E-commerce Summary

Tray orders summary

GET
/v1/tray/orders/summary

Aggregated totals for Tray orders over the given period. status filters the Tray status column directly. groupBy dimensions: payment_method (order column) and product (joins tray_products; totalRevenue = price × quantity, totalOrders = distinct orders; the (outros) row reports only key and totalRevenue — its totalOrders, avgTicket and uniqueCustomers are null) and main_product (V4MOS-2863: each order lands in its largest product only, by price × quantity summed per product name, ties to the first name; an order without items reads (sem valor). Order grain, so totalOrders = orders, totalRevenue = order total with shipping, the groups add up to the summary and the (outros) row is complete). Other dimensions return 400.

Authorization

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Query Parameters

organizationId*string

Organization identifier (required)

dateStart*string

Period start (YYYY-MM-DD), filters date

Formatdate
dateEnd*string

Period end (YYYY-MM-DD), filters date (whole day included)

Formatdate
integrationName?string

Restrict to a single store integration

status?string

Tray order status. When omitted, 'Cancelado' orders are excluded by default; passing it replaces that default.

groupBy?string

Break the summary down by one dimension. Tray supports: payment_method, product, main_product.

Value in"payment_method""product""main_product"
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. Any other GTM motion of the organization (V4MOS-2707) is answered with the orders of its stores only: the stores with an order in analytics.fct_transactions_by_gtm_motion for the motion, by the key the order facts give a store (vtex_orders.document_id, shopify_orders.store_key, tray_orders.store_key); a motion without a store answers zero orders. Not a UUID: 400. Not a live GTM motion of the organization: 403 GTM_MOTION_NOT_IN_ORGANIZATION.

Formatuuid
paymentStatus?"paid"

Narrow the summary to paid orders, on top of the validity default or of an explicit status: payment_date set, order_status_type not canceled/cancelled and no status label starting with 'cancelado' (the dbt sales fact, int_tray_order_sku_sales.is_invoiced). Echoed back as paymentStatus. Omitted, the summary is unchanged.

Value in"paid"

Response Body

Orders summary (with groupBy echo and groups when requested)

application/json
  1. response
totalOrders?integer
totalRevenue?number
Formatfloat
avgTicket?number
Formatfloat
totalCustomers?integer
uniqueCustomers?integer
period?
platform?string
Value in"vtex""shopify""tray"
integrationName?string|null
groupBy?string

Echo of the requested dimension. Present only when groupBy was sent.

Value in"payment_method""utm_source""utm_campaign""product""source_name""main_product"
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, main_product) 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.

paymentStatus?"paid"

Echo of the requested payment state. Present only when paymentStatus was sent: without it the totals count every order the validity default (or the explicit status) lets through, paid or not.

Value in"paid"
curl -X GET "https://example.com/v1/tray/orders/summary?organizationId=org_123&dateStart=2019-08-24&dateEnd=2019-08-24&gtmMotionId=019a5b2e-7c4d-7abc-8def-0123456789ab"
{  "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    }  ],  "paymentStatus": "paid"}