Products

List consolidated product categories

GET
/v1/products/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 page or sortBy, because the values are the same on any page or sort order.

Authorization

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Query Parameters

organizationId*string
Formatuuid
integrationId*string

Store 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.

Formatuuid
dateFrom?string
Formatdate
dateTo?string
Formatdate
search?string
Lengthlength <= 120
categoryId?stringDeprecated

Deprecated: 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.

Itemsitems <= 50
status?string
Default"all"
Value in"all""active""inactive"
minNetSales?number

Inclusive 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?number

Inclusive 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?number

Inclusive 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?number

Inclusive 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.

minMarginAverage?number

Inclusive lower bound on marginAverage — margin % as a decimal: 0.3 = 30%. Products whose margin is N/D never match. Must not exceed maxMarginAverage. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.

maxMarginAverage?number

Inclusive upper bound on marginAverage — margin % as a decimal: 0.3 = 30%. Products whose margin is N/D never match. Must not be below minMarginAverage. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.

minAvailableStock?number

Inclusive lower bound on availableStock — available stock in units. Products whose stock is N/D (not every SKU monitored) never match. Must not exceed maxAvailableStock. Each category only adds up the products inside every range — the same products GET /v1/products returns for these bounds.

maxAvailableStock?number

Inclusive 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?string

Metrics to return, comma-separated (e.g. netSales,marginTotal). Identity, state, coverage and N/D reasons are always returned. An unknown metric returns 400.

gtmMotionId?string

GTM 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.

Formatuuid

Response Body

Category rollups and the applied metric contract

application/json
  1. 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*|
Formatdate-time
selectedColumns*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&gtmMotionId=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"  ]}