Entrar

Relatório de vendas e faturamento: por dia/loja, dashboard, atribuição por campanha

GET https://{organization}.myguper.com/api/order/report/sales/{dateStart}/{dateEnd}

Vendas/faturamento agregados por período, com quebra por dia, mês ou loja — a resposta para "quanto vendi ontem", "faturamento por loja neste mês", "ticket médio por período". Devolve os totais mais a quebra por status.

A receita é líquida de cancelamento por padrão (pedidos cancelados ficam fora do total). O bloco byStatus traz sempre todos os status, inclusive o cancelado, para o que ficou de fora continuar auditável.

Valores em centavos. O dia sai de order_date (a data do negócio) convertida para o fuso da organização — a venda cai no dia em que aconteceu, não no dia em que sincronizou. updatedThrough é o maior createAt que entrou no cálculo: como o pedido chega depois da venda, "ontem" é um número mutável; use-o para decidir se vale reconsultar.

Substitui o financeSumary, que somava cancelado, perdia o último dia do período e agrupava em UTC.

Todo total traz mix, a receita decomposta do preço de tabela até o que entrou de fato — a resposta para "qual é minha receita líquida", "quanto eu dei de desconto", "quanto o programa de fidelidade me custou":

campo significado
listRevenue preço de tabela — revenue + discounts
discount o que a loja abriu mão
incentive saldo que o programa pagou (null sem withAttribution)
netRevenue o que entrou — revenue − incentive (null sem withAttribution)
averageTicket ASP, preço médio efetivamente cobrado
listAverageTicket OSP, preço médio de tabela, antes do desconto

⚠️ revenue já é líquido do desconto comercial — o price do item é o unitário depois do desconto. Então o preço de tabela é revenue mais discounts, não menos. Subtrair o desconto de revenue conta duas vezes, e é a forma mais comum de errar esse número.

⚠️ Não confunda mix com attribution.revenueGross / revenueNet: esses são do recorte das vendas atribuídas, enquanto mix é do negócio inteiro.

⚠️ listRevenue e listAverageTicket valem o que valer total_discounts. Onde a integração não manda "preço de tabela menos preço de venda" o número não se sustenta — ordersDiscountOverRevenue, no mesmo total, conta os pedidos com desconto maior que a própria venda.

Todo total e toda linha trazem também as contagens principais: orders, revenue, averageTicket e customersIdentified — os compradores únicos (clientes distintos, COUNT(DISTINCT client)): quantas pessoas diferentes compraram — além de ordersIdentified / ordersAnonymous (pedidos com e sem cliente identificado). Então "vendas por dia com ticket médio e compradores únicos" é uma chamada só: este relatório com groupBy=day (some membership=member para só membros). customersIdentified conta só comprador identificado — pedido anônimo não tem cliente para contar.

Passe compareWith para comparar com outro período (previous = janela de mesmo tamanho logo antes; previousYear = mesmas datas um ano atrás; ou um intervalo YYYY-MM-DD..YYYY-MM-DD). A resposta ganha um bloco comparison com o total do período-base e o delta (absoluto e %) — dá para responder "vendeu X, +12% vs o mês passado".

Passe withAttribution para a receita atribuída a campanhas — o valor total das vendas em que o cashback / saldo de uma campanha foi resgatado ou cuja mensagem gerou a compra, e a mesma quebra por campanha (topCampaigns=N), para responder "quanto o cashback da campanha X gerou" e o ticket por campanha. É receita influenciada, não incremental. O bloco separa ainda venda atribuída (resgatou saldo), influenciada (só recebeu a mensagem e comprou) e impactada (a soma) em split. O bloco já traz as derivadas sobre pedidos distintos: avgDiscount (redeemed / revenueGross), averageTicketGross e averageTicketNet — a diferença entre os dois tickets é o saldo médio aplicado por pedido.

Try-it values populated from environment ACME (Demo)


Autenticação

Token

Send your user token in the x-guper-authorization header.

Cabeçalhos

Name Type Description
x-guper-authorization * string User token issued by Guper.
Content-Type * string Always `application/json` for endpoints that accept a JSON body.

Parâmetros do caminho

Name Type Description
dateStart * string Start of the period (YYYY-MM-DD), inclusive.
dateEnd * string End of the period (YYYY-MM-DD), inclusive. The whole day is included.

Parâmetros de query

