Produtos

Série diária ou semanal de vendas de um produto

GET
/v1/products/{productId}/series

Retorna a evolução de faturamento, unidades, pedidos, custo e margem de um produto, dia a dia (granularity=day) ou em blocos de 7 dias (granularity=week), com o período anterior de mesma duração alinhado ponto a ponto para comparação.

  • Os blocos semanais contam 7 dias a partir de dateFrom, não semanas do calendário; o último pode ser mais curto.
  • Dias sem venda aparecem com zero.
  • Custo e margem seguem a regra da listagem: vêm null quando falta valor de venda ou custo.
  • Os dados podem levar até 30 minutos para refletir atualizações.

Autorização

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Parâmetros de path

productId*string

ID do produto pai, no formato publicado pela sua plataforma: um identificador VTEX (1234567) ou um GID da Shopify (gid://shopify/Product/10417518674198), que contém barras e deve ser codificado com percent-encoding no caminho. O valor é o mesmo productId retornado pela listagem, repassado sem alterações. Um produto ausente do catálogo, mas presente nas vendas ou na coorte de entrada, continua endereçável.

Padrão (regex)^[A-Za-z0-9._~+@:/-]{1,256}$
Tamanholength <= 256

Parâmetros de query

organizationId*string
Formatouuid
integrationId*string

Identificador da loja: o sourceIntegrationId retornado por GET /v1/products/integrations. Não use a App Key da VTEX.

Formatouuid
dateFrom?string

Padrão: 29 dias antes de dateTo.

Formatodate
dateTo?string

Padrão: hoje.

Formatodate
granularity?string
Padrão"day"
Valor em"day""week"
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.

Formatouuid

Corpo da resposta

Série do produto. no_base ainda retorna todos os buckets, com zeros.

application/json
  1. response
state*string
Valor em"ready""no_base""stale"
reason*|
Valor emnull"no_period_sales""stale_source"
asOf*|
Formatodate-time
integrationId*string
productId*string
granularity*string
Valor em"day""week"
bucketDays*integer
Valor em17
period*

Janela que um bloco efetivamente mediu, informada quando não é o período solicitado. Lida das linhas retornadas, portanto é um fato e não uma afirmação calculada.

periodApplied*

Qual período o bloco realmente mediu. basis: 'requested': o bloco usou dateFrom/dateTo, então os números correspondem aos dias escolhidos. basis: 'source_window': o bloco ignora o período pedido e usa uma janela móvel própria, informada em window. Vem sempre, qualquer que seja o state do bloco, e não indica degradação.

data*array<>
previous*|

A janela de mesmo tamanho imediatamente anterior a period, para a legenda "Período anterior". Nula somente quando essa leitura falhou; a série atual é publicada de qualquer forma.

curl -X GET "https://example.com/v1/products/string/series?organizationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&integrationId=497f6eca-6276-4993-bfeb-53cbbbba6f08&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "state": "ready",  "reason": null,  "asOf": "2019-08-24T14:15:22Z",  "integrationId": "string",  "productId": "string",  "granularity": "day",  "bucketDays": 1,  "period": {    "from": "2019-08-24",    "to": "2019-08-24"  },  "periodApplied": {    "basis": "requested",    "granularity": "day"  },  "data": [    {      "index": 0,      "from": "2019-08-24",      "to": "2019-08-24",      "netSales": 0,      "netUnits": 0,      "orders": 0,      "cogs": 0,      "marginTotal": 0,      "marginNdReason": null    }  ],  "previous": {    "state": "ready",    "reason": null,    "window": {      "from": "2019-08-24",      "to": "2019-08-24"    },    "data": [      {        "index": 0,        "from": "2019-08-24",        "to": "2019-08-24",        "netSales": 0,        "netUnits": 0,        "orders": 0,        "cogs": 0,        "marginTotal": 0,        "marginNdReason": null      }    ]  }}