Search products in the account associated with your API key. Supports text search, inventory and price filters, variant attributes, catalogs, collections, sorting and facet counts. Requires products:read. The request and response use camelCase.
Parameters
All parameters are optional. Send {} to list active products across the account's warehouses. Do not send accountId: the account comes from the authenticated key.
| Parameter | Meaning and default |
|---|---|
query | Text search; default "*" matches all. Searches name, SKU, description, indexed content and locations. This is not an exact barcode lookup. |
warehouseId | Restrict to one warehouse. Omit to search all warehouses in the account. |
productCategoryName | Exact category name, for example "Clothing". |
measurement | Exact measurement value. |
productId | Restrict to a product ID. Without an explicit status or catalog, this lookup does not apply the default active-only filter. |
productStatus | Normally defaults to "Active". Indexed product statuses are "Active" and "Inactive" (case-sensitive). Catalog and collection searches only accept active products. |
salesCatalogId | Active sales catalog belonging to this account; independent of warehouse. |
collectionId | Product collection belonging to this account. Can combine with a catalog. |
filter | Additional OData conditions; examples below. Field names inside this string are PascalCase and case-sensitive. |
orderBy | Sort field and direction, for example "ProductName asc", "Available desc", "Price1 asc" or "UpdatedAt desc". Omit for search relevance. |
facets | Fields whose matching value counts you want, for example ["ProductCategoryName,count:50", "VariantAttributeValues"]. Counts do not add filters automatically. |
pageNumber | Page starting at 1; default 1. |
pageSize | Results per page, 1–100; default 20. |
Filters
Use numeric comparisons eq, ne, gt, ge, lt, le; combine conditions with and, or, not and parentheses. Strings use single quotes; escape a quote by doubling it, for example 'Men''s clothing'. Use the dedicated parameters for account, warehouse, status and product restrictions.
| Need | Example filter |
|---|---|
| Available inventory | Available gt 0 |
| Out of stock | Available le 0 |
| Minimum physical stock | Stock ge 10 |
| Price list range | Price1 ge 5000 and Price1 le 50000 |
| Base price range | PriceBase ge 5000 and PriceBase le 50000 |
| Category ID | ProductCategoryId eq 'category-id' |
| Products with variants | HasVariants eq true |
| Missing images | HasImage eq false |
| Raw materials | IsRawMaterial eq true |
| Serial or optional tracking | IncludesSerials eq true and IncludesOptionals eq false |
| Variant attribute | VariantAttributeValues/any(v: v eq 'Color:Rojo') |
| Feature | FeatureKeys/any(f: f eq 'Material:Algodón') |
| Custom field | CustomFieldKeys/any(f: f eq 'proveedor:sony') |
| With discounts | DiscountKeys/any() |
| Changed since a date | UpdatedAt ge 2026-10-01T00:00:00Z |
Collection filters match products. A variant-attribute filter selects matching products; it does not trim the returned variants to that attribute. Catalog and collection memberships do restrict the returned variants. Stock and price filters apply to the indexed document, not to an individual matching variant.
Examples
Search available products with a price range and category counts:
{ "query": "shirt", "warehouseId": "warehouse-id", "filter": "Available gt 0 and Price1 ge 5000 and Price1 le 50000", "orderBy": "ProductName asc", "facets": ["ProductCategoryName,count:50", "VariantAttributeValues"], "pageNumber": 1, "pageSize": 20}Discover variant values and features:
{ "query": "*", "filter": "HasVariants eq true", "facets": ["VariantAttributeValues,count:100", "FeatureKeys,count:50"]}Restrict a catalog to a collection and warehouse:
{ "salesCatalogId": "catalog-id", "collectionId": "collection-id", "warehouseId": "warehouse-id", "orderBy": "ProductName asc"}Facets and catalogs
Useful facets include ProductCategoryName, WarehouseId, Measurement, VariantAttributeNames, VariantAttributeValues, FeatureKeys, CustomFieldKeys and DiscountKeys. Request count:N to control the number of returned values. Apply a selection by issuing another request with a filter, such as ProductCategoryName eq 'Clothing'.
With salesCatalogId or collectionId, allowed facets are ProductCategoryName, WarehouseId, Measurement, VariantAttributeValues, FeatureKeys, CustomFieldKeys and References. Allowed sort fields are ProductName, PriceBase, Price1–Price10, TotalSales, Available, Stock and Weight. An unavailable catalog or collection returns an empty page. Facet counts and filtering use the indexed document's full variant aggregates, even when membership limits returned variants.
Reading results
The response contains results, totalCount, pageNumber, pageSize, totalPages and facets. Each result is a product/warehouse document. Without warehouseId, the same product can appear in multiple warehouses. Use productId for product operations; id identifies the search document.
Results include stock, reserved, available, prices (base, price1–price10), variants, taxes and discounts. Variants include productVariantId, their stock, attributes and variantPrices. Facet keys preserve Search field names such as ProductCategoryName.
Synchronization
New products and inventory changes are indexed asynchronously and may take a short interval to appear. There is no guaranteed one-second maximum. An empty result does not prove a product was not created; use GET by product ID to check a recent write. Full index rebuilds can temporarily return partial or empty results.
Header Parameters
Your API Key for authentication
Request Body
application/json
Optional search parameters in camelCase. Use {} to list active products. See the parameter table and examples below.
TypeScript Definitions
Use the request body type in TypeScript.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/v1/products/search" \ -H "X-Api-Key: string" \ -H "Content-Type: application/json" \ -d '{}'{ "totalCount": 0, "pageNumber": 0, "pageSize": 0, "totalPages": 0, "results": [ { "id": "string", "accountId": "string", "organizationId": "string", "warehouseId": "string", "productId": "string", "hasVariants": true, "locationName": "string", "stock": 0.1, "reserved": 0.1, "available": 0.1, "minStock": 0.1, "variants": [ { "warehouseProductId": "string", "productVariantId": "string", "variantName": "string", "variantSku": "string", "locationName": "string", "variantAttributes": [ { "name": "string", "value": "string" } ], "stock": 0.1, "reserved": 0.1, "available": 0.1, "minStock": 0.1, "variantImage": { "id": "string", "url": "string", "thumbnailUrl": "string" }, "variantPrices": { "base": 0, "price1": 0, "price2": 0, "price3": 0, "price4": 0, "price5": 0, "price6": 0, "price7": 0, "price8": 0, "price9": 0, "price10": 0 }, "updatedAt": "2019-08-24T14:15:22Z" } ], "productName": "string", "productSku": "string", "productImages": [ { "id": "string", "url": "string", "thumbnailUrl": "string" } ], "productStatus": "string", "productCategoryId": "string", "productCategoryName": "string", "controlInventory": true, "prices": { "base": 0, "price1": 0, "price2": 0, "price3": 0, "price4": 0, "price5": 0, "price6": 0, "price7": 0, "price8": 0, "price9": 0, "price10": 0 }, "variantAttributeNames": [ "string" ], "variantAttributeValues": [ "string" ], "variantCombinations": [ "string" ], "attachments": [ { "name": "string", "type": "string", "url": "string", "category": "string", "sizeInBytes": 0, "mimeType": "string", "description": "string" } ], "includesSerials": true, "serials": [ "string" ], "includesOptionals": true, "optionals": [ { "id": "string", "name": "string", "minSelection": 0, "maxSelection": 0, "items": [ { "id": "string", "name": "string", "price": 0.1, "image": "string", "relatedProductId": "string", "relatedProductVariantId": "string", "relatedProductQuantity": 0, "maxSelection": 0 } ] } ], "createdAt": "2019-08-24T14:15:22Z", "updatedAt": "2019-08-24T14:15:22Z", "taxes": [ { "id": "string", "name": "string", "value": 0.1, "isInclude": true, "tributeType": "string" } ], "discounts": [ { "id": "string", "name": "string", "percentage": 0.1, "startDate": "2019-08-24T14:15:22Z", "endDate": "2019-08-24T14:15:22Z" } ], "totalSales": 0.1, "isRawMaterial": true, "customFieldKeys": [ "string" ], "references": [ "string" ], "measurement": "string", "weight": 0, "width": 0, "length": 0, "height": 0 } ], "facets": { "property1": [ { "value": "string", "count": 0 } ], "property2": [ { "value": "string", "count": 0 } ] }}Update product PATCH
Partially update a product in the account associated with your API key. Send at least one non-null supported field: name, description, sku, code, base_price, price, measurement, category_id, custom_category_id, control_inventory, available_online or status. Status accepts only active (reactivate) or disabled (deactivate), exactly lowercase; deletion states and other values are rejected. This changes the product status without deleting it or reversing stock. Omitted/null fields keep their stored values; zero and false are explicit changes. Empty text clears description, SKU, code or measurement; name and category IDs cannot be empty. Account and product ID cannot be changed in the body. Relations, inventory, calculated costs and metrics are not editable through this endpoint. Products loads the stored aggregate and reuses its validations, recalculations and product.updated publication. Changing base_price applies existing cost rules; this does not record a purchase. Updates become visible in search asynchronously.
Update stock POST
Add or remove stock for products and variants in the authenticated account. Send updates with warehouse_id, product_id, action (add/remove), origin and a positive quantity. All operations must use the same warehouse. For a variant, also send product_variant_id from the product's variants response; keep product_id as the owning product ID. Omitted or null product_variant_id uses the existing product-level operation. The response includes product_variant_id for each returned stock record. This operation is not idempotent; reconcile actual stock after an uncertain result before retrying. For origin purchase, supply both unit_cost (unit cost with taxes) and unit_cost_base (unit cost without taxes). Both must be finite and non-negative; zero is explicit, omission/null returns 400 for purchases. For other origins the pair is optional, but supplying one requires both. Products applies the existing last-purchase and weighted-average rules to the product or variant; cost is per unit, not the line total.