Name Type Description
groupBy string How to break the numbers down. One of `day`, `month`, `store`, `interface` (the integration channel), `tier`, or a comma list combining `store`/`interface` with `day` or `month` (e.g. `day,store`). `day` and `month` cannot be combined. Default: `day`. `tier` groups by the customer's level at purchase time (the `order_personTier` snapshot); the row with `tier: null` is the **no snapshot** bucket (anonymous or unidentified), which is what makes the rows add up to the total. It uses a single tier program per organization (the oldest), so an organization with two never counts one order twice.
store integer | string Restrict to one store (`store=207`) or to a **list** of them (`store[]=207&store[]=208`, or `207,208` — up to 500). The list exists for a **channel** filter: a channel is a store *group*, the group lives in the Register service and is deliberately not denormalized onto the order, so the caller resolves the group into store ids and sends the ids.
tier string Restrict to orders placed by a customer at this **tier at the time of purchase**, from the order's own snapshot (`order_personTier`). Pass the level name exactly as the program defines it (`Diamond`, `Gold`, …), or **`none`** for orders with no snapshot at all. ⚠️ `none` is not leftovers: those are anonymous or unidentified orders, and in a large organization they can be **over a third of the revenue** — so the tiers alone never add up to the total. The filter also narrows the attribution block and the product ranking, so every number on the response answers the same cut.
client string Restrict to a list of client ids — a cohort or an experiment universe. Pass an array (`client[]=101&client[]=102`) or a comma list. Up to 5000 ids. The same filter applies to the attributed-revenue block.
campaign string Requires `withAttribution=true`. Restricts **only the attribution block** to orders attributed to these campaigns (each order counted once, even if it used more than one of them). The sales total is not filtered — a sale has no campaign — so `participation` becomes the share of these campaigns in the total. Array (`campaign[]=191`) or comma list; up to 500 ids.
status string Restrict the total to one order status. Default: everything except `canceled`. Regardless of this filter, `byStatus` always reports all statuses. Values: `completed`, `registered`, `canceled`.
compareWith string Add a period-over-period comparison. `previous` = the equal-length window immediately before; `previousYear` = the same dates one year back; or an explicit range `YYYY-MM-DD..YYYY-MM-DD`. Adds a `comparison` block (baseline total + `delta` abs/pct). The same `store`/`status` filters apply to both sides.
membership string Restrict to **members / associates**: `member` keeps only orders placed by a program member, from the order's `order_personMembership` snapshot (`isMember=1`, captured at purchase). This is **revenue from members in the period**. It only covers orders that have a member snapshot (from ~2026-05-28 on); earlier orders are left out. There is no `non-member` value — the snapshot does not record non-members, so compute non-member as `total − member`. For the org-wide member base (counts, tiers, lifetime), use `register.report.members`.
withAttribution boolean Add an `attribution` block: revenue on orders attributed to a campaign (a campaign whose balance was redeemed, or whose message the client got before buying in the window), same scope as the total. It carries `revenueGross` (gross, redeemed balance NOT subtracted), `redeemed` (the balance applied) and **`revenueNet = revenueGross − redeemed`** — the **generated sale**, the basis on which Guper bills. Report `revenueNet`, not `revenueGross`: gross overstates it. `participation` is the gross ratio, `participationNet` the net one (net over total revenue). Add `topCampaigns=N` for the top-N campaigns by attributed revenue. The block (and each `byDay` row) also carries `avgDiscount` (`redeemed / revenueGross`, a ratio), `averageTicketGross` (`revenueGross / orders`) and `averageTicketNet` (`revenueNet / orders`), all over **distinct orders** — use them instead of recomputing. It also carries a **`split`** block with the two ways the program reaches a sale, in distinct orders: **`attributed`** (the order redeemed balance) and **`influenced`** (the client only got the campaign's message and bought, redeeming nothing), plus **`impacted`** — the sum, which is the block's own total. An order falls on one side only: getting the message *and* redeeming counts as attributed. Each side carries the same derived fields as the total (`orders`, `revenueGross`, `redeemed`, `revenueNet`, `avgDiscount`, `averageTicketGross`, `averageTicketNet`), so `attributed.revenueNet + influenced.revenueNet = impacted.revenueNet`. Each `byDay` row and each `byStore`/`byInterface` row carries the same two sides (`split.attributed` and `split.influenced`, net), so a chart can switch between them without another request.
attributionBy string Requires `withAttribution=true`. Break the attribution block down by `store` and/or `interface` (comma list), adding `byStore` / `byInterface` — one row per value, each with the same derived fields as the total, ordered by attributed revenue. Both dimensions belong to the **order**, so they are summed after orders are deduplicated. The day breakdown already comes as `byDay` with `groupBy`, and campaign/origin have their own rankings.

Respostas

{
  "meta": {
    "unit": "cents",
    "timezone": "America/Sao_Paulo",
    "groupBy": ["month"],
    "filters": { "store": null, "status": "all except canceled (default)" }
  },
  "rows": [
    { "month": "2026-08", "orders": 22431, "revenue": 4936614695,
      "discounts": 261093017, "averageTicket": 220080, "customersIdentified": 13445,
      "ordersIdentified": 22283, "ordersAnonymous": 148 }
  ],
  "total": {
    "orders": 22431, "revenue": 4936614695, "discounts": 261093017, "averageTicket": 220080,
    "customersIdentified": 13445, "ordersIdentified": 22283, "ordersAnonymous": 148
  },
  "byStatus": [
    { "status": "completed", "orders": 22431, "revenue": 4936614695 },
    { "status": "canceled",  "orders": 448,   "revenue": 113308848 }
  ],
  "updatedThrough": "2026-09-02 18:05:03",
  "comparison": {
    "period": { "start": "2026-07-01", "end": "2026-07-31", "label": "previous" },
    "total": {
      "orders": 23633, "revenue": 4585023678, "averageTicket": 194009,
      "customersIdentified": 14139, "ordersIdentified": 23490, "ordersAnonymous": 143
    },
    "delta": {
      "orders":        { "abs": -1202,      "pct": -0.0509 },
      "revenue":       { "abs": 351591017,  "pct": 0.0767 },
      "averageTicket": { "abs": 26071,      "pct": 0.1344 }
    }
  }
}

Notas

Comparando períodos (compareWith)

Adiciona um bloco comparison ao lado do total. A comparação usa os mesmos filtros store/status; só o total do período-base é calculado (sem quebra por dia ou por loja no período-base).

valor período-base
previous a janela de mesmo tamanho imediatamente antes — ex.: para 2026-08-01..2026-08-31 (31 dias) é 2026-07-01..2026-07-31
previousYear as mesmas datas um ano antes — ex.: 2025-08-01..2025-08-31
2026-06-01..2026-06-30 um intervalo explícito que você passa

delta compara o total atual com o base, em orders, revenue e averageTicket:

  • abs — a diferença (atual − base). Em centavos para revenue e averageTicket.
  • pct — a variação como razão: 0.0767 = +7,67%, -0.0509 = −5,09%. É null quando o base é 0 (porcentagem contra zero não tem sentido).

No exemplo acima: faturamento +7,7% com −5,1% de pedidos — menos pedidos, ticket maior (+13,4%).

Atribuída, influenciada, impactada (split)

Com withAttribution=true, o bloco separa os dois caminhos pelos quais o programa chega na venda, sempre em pedidos distintos:

lado o que é
attributed o pedido resgatou saldo de uma campanha
influenced o cliente só recebeu a mensagem da campanha e comprou, sem resgatar nada
impacted os dois juntos — o total do próprio bloco
cashback dos atribuídos, os que resgataram sem push
push dos atribuídos, os que resgataram e receberam push (push vence o empate)

O pedido cai num lado só: receber a mensagem e resgatar conta como atribuído, então attributed e influenced nunca contam em dobro e sempre fecham na soma (impacted). Dentro dos atribuídos, cashback + push = attributed — a separação por canal, porque cashback-base e push custam diferente e misturar subestima o retorno do push.

"attribution": {
  "orders": 1558,
  "revenueNet": 303065066,
  "split": {
    "attributed": { "orders": 1480, "revenueGross": 345645957, "redeemed": 62869038, "revenueNet": 282776919, "avgDiscount": 0.1819 },
    "influenced": { "orders": 78,   "revenueGross": 20288147,  "redeemed": 0,        "revenueNet": 20288147,  "avgDiscount": 0 },
    "impacted":   { "orders": 1558, "revenueGross": 365934104, "redeemed": 62869038, "revenueNet": 303065066, "avgDiscount": 0.1718 },
    "cashback":   { "orders": 1432, "revenueGross": 332780112, "redeemed": 60667968, "revenueNet": 272112144, "avgDiscount": 0.1823 },
    "push":       { "orders": 48,   "revenueGross": 12865845,  "redeemed": 2201070,  "revenueNet": 10664775,  "avgDiscount": 0.1711 }
  }
}

influenced só existe onde a campanha manda mensagem — campanha que só emite saldo nunca cai ali. cashback/push também aparecem em byDay e nas quebras byStore/byInterface (cashback vs push por canal e por mês). Reporte revenueNet: é a base da fatura.

discounts e os pedidos em que ele não fecha

discounts é a soma de total_discounts, que as integrações deveriam mandar como preço de tabela menos preço de venda. Algumas não mandam. ordersDiscountOverRevenue conta os pedidos do recorte cujo desconto é maior que a própria venda — o que aquela definição torna impossível.

Não é resíduo de arredondamento: numa organização são 27% dos pedidos, todos de uma integração só, e com eles dentro a razão desconto/receita dá 67%. Confira esse campo antes de publicar qualquer razão feita sobre discounts; acima de zero, reporte o valor e diga que a razão não se sustenta, em vez de transformar dado sujo em número de negócio. Consertar o dado é da integração, não do relatório.

Relacionados

Copied to clipboard