Sign in

Cashback redemptions report: which orders redeemed, per campaign, origin store vs redemption store (circulation)

GET https://{organization}.myguper.com/api/loyalty/report/redemptions/{dateStart}/{dateEnd}

Settled cashback redemptions — one row per (redemption, card) — with the order that used the balance, the store that issued the card and the store where it was redeemed. Paginated. Pass groupBy to get aggregates instead (by day, month, campaign, origin store and/or redemption store).

Use it for the detail table of redemptions, to answer "which orders used the cashback of campaign X", and for balance circulation between stores (groupBy=originStore,redeemStore: where the balance was generated vs where it was spent).

Grain: the card. An order that used three cards shows up three times, so there is no order total here on purpose — summing a ticket over these rows counts the same order several times. For revenue per order use order.report.sales (with attribution) or order.campaign.report.

A redemption counts only once the sale is settled. Open checkout reservations and canceled reservations are left out. redeemedValue is the debit minus any partial reversal of that same redemption, on that card.

cohort=redemption (default): debits (checkout) dated in the period, from cards of any date. cohort=issuance: cards issued in the period, redeemed at any date. Values are in cents; dates are in the organization timezone. Test cards (production=0) are excluded; rewardType defaults to monetary.

In aggregates, redemptions (distinct redemptions), cards (distinct cards) and orders (distinct orders) are different counts — none of them is a denominator for the others.

Try-it values populated from environment ACME (Demo)


Authentication

Token

Send your user token in the x-guper-authorization header. Endpoints that support a Public mode (e.g. acúmulo and resgate previews) accept the same request without the header — Private mode adds customer data and a confirmation token to the response.

Headers

Name Type Description
x-guper-authorization * string User token issued by Guper. Omit only on endpoints that explicitly support a Public mode.
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.

Query parameters

Name Type Description
groupBy string Omit for the paginated list. Otherwise one of `day`, `month`, `campaign`, `originStore`, `redeemStore`, or a comma list. `day` and `month` cannot be combined; they follow the cohort (redemption date or card issuance date).
cohort string Which date the period applies to. `redemption` (default) or `issuance`.
campaign string Only cards of these campaigns. Pass an array (`campaign[]=191&campaign[]=171`) or a comma list; a single id still works. Up to 200 ids.
originStore integer Only cards issued by this store.
redeemStore integer Only redemptions made in this store.
client integer Only cards of this client (person id).
rewardType string Which wallet. Default `monetary`.
page integer List page (default 1). Ignored with `groupBy`.
entries integer Rows per page (default 50, max 500). Ignored with `groupBy`.

Responses

{
  "meta": { "unit": "cents", "timezone": "Etc/GMT+6", "cohort": "issuance", "groupBy": null },
  "total": { "rows": 757, "redemptions": 694, "orders": 694, "redeemedValue": 34095898 },
  "page": 1, "entries": 1, "pages": 757,
  "list": [
    { "tid": "f19f97178e926abacd584819d8e83e954b5254c4c6b12aea23c02670d21eb9e3",
      "cardId": 334708, "campaign": 191, "clientId": 2461453,
      "originStore": 1629, "redeemStore": 1629, "orderId": 3940209,
      "redeemedValue": 147400, "redeemedAt": "2025-10-04 15:26:23",
      "settledAt": "2026-08-27 16:42:03", "cardCreatedAt": "2025-08-17 16:48:09" }
  ]
}

Related

Copied to clipboard