Products

Daily or weekly sales series of one product

GET
/v1/products/{productId}/series

Returns how a product's net sales, units, orders, cost and margin evolved, day by day (granularity=day) or in 7-day buckets (granularity=week), with the previous period of the same length aligned point by point for comparison.

  • Weekly buckets count 7 days from dateFrom, not calendar weeks; the last one may be shorter.
  • Days without sales are returned as zero.
  • Cost and margin follow the listing rule: they are null when the sale value or cost is incomplete.
  • Data can take up to 30 minutes to reflect updates.

Authorization

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Path Parameters

productId*string

Parent product id, in the shape its platform publishes: a VTEX identifier (1234567) or a Shopify GID (gid://shopify/Product/10417518674198), which carries slashes and must be percent-encoded in the path. The value is the same productId the listing returned, forwarded opaquely. A product absent from the catalog but present in sales or in the entry cohort is still addressable.

Match^[A-Za-z0-9._~+@:/-]{1,256}$
Lengthlength <= 256

Query Parameters

organizationId*string
Formatuuid
integrationId*string

Store identifier: the sourceIntegrationId returned by GET /v1/products/integrations. Do not use the VTEX App Key.

Formatuuid
dateFrom?string

Defaults to 29 days before dateTo.

Formatdate
dateTo?string

Defaults to today.

Formatdate
granularity?string
Default"day"
Value in"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.

Formatuuid

Response Body

Series of the product. no_base still returns every bucket, with zeros.

application/json
  1. response
state*string
Value in"ready""no_base""stale"
reason*|
Value innull"no_period_sales""stale_source"
asOf*|
Formatdate-time
integrationId*string
productId*string
granularity*string
Value in"day""week"
bucketDays*integer
Value in17
period*

Window a block actually measured, reported when it is not the requested period. Read from the returned rows, so it is a fact rather than a computed claim.

periodApplied*

Which period the block actually measured. basis: 'requested': the block used dateFrom/dateTo, so its numbers match the selected days. basis: 'source_window': the block ignores the requested period and uses a rolling window of its own, reported in window. Always present, whatever the block's state, and not a sign of degradation.

data*array<>
previous*|

The window of the same length immediately before period, for the "Período anterior" legend. Null only when that read failed; the current series is published either way.

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      }    ]  }}