Produtos consolidados
Retorna uma linha por produto com vendas, margem, estoque, devoluções e métricas de recompra do período, além dos totais por categoria em categories.
- Métricas de venda seguem
dateFrom/dateTo; catálogo, status e estoque mostram a foto mais recente. - Valores indisponíveis vêm como
null, com o motivo emndReasons— por exemplo, a margem fica oculta quando falta o custo de alguma unidade. - LTV e recompra de 180 dias consideram só os clientes que já completaram 180 dias desde a primeira compra;
matureEntryCustomerseentryCustomersmostram quantos são. - Se você já consulta
GET /v1/products/categories, envieincludeCategories=falsepara receber a listagem mais rápido.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringuuidintegrationId*stringIdentificador da loja: o sourceIntegrationId retornado por GET /v1/products/integrations. Não use a App Key da VTEX — ela pode ser trocada e a mesma chave pode estar ligada a mais de uma loja ou organização.
uuiddateFrom?stringdatedateTo?stringdatesearch?stringlength <= 120categoryId?stringDescontinuadoObsoleto: prefira categoryIds. Corresponde a qualquer nível do caminho de categorias da VTEX, portanto um departamento também retorna os produtos de seus descendentes.
categoryIds?array<>Filtra por uma ou mais categorias. Um produto entra quando pertence a QUALQUER uma delas, diretamente ou por uma subcategoria — escolher um departamento traz também os produtos das subcategorias. Envie separados por vírgula (categoryIds=1,12) ou repetidos (categoryIds=1&categoryIds=12); valores vazios e duplicados são ignorados. Até 50 ids distintos (contando também o categoryId, se enviado), cada um com até 50 caracteres; acima disso a resposta é 400.
items <= 50status?string"all""all""active""inactive"minNetSales?numberLimite mínimo (inclusivo) de netSales — faturamento no período, na moeda da loja. Não pode ser maior que maxNetSales. Filtra as linhas, a pagination e os totais de categories.
maxNetSales?numberLimite máximo (inclusivo) de netSales — faturamento no período, na moeda da loja. Não pode ser menor que minNetSales. Filtra as linhas, a pagination e os totais de categories.
minMarginTotal?numberLimite mínimo (inclusivo) de marginTotal — margem em moeda. Produtos com margem N/D (falta de valor de venda ou de custo) nunca entram na faixa. Não pode ser maior que maxMarginTotal. Filtra as linhas, a pagination e os totais de categories.
maxMarginTotal?numberLimite máximo (inclusivo) de marginTotal — margem em moeda. Produtos com margem N/D (falta de valor de venda ou de custo) nunca entram na faixa. Não pode ser menor que minMarginTotal. Filtra as linhas, a pagination e os totais de categories.
maxAvailableStock?numberLimite máximo (inclusivo) de availableStock — estoque disponível em unidades. Produtos com estoque N/D (nem todos os SKUs monitorados) nunca entram na faixa. Não pode ser menor que minAvailableStock. Filtra as linhas, a pagination e os totais de categories.
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?stringMétricas a retornar, separadas por vírgula (ex.: netSales,marginTotal). Identificação, estado, cobertura e motivos de N/D sempre vêm. Uma métrica desconhecida retorna 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.
uuidLinhas de produtos paginadas
application/json- response
data*array<>categories*array<>Agrupamentos para cada nível de categoria presente no conjunto filtrado, calculados fora da paginação. Os numeradores das métricas são recalculados por nível, nunca somados a partir da página.
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 }}