Skip to main content

Products

Fetch, filter and search catalog products.

More information about the Catalog in the OneEntry admin panel: https://doc.oneentry.cloud/docs/category/catalog (opens in a new tab)


The Products module (the Catalog) retrieves, filters, searches and sorts products for an online store or a media collection. You manage the catalog in the OneEntry admin panel under Catalog > Products, and your app fetches products at runtime, so a price or attribute change in the admin goes live without a redeploy.

The Catalog isn't limited to e-commerce: it also works for media galleries, portfolios, document libraries and other content collections.

Quickstart​

Initialize the module from defineOneEntry:


const { } = defineOneEntry(
, {
}
);

Fetch a page of products and read their fields:

// Fetch the first 20 products (empty body = no filters).
const products = await Products.getProducts([], "en_US", { limit: 20 });
if ('statusCode' in products) throw new Error(products.message);
const { items, total } = products;

console.log(`Loaded ${items.length} of ${total} products`);

items.forEach((product) => {
console.log(product.id, product.localizeInfos.title, product.price);
});

Most listing methods take the same arguments: an optional filter body, a langCode and an optional userQuery for pagination and sorting. See Parameters for the full list.

Products and categories​

A product is a catalog entity (IProductsEntity) with:

  • basic info: localizeInfos (title and other localized fields), sku, price;
  • images: product photos and galleries, stored as attributes;
  • custom attributes in attributeValues: brand, material, size, color, variants, stock and any other fields you define;
  • per-language content.

The SDK has no fixed product types. Variants, options, downloads, bundles and any other structure are modeled with the custom attributes you configure for the catalog.

The catalog organizes products with:

  • Categories: sections of the catalog, which are pages of the Catalog type created in the Pages module.
  • Product statuses: filter conditions on top of attribute filters, such as "in stock" or "sale".
  • Product links: connect products by attribute criteria, e.g. all black phones.
  • Product filters: quick search by preset filter criteria.
  • Custom attributes: brand, size, color, material and so on.

Example hierarchy:

Electronics
├─ Smartphones
│ ├─ iPhone 15 Pro
│ └─ Samsung Galaxy S24
└─ Laptops
├─ MacBook Pro
└─ Dell XPS

Clothing
├─ T-Shirts
└─ Jeans

Setting up categories​

Categories are pages of the Catalog type, created in the Pages module. Create them before you add products:

  1. Open the Pages module in the admin panel.
  2. Create pages of the Catalog type. These become your product categories.
  3. Add products to them under Catalog > Products.

The Catalog section of the admin panel also has bulk Catalog Upload, Product Filters, Product Links, Product Statuses and per-catalog Settings.

Pagination​

Page through results with limit and offset instead of loading everything at once:

offset = (pageNumber - 1) * limit

Record limit: if the user group's permission for a method allows only restricted reading, the API returns at most the number of records set in the project settings (10 by default), whatever limit you pass. With full read access, limit works as usual. See Module permissions.

To build a "Load more" button, increase offset by limit on each click and append the new items to the list. Use total to know when to stop. When total is 0, render an empty state.

Sorting​

Pass sortKey and sortOrder in userQuery:

sortKeyWhat It DoesExample Use
priceSort by priceShow cheapest first
dateSort by creation dateShow newest products
titleSort alphabeticallyA-Z product list
positionCustom order (default)Hand-picked order from admin
idSort by IDTechnical sorting
statusSort by product statusOrder by product status

sortOrder is ASC (ascending) or DESC (descending, the default). For a "New arrivals" section, sort by creation date: userQuery: { sortKey: "date", sortOrder: "DESC" }.

Filtering​

Filters go in the request body (an array of IFilterParams), not in userQuery. Each condition has an attributeMarker, a conditionMarker (eq, neq, in, nin, mth, lth, exs, nexs, pat, same, same_part) and a conditionValue. Put several conditions in the array to narrow the results: a product must match all of them. in and nin mean "contains" and "does not contain" (a case-insensitive substring match), and conditionValue is a single string or number, not a list. The full condition reference is in Parameters.

const products = await Products.getProducts(
[
{ attributeMarker: "price", conditionMarker: "mth", conditionValue: 100 },
{ attributeMarker: "brand", conditionMarker: "eq", conditionValue: "apple" },
],
"en_US",
);
if ('statusCode' in products) throw new Error(products.message);
const { items } = products;

To show products from several categories, pass their page URLs in pageUrls of a filter entry, for example { pageUrls: ["smartphones", "laptops"] }. Set isNested: true to include their subcategories.

