List consolidated product categories
Returns the totals of each category (departments and subcategories) for the same selection as GET /v1/products: store, period, search, status, categories and metric ranges.
- Totals cover all filtered products, with no pagination: orders and customers are recounted (an order with several products counts once) and rates are recomputed from the totals.
- With metric ranges, each category only adds up the products inside every range; categories with no product in range are omitted.
- A department already includes its subcategories: do not add up different levels.
- Does not accept
pageorsortBy, because the values are the same on any page or sort order.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringuuidintegrationId*stringStore identifier: the sourceIntegrationId returned by GET /v1/products/integrations. Do not use the VTEX App Key — it can be rotated, and the same key can be linked to more than one store or organization.
uuiddateFrom?stringdatedateTo?stringdatesearch?stringlength <= 120categoryId?stringDeprecatedDeprecated: prefer categoryIds. Matches any level of the VTEX category path, so a department also returns the products of its descendants.
categoryIds?array<>Filters by one or more categories. A product matches when it belongs to ANY of them, directly or through a subcategory — choosing a department also returns the products of its subcategories. Send comma-separated (categoryIds=1,12) or repeated (categoryIds=1&categoryIds=12); blank values and duplicates are ignored. Up to 50 distinct ids (including categoryId, if sent), each up to 50 characters; above that the response is 400.
items <= 50status?string"all""all""active""inactive"minNetSales?numberInclusive lower bound on netSales — net sales in the period, in the store currency. Must not exceed maxNetSales. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.
maxNetSales?numberInclusive upper bound on netSales — net sales in the period, in the store currency. Must not be below minNetSales. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.
minMarginTotal?numberInclusive lower bound on marginTotal — margin in currency. Products whose margin is N/D (missing sale value or cost) never match. Must not exceed maxMarginTotal. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.
maxMarginTotal?numberInclusive upper bound on marginTotal — margin in currency. Products whose margin is N/D (missing sale value or cost) never match. Must not be below minMarginTotal. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.
maxAvailableStock?numberInclusive upper bound on availableStock — available stock in units. Products whose stock is N/D (not every SKU monitored) never match. Must not be below minAvailableStock. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.
columns?stringMetrics to return, comma-separated (e.g. netSales,marginTotal). Identity, state, coverage and N/D reasons are always returned. An unknown metric returns 400.
gtmMotionId?stringGTM motion of the organization (UUID), as listed by GET /v1/gtm-motions. Optional: without it, the response covers the organization's default GTM motion. The default motion is answered with the organization's data, the same numbers as when the parameter is omitted. Another GTM motion of the organization only sees its own stores (V4MOS-2707): a store belongs to a motion whole, so GET /v1/products/integrations lists only the motion's stores (none for a motion without a store) and a route that reads one store answers exactly as for the organization when integrationId is a store of the motion, and 404 GTM_MOTION_STORE_NOT_IN_MOTION otherwise. Not a UUID: 400. Not a live GTM motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.
uuidCategory rollups and the applied metric contract
application/json- response
All category rollups matching the filters, outside product pagination.
categories*array<>Rollups for every category level present in the filtered set, computed outside pagination. Metric numerators are recalculated per level, never summed from the page.
period*asOf*|date-timeselectedColumns*array<>availableColumns*array<>curl -X GET "https://example.com/v1/products/categories?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&categoryIds=1&categoryIds=12>mMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"{ "categories": [ { "integrationId": "497a18ca-284e-40c0-985d-f72be35d468e", "categoryId": "string", "categoryName": "string", "parentCategoryId": "string", "depth": 1, "inventoryState": "monitored", "inventoryFreshness": "fresh", "inventoryUpdatedAt": "2019-08-24T14:15:22Z", "cohortState": "no_base", "cohortWindowDays": 180, "entryCustomers": 0, "matureEntryCustomers": 0, "asOf": "2019-08-24T14:15:22Z", "grossSales": 0, "netSales": 0, "grossUnits": 0, "netUnits": 0, "averageTicket": 0, "marginAverage": 0, "marginTotal": 0, "newCustomers": 0, "recurringCustomers": 0, "ltv180": 0, "repurchaseRate180": 0, "ltvToDate": 0, "repurchaseRateToDate": 0, "cohortElapsedDaysAverage": 0, "availableStock": 0, "velocity30d": 0, "daysOfStock": 0, "returnRate": 0, "coverage": { "grossValue": 0, "cost": 0, "inventory": 0, "matureCohort": 0 }, "ndReasons": { "averageTicket": "string", "margin": "string", "averageMargin": "string", "daysOfStock": "string", "ltv180": "string", "repurchaseRate180": "string", "returnRate": null }, "cogs": 6200 } ], "period": { "from": "2019-08-24", "to": "2019-08-24" }, "asOf": "2019-08-24T14:15:22Z", "selectedColumns": [ "grossSales" ], "availableColumns": [ "grossSales" ]}