E-commerce Summary

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

Response

Each endpoint returns:

  • totalOrders – number of orders in the period
  • totalRevenue – summed order value
  • avgTicket – totalRevenue / totalOrders (0 when there are no orders)
  • totalCustomers – orders with an identifiable customer
  • uniqueCustomers – distinct customers
  • period, platform, integrationName
  • groupBy / groups – present only when groupBy was sent: top-20 groups by revenue, each with key, 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). For groupBy=product, the (outros) row carries only key and totalRevenue — totalOrders, avgTicket and uniqueCustomers are null (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 store
  • status – order status filter
  • groupBy – 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.

On this page