Variants such as sizes and colors live in the product's attributeValues. Their structure is whatever attribute set you configured for the catalog.


Methods​

MethodDescriptionUse Case
getProducts()Get all products with filtering/sortingMain catalog page
getProductById()Get single product by IDProduct detail page
getProductsByPageId()Get products from category by page IDCategory page
getProductsByPageUrl()Get products from category by page URLCategory page by URL
getRelatedProductsById()Get related/similar products"You may also like" section
searchProduct()Search products by querySearch functionality
getProductsCount()Get total products countPagination info
getProductsCountByPageId()Get products count by category IDCategory pagination
getProductsCountByPageUrl()Get products count by category URLCategory pagination
getProductBlockById()Get the blocks attached to a productProduct content blocks
getProductsEmptyPage()Get products that have no categoryUncategorized products
getProductsPriceByPageUrl()Get product prices of a category by page URLPrice list, price-range slider
getProductsByIds()Get products by a list of IDsCart, wishlist, comparison
getProductsByVectorSearch()Semantic (vector) search for productsAI-powered search

Parameters​

Most methods accept a set of query parameters called userQuery. Any parameter you don't pass takes its default. Some methods also accept a body for filtering: pass an empty array, or nothing, if you don't need filters (getProductsEmptyPage() takes an object with a filter array instead).


const = {
: 0,
: 30,
sortOrder: ,
sortKey: ,
signPrice: ,
}

Note: the userQuery shape depends on the method. The fields above are the common base (IProductsQueryBase) used by getProducts, getProductsByPageId, getProductsByPageUrl and getProductsEmptyPage. getRelatedProductsById also accepts statusMarker, templateMarker and relationMode ('global' | 'local'). getProductsPriceByPageUrl also accepts statusMarker and has no sortKey. getProductsByIds accepts only signPrice. Filtering (attributeMarker, conditionMarker, conditionValue) goes in the request body, not in userQuery; see below.

Schema

offset: number
Number of records to skip. Default: 0.
example: 0

limit: number
Maximum number of records to return. Default: 30.
example: 30

sortKey: string
Field to sort by. When not set, products are sorted by position.
Available values: id, position, title, date, price, status

sortOrder: string
Sort order: DESC or ASC. Default: DESC.
example: "DESC"

signPrice: string
Order storage marker for price fixing. If the parameter is set, the price is fixed for a certain time (see the Fixing the price section below).
example: "orders"

Method-specific fields: statusMarker (getRelatedProductsById, getProductsPriceByPageUrl) and templateMarker (getRelatedProductsById): string | null, default null. relationMode (getRelatedProductsById): 'global' | 'local', default 'global'.

Use conditions to find specific products data:

attributeMarker: The text identifier of the indexed attribute by which values are filtered. conditionMarker: The type of condition to apply to the attribute value.

MarkerMeaningExample
eqEqualcolor = "red"
neqNot equalcategory ≠ "archived"
inContains (case-insensitive substring match)brand contains "app"
ninDoes not contain (case-insensitive substring match)brand does not contain "fake"
mthGreater thanprice > 100
lthLess thanprice < 50
exsExists (has value)Has description
nexsDoes not existNo image
patMatches a regular-expression pattern where each * stands for exactly one character and _ for a space. With search indexing on, the pattern must match the whole valuecurrency matches "s" (finds "usd")
sameHas the same value as at least one other product. conditionValue is ignoredproducts that share a price
same_partHas the same value as another product once the last segments are cut off. conditionValue is delimiter|count (default -|2); a value with count or fewer segments is compared wholeSKUs "ABC-1-S" and "ABC-1-M" share "ABC"

conditionValue: The value to compare against.


Fixing the price (signPrice)​

When you fetch products, you can pass an optional signPrice parameter in userQuery. The recommendation methods of the Blocks module take it as an argument too. Its value is the marker of an order storage, and it tells the server to lock the returned price for a limited time.

Prices can change while a customer shops: a discount starts, or an admin edits a price. With signPrice, the price shown in the catalog or cart is the price charged at checkout. Use it whenever prices feed into a cart or checkout.

How it works:

  1. Fetch products with signPrice set to your order storage marker (for example "orders").
  2. Every returned product now has a signedPrice field: a signed token that encodes the locked price.
  3. Send the signedPrice token back when you create the order, and the server honors the fixed price.

const products = await Products.([], "en_US", {
signPrice: "orders"
});
if ('statusCode' in products) throw new Error(products.message);
const { items } = products;

const signedPrice = items[0].;
// "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."

The token is consumed by createOrder(). For where to take it and how to pass it, see Fixed product price (signedPrice) in the Orders module.