Entrar

Cashback emitido e resgatado por campanha (agregado)

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

Agregado de cashback da organização — cards emitidos, crédito distribuído, resgatado, saldo e expirados — quebrado por mês, dia, campanha, gatilho ou loja, numa única chamada. É o relatório de campanha, agrupado: em vez de chamar o relatório por-campanha uma vez por campanha (uma org pode ter centenas), devolve todas de uma vez.

É o dashboard de indicadores do programa de cashback (emissão e resgate): quanto foi emitido, resgatado e expirado por campanha no período. (Para o saldo atual disponível por carteira — disponível, usado — use o relatório de saldos; este é o fluxo de emissão/resgate ao longo do tempo.)

Reconcilia com loyalty.campaign.report por construção — mesma fonte, mesma conta: rewardCard para emissão/saldo/cards e rewardCard_flow para o valor resgatado preciso.

Conversão (uso dos cards). Um card conta como usado quando uma venda que gastou o saldo dele foi liquidada — uso parcial e total contam. Reserva aberta no checkout e reserva cancelada não contam. O saldo do card nunca é usado para isso: ele também desce por estorno de premiação e débito manual.

  • touchedCards — cards emitidos no período (não cancelados) com algum resgate liquidado, em qualquer data. touchedRedeemed — o valor que esses mesmos cards resgataram, em qualquer data (o redeemed segue a data do resgate).
  • cardsRedeemedFull / cardsRedeemedPartial — desses, os que gastaram todo o crédito / os que ainda tinham saldo.
  • usageRate — taxa de conversão: touchedCards / (cards − cardsCanceled), em %. partialShare / fullShare — % dos touchedCards (somam 100).
  • Buckets de status que somam cards: cardsRedeemed (card com saldo zerado), cardsExpired, cardsCanceled, cardsActive. cardsRedeemed não é a conversão: estorno também zera card.
  • expiredBalance — saldo que sobrou nos cards vencidos: o crédito perdido por não ser usado a tempo (mesmo corte do cardsExpired).

Um período recente ainda está maturando — a conversão dele sobe enquanto os cards estão válidos. Compare com um período anterior, já fechado.

Valores em centavos. Tipo separado (rewardType=monetary por padrão) — carteira de ponto é outra escala e não pode ser somada com centavo. Cards de teste (production=0) ficam fora. Cancelados são contados à parte (cardsCanceled), nunca somem. O dia sai no fuso da organização, então casa com o relatório de vendas por (mês, loja).

redeemed é o valor resgatado liquidado. Com cohort=redemption (padrão) é pela data do resgate — um card emitido em julho e resgatado em agosto mostra a emissão em julho e o resgate em agosto. Com cohort=issuance é o valor resgatado, em qualquer data, dos cards emitidos no período ("o que aconteceu com o que emiti").

groupBy=tier quebra pelo tier do cliente na EMISSÃO — um snapshot gravado no card quando ele nasce (o nível na compra é imutável). tier=null = card sem tier (anônimo/não identificado, ou emitido antes do snapshot; o histórico não é backfillado, salvo indicação).

Ainda fora daqui: canal — agrupe por store e junte o mapa loja→grupo no cliente.

Com groupBy=campaign, cada linha traz também o name e o trigger da campanha — para classificar em famílias (reativação, aniversário, last-chance…) sem outra chamada.

Try-it values populated from environment ACME (Demo)


Autenticação

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.

Cabeçalhos

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.

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.

Parâmetros de query

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.

Respostas

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

Relacionados

Copied to clipboard