VTEX orders summary
Aggregated totals for VTEX orders over the given period. status filters the VTEX status column directly (e.g. invoiced, canceled). groupBy dimensions: payment_method, utm_source, utm_campaign (order columns) and product (joins vtex_order_items; totalRevenue = selling_price × quantity, totalOrders = distinct orders containing the product; the (outros) row reports only key and totalRevenue — its totalOrders, avgTicket and uniqueCustomers are null). An unsupported dimension returns 400 listing the valid ones. Customers are resolved through the order's customer record (user_profile_id): totalCustomers counts orders with an identified customer and uniqueCustomers the distinct buyers.
ClientIdAuthClientSecretAuthx-client-id<token>Client ID
x-client-secret<token>Client secret
organizationId*stringOrganization identifier (required)
dateStart*stringPeriod start (YYYY-MM-DD), filters creation_date
datedateEnd*stringPeriod end (YYYY-MM-DD), filters creation_date (whole day included)
dateintegrationName?stringRestrict to a single store integration
status?stringVTEX order status (e.g. invoiced, canceled). When omitted, canceled/cancellation-requested orders and orders without authorized_date are excluded by default; passing it replaces that default.
groupBy?stringBreak the summary down by one dimension. VTEX supports: payment_method, utm_source, utm_campaign, product.
"payment_method""utm_source""utm_campaign""product"Orders summary (with groupBy echo and groups when requested)
application/json- response
totalOrders?integertotalRevenue?numberfloatavgTicket?numberfloattotalCustomers?integeruniqueCustomers?integerperiod?platform?string"vtex""shopify""tray"integrationName?string|nullgroupBy?stringEcho of the requested dimension. Present only when groupBy was sent.
"payment_method""utm_source""utm_campaign""product""source_name"groups?array<>Present only when groupBy was sent. Top-20 groups ordered by totalRevenue desc, plus an '(outros)' row aggregating the remainder when one exists. Null/blank dimension values are bucketed as '(sem valor)'. The '(sem valor)' group, when it has rows, is always returned as its own explicit group — even outside the top-20 — and its numbers are excluded from '(outros)'. On order-grain dimensions (payment_method, utm_source, utm_campaign, source_name) the '(outros)' row is complete — its uniqueCustomers is a clamped lower-bound approximation (distinct counts do not subtract across groups). For groupBy=product (item grain) the '(outros)' row carries ONLY key and totalRevenue: totalOrders, avgTicket and uniqueCustomers are null, because per-product order counts overlap (one order counts once per product it contains) and the remainder's counts cannot be derived; the '(sem valor)' group at item grain is a normal group with full metrics.
curl -X GET "https://example.com/v1/vtex/orders/summary?organizationId=org_123&dateStart=2019-08-24&dateEnd=2019-08-24"{ "totalOrders": 847, "totalRevenue": 152340.5, "avgTicket": 179.86, "totalCustomers": 612, "uniqueCustomers": 489, "period": { "start": "2026-06-01", "end": "2026-06-23" }, "platform": "vtex", "integrationName": "lupo-vtex", "groupBy": "payment_method", "groups": [ { "key": "creditCard", "totalOrders": 412, "totalRevenue": 80231.4, "avgTicket": 194.74, "uniqueCustomers": 322 } ]}