E-commerce Summary

Resumo de pedidos Shopify

GET
/v1/shopify/orders/summary

Totais agregados de pedidos do Shopify no período informado. status filtra a coluna status derivada do Shopify (closed | cancelled | processed | open). Dimensões de groupBy: source_name, utm_source, utm_campaign (colunas do pedido; a UTM vem da última visita da jornada do cliente) e product (faz join com shopify_order_items; totalRevenue = preço unitário original × quantity, bruto de descontos de linha; totalOrders = pedidos distintos; a linha (outros) informa apenas key e totalRevenue — seus totalOrders, avgTicket e uniqueCustomers são null). O Shopify não expõe dados de pagamento — payment_method retorna 400.

Autorização

ClientIdAuthClientSecretAuth
headerx-client-id<token>

Client ID

headerx-client-secret<token>

Client secret

Parâmetros de query

organizationId*string

Identificador da organização (obrigatório)

dateStart*string

Início do período (YYYY-MM-DD), filtra created_at

Formatodate
dateEnd*string

Fim do período (YYYY-MM-DD), filtra created_at (dia inteiro incluído)

Formatodate
integrationName?string

Restringe a uma única integração de loja

status?string

Status do pedido no Shopify (closed | cancelled | processed | open). Quando omitido, pedidos cancelados/reembolsados são excluídos por padrão; informá-lo substitui esse padrão.

groupBy?string

Detalha o resumo por uma dimensão. O Shopify suporta: utm_source, utm_campaign, product, source_name.

Valor em"utm_source""utm_campaign""product""source_name"
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.

Formatouuid
paymentStatus?"paid"

Narrow the summary to paid orders, on top of the validity default or of an explicit status: fully_paid = TRUE and cancelled_at IS NULL (the dbt sales fact, int_shopify_order_sku_sales.is_invoiced). Echoed back as paymentStatus. Omitted, the summary is unchanged.

Valor em"paid"

Corpo da resposta

Resumo de pedidos (com eco de groupBy e groups quando solicitado)

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

Eco da dimensão solicitada. Presente apenas quando groupBy foi enviado.

Valor em"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.

Valor em"paid"
curl -X GET "https://example.com/v1/shopify/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"}