Entrar

Cashback emitido y canjeado por campaña (agregado)

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

Agregado de cashback de la organización — tarjetas emitidas, crédito distribuido, canjeado, saldo y expiradas — desglosado por mes, día, campaña, trigger o tienda, en una sola llamada. Es el reporte de campaña, agrupado: en vez de llamar el reporte por-campaña una vez por campaña (una org puede tener cientos), devuelve todas de una vez.

Reconcilia con loyalty.campaign.report por construcción — misma fuente, misma cuenta: rewardCard para emisión/saldo/tarjetas y rewardCard_flow para el valor canjeado preciso.

Conversión (uso de las tarjetas). Una tarjeta cuenta como usada cuando una venta que gastó su saldo fue liquidada — el uso parcial y el total cuentan. Una reserva abierta en el checkout o una reserva cancelada no cuentan. El saldo de la tarjeta nunca se usa para esto: también baja por reversión del premio y débito manual.

  • touchedCards — tarjetas emitidas en el período (no canceladas) con algún canje liquidado, en cualquier fecha. touchedRedeemed — el valor que esas mismas tarjetas canjearon, en cualquier fecha (redeemed sigue la fecha del canje).
  • cardsRedeemedFull / cardsRedeemedPartial — de esas, las que gastaron todo el crédito / las que aún tenían saldo.
  • usageRate — tasa de conversión: touchedCards / (cards − cardsCanceled), en %. partialShare / fullShare — % de touchedCards (suman 100).
  • Grupos de estado que suman cards: cardsRedeemed (tarjeta con saldo en cero), cardsExpired, cardsCanceled, cardsActive. cardsRedeemed no es la conversión: una reversión también deja la tarjeta en cero.
  • expiredBalance — saldo que quedó en las tarjetas vencidas: el crédito perdido por no usarse a tiempo (mismo corte que cardsExpired).

Un período reciente todavía está madurando — su conversión sigue subiendo mientras las tarjetas están vigentes. Compárelo con un período anterior, ya cerrado.

Valores en centavos. Tipo separado (rewardType=monetary por defecto) — la cartera de puntos es otra escala. Tarjetas de prueba (production=0) quedan fuera. Canceladas se cuentan aparte (cardsCanceled). El día se corta en la zona horaria de la organización, así calza con el reporte de ventas por (mes, tienda).

redeemed es el valor canjeado liquidado. Con cohort=redemption (por defecto) es por la fecha del canje, no de la tarjeta. Con cohort=issuance es el valor canjeado, en cualquier fecha, de las tarjetas emitidas en el período ("qué pasó con lo que emití").

groupBy=tier desglosa por el tier del cliente en la EMISIÓN — un snapshot guardado en la tarjeta cuando nace (el nivel en la compra es inmutable). tier=null = tarjeta sin tier (anónimo/no identificado, o emitida antes del snapshot; el histórico no se backfillea, salvo indicación).

Aún fuera de aquí: canal — agrupa por store y une el mapa tienda→grupo del lado del cliente.

Con groupBy=campaign, cada fila trae también el name y el trigger de la campaña — para clasificar en familias (reactivación, cumpleaños, last-chance…) sin otra llamada.

Try-it values populated from environment ACME (Demo)


Autenticación

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.

Encabezados

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 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.

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.

Respuestas

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