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:
- Open the Pages module in the admin panel.
- Create pages of the Catalog type. These become your product categories.
- 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
limityou pass. With full read access,limitworks 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:
| sortKey | What It Does | Example Use |
|---|---|---|
| price | Sort by price | Show cheapest first |
| date | Sort by creation date | Show newest products |
| title | Sort alphabetically | A-Z product list |
| position | Custom order (default) | Hand-picked order from admin |
| id | Sort by ID | Technical sorting |
| status | Sort by product status | Order 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
| Method | Description | Use Case |
|---|---|---|
| getProducts() | Get all products with filtering/sorting | Main catalog page |
| getProductById() | Get single product by ID | Product detail page |
| getProductsByPageId() | Get products from category by page ID | Category page |
| getProductsByPageUrl() | Get products from category by page URL | Category page by URL |
| getRelatedProductsById() | Get related/similar products | "You may also like" section |
| searchProduct() | Search products by query | Search functionality |
| getProductsCount() | Get total products count | Pagination info |
| getProductsCountByPageId() | Get products count by category ID | Category pagination |
| getProductsCountByPageUrl() | Get products count by category URL | Category pagination |
| getProductBlockById() | Get the blocks attached to a product | Product content blocks |
| getProductsEmptyPage() | Get products that have no category | Uncategorized products |
| getProductsPriceByPageUrl() | Get product prices of a category by page URL | Price list, price-range slider |
| getProductsByIds() | Get products by a list of IDs | Cart, wishlist, comparison |
| getProductsByVectorSearch() | Semantic (vector) search for products | AI-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
userQueryshape depends on the method. The fields above are the common base (IProductsQueryBase) used bygetProducts,getProductsByPageId,getProductsByPageUrlandgetProductsEmptyPage.getRelatedProductsByIdalso acceptsstatusMarker,templateMarkerandrelationMode('global'|'local').getProductsPriceByPageUrlalso acceptsstatusMarkerand has nosortKey.getProductsByIdsaccepts onlysignPrice. Filtering (attributeMarker,conditionMarker,conditionValue) goes in the request body, not inuserQuery; 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.
| Marker | Meaning | Example |
|---|---|---|
| eq | Equal | color = "red" |
| neq | Not equal | category ≠ "archived" |
| in | Contains (case-insensitive substring match) | brand contains "app" |
| nin | Does not contain (case-insensitive substring match) | brand does not contain "fake" |
| mth | Greater than | price > 100 |
| lth | Less than | price < 50 |
| exs | Exists (has value) | Has description |
| nexs | Does not exist | No image |
| pat | Matches 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 value | currency matches "s" (finds "usd") |
| same | Has the same value as at least one other product. conditionValue is ignored | products that share a price |
| same_part | Has 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 whole | SKUs "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:
- Fetch products with
signPriceset to your order storage marker (for example"orders"). - Every returned product now has a
signedPricefield: a signed token that encodes the locked price. - Send the
signedPricetoken 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.
Related
- OneEntry Admin Panel - Catalog: admin panel documentation
- Pages Module: create catalog categories (Catalog type pages)
- AttributesSets Module: custom product fields and attributes
- Templates Module: product display templates
- Blocks Module: reusable product content blocks
- Orders Module: handle product orders