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.
Paginated 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"{ "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 }}