Entrar

Reporte de ventas y facturación: por día/tienda, dashboard, atribución por campaña

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

Ventas/facturación agregadas por período, desglosadas por día, mes o tienda — la respuesta a "cuánto vendí ayer", "facturación por tienda este mes", "ticket promedio por período". Devuelve los totales más el desglose por estado.

Los ingresos son netos de cancelación por defecto (los pedidos cancelados quedan fuera del total). El bloque byStatus siempre reporta todos los estados, incluido el cancelado, para que lo excluido siga siendo auditable.

Valores en centavos. El día se corta de order_date (la fecha del negocio) convertida a la zona horaria de la organización. updatedThrough es el mayor createAt que entró en el cálculo: como el pedido llega después de la venta, "ayer" es un número mutable.

Reemplaza a financeSumary, que sumaba cancelaciones, perdía el último día del período y agrupaba en UTC.

Todo total trae mix, el ingreso descompuesto desde el precio de lista hasta lo que realmente entró — la respuesta a "cuál es mi ingreso neto", "cuánto di de descuento", "cuánto me costó el programa de lealtad":

campo significado
listRevenue precio de lista — revenue + discounts
discount lo que la tienda cedió
incentive saldo que pagó el programa (null sin withAttribution)
netRevenue lo que entró — revenue − incentive (null sin withAttribution)
averageTicket ASP, precio promedio efectivamente cobrado
listAverageTicket OSP, precio promedio de lista, antes del descuento

⚠️ revenue ya es neto del descuento comercial — el price del artículo es el unitario después del descuento. Entonces el precio de lista es revenue más discounts, no menos. Restar el descuento de revenue lo cuenta dos veces, y es la forma más común de equivocarse con este número.

⚠️ No confunda mix con attribution.revenueGross / revenueNet: esos son del recorte de las ventas atribuidas, mientras que mix es del negocio entero.

⚠️ listRevenue y listAverageTicket valen lo que valga total_discounts. Donde la integración no manda "precio de lista menos precio de venta" el número no se sostiene — ordersDiscountOverRevenue, en el mismo total, cuenta los pedidos con descuento mayor que la propia venta.

Todo total y toda fila traen también los conteos principales: orders, revenue, averageTicket y customersIdentified — los compradores únicos (clientes distintos, COUNT(DISTINCT client)): cuántas personas diferentes compraron — más ordersIdentified / ordersAnonymous (pedidos con y sin cliente identificado). Así "ventas por día con ticket promedio y compradores únicos" es una sola llamada: este reporte con groupBy=day (suma membership=member para solo miembros). customersIdentified cuenta solo comprador identificado — un pedido anónimo no tiene cliente que contar.

Pasa compareWith para comparar con otro período (previous = ventana del mismo tamaño justo antes; previousYear = las mismas fechas un año atrás; o un rango YYYY-MM-DD..YYYY-MM-DD). La respuesta agrega un bloque comparison con el total del período base y el delta (absoluto y %).

Pasa withAttribution para el ingreso atribuido a campañas — el valor total de las ventas donde el cashback / saldo de una campaña se canjeó o cuyo mensaje generó la compra, y el mismo desglose por campaña (topCampaigns=N), para responder "cuánto generó el cashback de la campaña X" y el ticket por campaña. Es ingreso influenciado, no incremental. El bloque separa además venta atribuida (canjeó saldo), influenciada (solo recibió el mensaje y compró) e impactada (la suma) en split. El bloque ya trae las derivadas sobre pedidos distintos: avgDiscount (redeemed / revenueGross), averageTicketGross y averageTicketNet — la diferencia entre los dos tickets es el saldo promedio aplicado por pedido.

Try-it values populated from environment ACME (Demo)


Autenticación

Token

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

Encabezados

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 de ruta

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.

Respuestas

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

Agrega un bloque comparison junto al total. La comparación usa los mismos filtros store/status; sólo se calcula el total del período base (sin desglose por día o por tienda en el período base).

valor período base
previous la ventana del mismo tamaño justo antes — ej.: para 2026-08-01..2026-08-31 (31 días) es 2026-07-01..2026-07-31
previousYear las mismas fechas un año antes — ej.: 2025-08-01..2025-08-31
2026-06-01..2026-06-30 un rango explícito que tú pasas

delta compara el total actual con el base, en orders, revenue y averageTicket:

  • abs — la diferencia (actual − base). En centavos para revenue y averageTicket.
  • pct — el cambio como razón: 0.0767 = +7,67%, -0.0509 = −5,09%. Es null cuando el base es 0.

En el ejemplo: facturación +7,7% con −5,1% de pedidos.

Atribuida, influenciada, impactada (split)

Con withAttribution=true, el bloque separa los dos caminos por los que el programa llega a la venta, siempre en pedidos distintos:

lado qué es
attributed el pedido canjeó saldo de una campaña
influenced el cliente solo recibió el mensaje de la campaña y compró, sin canjear nada
impacted los dos juntos — el total del propio bloque
cashback de los atribuidos, los que canjearon sin push
push de los atribuidos, los que canjearon y recibieron push (push gana el empate)

El pedido cae de un solo lado: recibir el mensaje y canjear cuenta como atribuido, así que attributed e influenced nunca cuentan doble y siempre suman (impacted). Dentro de los atribuidos, cashback + push = attributed — la separación por canal, porque el cashback base y el push cuestan distinto y mezclarlos subestima el retorno del 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 solo existe donde la campaña manda mensaje — una campaña que solo emite saldo nunca cae ahí. cashback/push también aparecen en byDay y en los desgloses byStore/byInterface (cashback vs push por canal y mes). Reporte revenueNet: es la base de la factura.

discounts y los pedidos en que no cuadra

discounts es la suma de total_discounts, que las integraciones deberían mandar como precio de lista menos precio de venta. Algunas no lo hacen. ordersDiscountOverRevenue cuenta los pedidos del recorte cuyo descuento es mayor que la propia venta — lo que esa definición vuelve imposible.

No es residuo de redondeo: en una organización son 27% de los pedidos, todos de una sola integración, y con ellos adentro la razón descuento/facturación da 67%. Revise ese campo antes de publicar cualquier razón hecha sobre discounts; arriba de cero, reporte el monto y diga que la razón no se sostiene, en vez de convertir dato sucio en número de negocio. Arreglar el dato es de la integración, no del reporte.

Relacionados

Copied to clipboard