Sign in

Sales & revenue report: by day/store, dashboard, campaign attribution

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

Aggregated sales/revenue for a period, broken down by day, month, store or integration channel (interface) — the answer to "how much did I sell yesterday", "revenue by store this month", "sales per channel", "average ticket per period". Returns totals plus a per-status breakdown; each row/total carries revenue and discounts. Filter to a cohort with client.

Revenue is net of cancellations by default (canceled orders are excluded from the total). The byStatus block always reports every status, including canceled, so what was left out stays auditable.

Every total carries mix, the revenue broken down from list price to what actually came in — the answer to "what is my net revenue", "how much did I give away in discount", "what did the loyalty program cost me":

field meaning
listRevenue list price — revenue + discounts
discount what the store gave up
incentive balance the program paid (null without withAttribution)
netRevenue what came in — revenue − incentive (null without withAttribution)
averageTicket ASP, the average price actually charged
listAverageTicket OSP, the average list price, before discount

⚠️ revenue is already net of the commercial discount — an item's price is the unit price after discount. So list price is revenue plus discounts, not minus. Subtracting the discount from revenue counts it twice, and it is the most common way to get this number wrong.

⚠️ Do not confuse mix with attribution.revenueGross / revenueNet: those are scoped to the attributed orders only, while mix is the whole business.

⚠️ listRevenue and listAverageTicket are only as good as total_discounts. Where the integration does not send "list price minus sale price" the number does not hold — ordersDiscountOverRevenue, in the same total, counts the orders whose discount is bigger than the sale itself.

Every total and row also carries the headline counts: orders, revenue, averageTicket, and customersIdentified — the number of unique buyers (distinct customers, COUNT(DISTINCT client)): how many different people bought — plus ordersIdentified / ordersAnonymous (orders with vs. without an identified customer). So "sales by day with average ticket and unique buyers" is a single call: this report with groupBy=day (add membership=member for members only). customersIdentified counts identified buyers only — an anonymous order has no customer to count.

Pass compareWith to get a period-over-period comparison: the response adds a comparison block with the baseline period's total and the delta (absolute and percent) on orders, revenue and average ticket — so you can answer "sold X, +12% vs last month".

Pass withAttribution for revenue attributed to campaigns — the total value of the sales where a campaign's cashback / balance was redeemed or whose message drove the purchase, and the same broken down per campaign (topCampaigns=N), so you can answer "how much did campaign X's cashback generate" and the ticket per campaign. This is influenced revenue, not incremental. The block also splits attributed sales (balance redeemed), influenced ones (only got the message and bought) and the impacted total (the sum) in split. Within the attributed sales, split also separates cashback (redeemed, no push) from push (redeemed and a push notification — push wins the tie), so you can read the push-assisted revenue apart from organic cashback; cashback + push = attributed. The split is in byDay and in the byStore/byInterface breakdowns too (cashback vs push by channel and month).

Values are in cents. The day is cut from order_date (the business date) converted to the organization timezone, so a sale rings up on the day it happened, not the day it synced. updatedThrough is the newest createAt that entered the calculation — because orders arrive after the sale, "yesterday" is a moving number; use it to decide whether to refetch.

Supersedes financeSumary, which summed cancellations, dropped the last day of the period and grouped in UTC.

Try-it values populated from environment ACME (Demo)


Authentication

Token

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

Headers

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.

Path parameters

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.

Query parameters

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.

Responses

{
  "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 }
    }
  }
}

Notes

Comparing periods (compareWith)

Adds a comparison block next to total. The comparison covers the same store/status filters; only the baseline total is computed (no per-day or per-store breakdown for the baseline).

value baseline period
previous the equal-length window immediately before the requested one — e.g. for 2026-08-01..2026-08-31 (31 days) it is 2026-07-01..2026-07-31
previousYear the same calendar dates one year earlier — e.g. 2025-08-01..2025-08-31
2026-06-01..2026-06-30 an explicit range you provide

delta compares the current total to the baseline, on orders, revenue and averageTicket:

  • abs — the difference (current − baseline). In cents for revenue and averageTicket.
  • pct — the change as a ratio: 0.0767 means +7.67%, -0.0509 means −5.09%. It is null when the baseline is 0 (a percentage against zero has no meaning).

So in the example above: revenue up +7.7% on −5.1% orders — fewer orders, bigger ticket (+13.4%).

Attributed, influenced, impacted (split)

With withAttribution=true the block splits the program's reach into the two ways it gets to a sale, always in distinct orders:

side what it is
attributed the order redeemed balance from a campaign
influenced the client only got the campaign's message and bought, redeeming nothing
impacted the two together — the block's own total
cashback of the attributed, those that redeemed without push
push of the attributed, those that redeemed and got a push (push wins the tie)

An order is on one side only: getting the message and redeeming counts as attributed, so attributed and influenced never double-count and always add up (to impacted). Within the attributed, cashback + push = attributed — the channel split, because cashback base and push cost differently and mixing them underestimates the push return.

"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 only exists where campaigns send messages — a campaign that just issues balance never lands there. cashback/push also appear in byDay and in the byStore/byInterface breakdowns (cashback vs push by channel and month). Report revenueNet: it is the billing basis.

discounts and the orders where it does not add up

discounts is the sum of total_discounts, which integrations are meant to send as list price minus sale price. Some do not. ordersDiscountOverRevenue counts the orders in the cut whose discount is larger than the sale itself — which that definition makes impossible.

It is not a rounding leftover: in one organization it is 27% of the orders, all from one integration, and with them in the mix the discount-over-revenue ratio reads 67%. Check this field before publishing any ratio built on discounts; when it is above zero, report the amount and say the ratio does not hold, instead of turning bad data into a business number. Fixing the data is the integration's job, not the report's.

Related

Copied to clipboard