Products

List consolidated products

GET
/v1/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 in ndReasons — 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; matureEntryCustomers and entryCustomers show how many they are.
  • If you already call GET /v1/products/categories, send includeCategories=false to get the listing faster.

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. Filters the rows, pagination and the categories totals.

maxNetSales?number

Inclusive 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?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. Filters the rows, pagination and the categories totals.

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. Filters the rows, pagination and the categories totals.

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. Filters the rows, pagination and the categories totals.

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. Filters the rows, pagination and the categories totals.

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. Filters the rows, pagination and the categories totals.

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. Filters the rows, pagination and the categories totals.

sortBy?string
Default"netSales"
Value in"productName""grossSales""netSales""netUnits""averageTicket""marginAverage""marginTotal""newCustomers""recurringCustomers""ltv180""repurchaseRate180""ltvToDate""repurchaseRateToDate""entryCustomers""matureEntryCustomers""availableStock""daysOfStock""returnRate""updatedAt"
sortOrder?string
Default"desc"
Value in"asc""desc"
page?integer
Range1 <= value
Default1
pageSize?integer
Range1 <= value <= 100
Default25
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

Paginated product rows

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