Cashback

Cashback is a rewards balance your Account earns. You can read what you've earned, see promotion progress, and redeem the balance to your Wingspan Wallet.

Prerequisites

A credential with bookkeeping.service:read to read, and bookkeeping.service:write to redeem.
An Idempotency-Key header on both redeem calls.

Check eligibility and balance

GET /v3/finance/cashback/eligibility returns isEligible, and when available reason, cashbackRate, and terms.
GET /v3/finance/cashback/balance returns balance, pendingBalance, currency, lifetimeEarned, and lifetimeRedeemed.

// GET /v3/finance/cashback/balance, 200 OK
{
  "balance": 42.75,
  "pendingBalance": 5.00,
  "currency": "USD",
  "lifetimeEarned": 120.00,
  "lifetimeRedeemed": 72.25
}

Redeem cashback to your Wallet

Call POST /v3/finance/cashback/redeem with amount. The amount must be greater than zero. The money goes to your Wingspan Wallet.

curl -X POST "https://api.wingspan.app/v3/finance/cashback/redeem" \
  -H "Authorization: Bearer $WINGSPAN_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: cashback-2026-10-20" \
  -d '{ "amount": 40.00 }'

// 200 OK (trimmed)
{
  "id": "Cb9Qk4Wn7Lx2Bz5Mh8Rc3T",
  "amount": 40.00,
  "currency": "USD",
  "status": "Pending"
}

status is Completed, Pending, or Failed. The Idempotency-Key is required, so a retry after a timeout can't redeem twice. destinationAccountId is in the schema, but sending it returns 422 for now.

Promotions

Promotions give a reward when you reach a spend target. Call GET /v3/finance/cashback/promotions. Each promotion has status (Active, Expired, or Complete), spendTarget, currentSpend, startDate, endDate, and reward. reward.status is Pending or Issued, and reward.redemptionLink is set when there is one.

To redeem a completed promotion, call POST /v3/finance/cashback/promotions/{promotionId}/redeem. It needs an Idempotency-Key. A promotion reward is issued once. While a reward is pending or already issued, a second attempt returns 409 instead of issuing another. The reward amount is set by the promotion, not by the request. The response is the promotion.

Errors

Status	Meaning
`403`	Missing scope
`404`	The promotion doesn't exist
`409`	A reward for this promotion is already pending or issued, or `IdempotencyKeyConflict`
`422`	The `Idempotency-Key` header is missing, `amount` is zero or less, or `destinationAccountId` was sent
`503`	The cashback service is unavailable. Retry.

Webhook events

CashbackRedemption.Created and CashbackRedemption.Updated are published. See Webhooks and events to subscribe.