Sign in

Cashback issued & redeemed by campaign (aggregate)

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

Org-wide cashback aggregate — cards issued, credit distributed, redeemed, balance and expired — broken down by month, day, campaign, campaign trigger or store, in a single call. It is the campaign report, grouped: instead of calling the per-campaign report once per campaign (an org can have hundreds), this returns every campaign at once.

This is the program dashboard / KPIs for cashback emission and redemption: how much was issued, redeemed and expired per campaign in the period. (For the current spendable balance per wallet — available, used — use the reward balances report instead; this one is the emission/redemption flow over time.)

Reconciles with loyalty.campaign.report by construction — same source, same math: rewardCard for issuance/balance/cards, rewardCard_flow for the precise redeemed value.

Conversion (usage of the cards). A card counts as used when a sale that spent its balance was settled — partial or full use both count. Open checkout reservations and canceled reservations do not. Card balance is never used for this: it also drops on reward reversals and manual debits.

  • touchedCards — cards issued in the period (not canceled) with any settled redemption, at any date. touchedRedeemed — the value those same cards redeemed, at any date (redeemed follows the redemption date instead).
  • cardsRedeemedFull / cardsRedeemedPartial — of those, the ones that spent the whole credit / that still had balance left.
  • usageRate — conversion rate: touchedCards / (cards − cardsCanceled), in %. partialShare / fullShare — % of touchedCards (they add up to 100).
  • Status buckets that add up to cards: cardsRedeemed (card with zero balance), cardsExpired, cardsCanceled, cardsActive. cardsRedeemed is not the conversion: a reversal also zeroes a card.
  • expiredBalance — balance left on the expired cards: the credit lost because it was not used in time (same cut as cardsExpired).

A recent period is still maturing — its conversion keeps rising while the cards are valid. Compare with an older, closed period.

Values are in cents. Reward type is separated (rewardType=monetary by default) — point wallets are a different scale and must not be summed with cash. Test cards (production=0) are excluded. Canceled cards are counted apart (cardsCanceled), never dropped silently. The day is cut in the organization timezone, so it lines up with the sales report by (month, store).

redeemed is the settled redeemed value. With cohort=redemption (default) it is windowed by the redemption date — a card issued in July and redeemed in August shows its issuance in July and its redeemed value in August. With cohort=issuance it is the value redeemed, at any date, from the cards issued in the period ("what happened to what I issued").

groupBy=tier breaks the numbers down by the member tier at issuance — a snapshot taken on the card when it was created (the tier at purchase is immutable). tier=null means the card had no tier (anonymous / unidentified, or issued before this snapshot shipped; history is not backfilled unless stated).

Still not here: channel — group by store and join the store-group map client-side.

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 How to break the numbers down. One of `month`, `day`, `campaign`, `trigger` (the campaign trigger), `store` or `tier` (the member tier at issuance), or a comma list (e.g. `day,store`). `month` and `day` cannot be combined. Default: `month`. With `campaign`, each row also carries the campaign **`name`** and **`trigger`** — so you can classify campaigns into families (reactivation, birthday, last-chance, …) without another call. With `tier`, a null row is cards with no tier snapshot.
rewardType string Which wallet. Default `monetary`. `point` is a different scale.
cohort string How `redeemed` is windowed. `redemption` (default): redeemed on dates in the period, from cards of any period. `issuance`: redeemed at any date from cards issued in the period. Card counts (`touchedCards` etc.) are always about the cards issued in the period.
campaign string Restrict to these campaigns. Pass an array (`campaign[]=191&campaign[]=171`) or a comma list; a single id still works. Up to 200 ids.
store integer Restrict to a single store id.

Responses

{
  "meta": {
    "unit": "cents", "timezone": "Etc/GMT+6",
    "groupBy": ["campaign"], "rewardType": "monetary",
    "cohort": "issuance",
    "filters": { "campaign": 191, "store": null }
  },
  "rows": [
    { "campaign": 191, "cards": 6687, "clients": 5798, "creditIssued": 352339478,
      "redeemed": 34095898, "balance": 0, "expiredBalance": 314870362, "cardsRedeemed": 280,
      "cardsExpired": 6319, "cardsCanceled": 88, "cardsActive": 0,
      "touchedCards": 696, "touchedRedeemed": 34095898, "cardsRedeemedPartial": 448, "cardsRedeemedFull": 248,
      "usageRate": 10.5, "partialShare": 64.4, "fullShare": 35.6 }
  ],
  "total": {
    "clients": 5798, "cards": 6687, "creditIssued": 352339478,
    "redeemed": 34095898, "balance": 0, "expiredBalance": 314870362, "cardsRedeemed": 280,
    "cardsExpired": 6319, "cardsCanceled": 88, "cardsActive": 0,
    "touchedCards": 696, "touchedRedeemed": 34095898, "cardsRedeemedPartial": 448, "cardsRedeemedFull": 248,
    "usageRate": 10.5, "partialShare": 64.4, "fullShare": 35.6
  }
}

Related

Copied to clipboard