Overview
Server-side order aggregation for VTEX, Shopify, and Tray
The E-commerce Summary API returns aggregated order totals for a store in a single call — no pagination. Metrics are computed from the orders at query time, so they reflect the latest data and accept any date range.
Available Endpoints
- getVTEX orders summary
/v1/vtex/orders/summaryAggregated totals for VTEX orders over the given period. - getShopify orders summary
/v1/shopify/orders/summaryAggregated totals for Shopify orders over the given period. - getTray orders summary
/v1/tray/orders/summaryAggregated totals for Tray orders over the given period. - getOrders by payment outcome and payment method
/v1/orders/payment-outcomesOrders CREATED in the period (creation day in UTC), one row per payment method chosen at checkout, each order in exactly one outcome: paid…
Response
Each endpoint returns:
totalOrders– number of orders in the periodtotalRevenue– summed order valueavgTicket–totalRevenue / totalOrders(0 when there are no orders)totalCustomers– orders with an identifiable customeruniqueCustomers– distinct customersperiod,platform,integrationNamegroupBy/groups– present only whengroupBywas sent: top-20 groups by revenue, each withkey,totalOrders,totalRevenue,avgTicket,uniqueCustomers. When a remainder exists, an(outros)remainder row appears with the same fields; 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). ForgroupBy=product, the(outros)row carries onlykeyandtotalRevenue—totalOrders,avgTicketanduniqueCustomersarenull(an order can span several products, so those counts cannot be derived for the remainder); the(sem valor)group itself still carries full metrics.
GTM motions
gtmMotionId is optional on every endpoint of this module. Without it, the response covers the organization's default GTM motion. List the motions, and see which one is the default, with GET /v1/gtm-motions.
Only the default GTM motion has data for now
These endpoints are not split by GTM motion yet. The default motion (or no gtmMotionId) answers with the organization's data, the same numbers as before; any other motion of the organization returns 422 with the code GTM_MOTION_DATA_NOT_AVAILABLE. A gtmMotionId that is not a UUID returns 400, and one that is not a motion of the organization returns 403 with the code GTM_MOTION_NOT_IN_ORGANIZATION, in the same body format as the 422, so you can tell it apart from a 403 of missing access.
Common Parameters
organizationId(required)dateStart/dateEnd(required, YYYY-MM-DD)integrationName– restrict to a single storestatus– order status filtergroupBy– optional breakdown dimension. VTEX:payment_method,utm_source,utm_campaign,product; Shopify:utm_source,utm_campaign,product,source_name; Tray:payment_method,product. An unsupported dimension returns 400 listing the platform's valid ones.
Status filtering
All three platforms (VTEX, Shopify, Tray) filter their native status column directly — pass the platform's own status value (e.g. VTEX invoiced).
Payment outcomes
GET /v1/orders/payment-outcomes?platform=vtex|tray|shopify&startDate=&endDate= answers what happened to the orders created in the period, per payment method: how many were paid (paidOrders, paymentRate) and, of the unpaid, how many were canceled without a payment (canceledOrders) and how many are still open (pendingOrders), with the real value of each. Each order is in one outcome only, and an order paid then canceled counts as paid. Shopify does not extract the payment method and answers supported: false.
Authentication
All endpoints require authentication via the standard V4MOS.AI API headers.