List consolidated products
Returns one row per product with the period's sales, margin, stock, returns and repurchase metrics, plus category totals in categories.
- Sales metrics follow
dateFrom/dateTo; catalog, status and stock show the latest snapshot. - Unavailable values come back as
null, with the reason inndReasons— for example, margin is withheld when some unit is missing its cost. - 180-day LTV and repurchase only count customers who have completed 180 days since their first purchase;
matureEntryCustomersandentryCustomersshow how many they are. - If you already call
GET /v1/products/categories, sendincludeCategories=falseto get the listing faster.
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. Filters the rows, pagination and the categories totals.
maxNetSales?numberInclusive upper bound on netSales — net sales in the period, in the store currency. Must not be below minNetSales. Filters the rows, pagination and the categories totals.
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. Filters the rows, pagination and the categories totals.
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. Filters the rows, pagination and the categories totals.
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. Filters the rows, pagination and the categories totals.
sortBy?string"netSales""productName""grossSales""netSales""netUnits""averageTicket""marginAverage""marginTotal""newCustomers""recurringCustomers""ltv180""repurchaseRate180""ltvToDate""repurchaseRateToDate""entryCustomers""matureEntryCustomers""availableStock""daysOfStock""returnRate""updatedAt"sortOrder?string"desc""asc""desc"page?integer1 <= value1pageSize?integer1 <= value <= 10025columns?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.
uuidPaginated product rows
application/json- response
data*array<>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<>pagination*curl -X GET "https://example.com/v1/products?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&categoryIds=1&categoryIds=12>mMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"{ "data": [ { "integrationId": "497a18ca-284e-40c0-985d-f72be35d468e", "productId": "string", "productName": "string", "stockPosition": { "state": "ready", "reason": "source_unavailable", "snapshotAt": "2019-08-24", "previousSnapshotAt": "2019-08-24", "availableStock": 0, "previousAvailableStock": 0, "inventoryState": "string", "previousInventoryState": "string", "stockDelta": 0, "stockDeltaReason": "source_unavailable", "previousDaysOfStock": 0, "previousDaysOfStockReason": "source_unavailable", "previousVelocity30d": 0 }, "imageUrl": "string", "sourceImageUrl": "string", "imageStatus": "mirrored", "categoryId": "string", "categoryName": "string", "categoryPath": [ { "id": "string", "name": "string" } ], "status": "active", "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 } ], "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" ], "pagination": { "page": 0, "pageSize": 0, "total": 0, "totalPages": 0 }}