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