Skip to main content

Redeem Voucher via Points Exchange

POST 
/client/users/:correlation_id/voucher/voucher-exchange/redeem

POST /voucher/voucher-exchange/redeem — Redeem Points for Voucher

Debits the member's point balance and issues a new voucher instance from the specified definition, via the Voucher Exchange flow. The debit + issuance is atomic — either both succeed, or neither does.

Request Body​

{
  "voucherDefinitionId": "def-10off",
  "businessUnit": "DEFAULT"
}

FieldTypeRequiredDescription
voucherDefinitionIdstringYesDefinition to redeem — must appear in the eligible list
businessUnitstringYesBU scope — must match the definition's BU

Preconditions​

  1. Definition exists and is in the active exchange pool → else 404 VOUCHER_DEFINITION_NOT_FOUND

  2. member.availablePointBalance >= definition.pointValue → else 409 INSUFFICIENT_POINTS (response includes requiredPoints + availablePointBalance)

  3. Daily/lifetime redemption limits not yet reached for this definition → else 409 REDEMPTION_LIMIT_EXCEEDED

  4. Member's tier (if gated) eligible

Redemption Flow​

  1. Validate body + preconditions

  2. Atomic transaction:

    • Debit pointValue from point balance (writes Voucher Burn transaction part)

    • Issue new voucher instance — status=AVAILABLE, all definition-derived fields hydrated

  3. On step 2 failure → full rollback (no orphan issuance, no silent point loss)

  4. Return the issued voucher + remaining balance

Response — 200​

FieldTypeDescription
advice.voucher.applied[]arrayIssued voucher(s) — each item is a minimal voucher view
transactionIdstringUnique ID for this exchange transaction
pointsRedeemednumberPoints debited (= definition.pointValue)
remainingPointBalancenumberMember balance after debit

Idempotency​

This endpoint is NOT idempotent. Duplicate POSTs will double-debit if both succeed. Client responsibilities:

  • Disable the redeem button immediately on first submission

  • On network error / timeout → do not auto-retry. Instead, re-query GET /issuances?type=VOUCHER and the points balance to reconcile state before prompting the user

  • Display a confirmation modal before the first submission

Error Responses​

StatuserrorCodeWhen
400INVALID_REQUESTMissing body, missing voucherDefinitionId, malformed fields
401—Missing/expired OAuth token
404VOUCHER_DEFINITION_NOT_FOUNDDefinition doesn't exist or is not in the exchange pool
409INSUFFICIENT_POINTSBalance below pointValue — response includes requiredPoints + availablePointBalance
409REDEMPTION_LIMIT_EXCEEDEDDaily/lifetime cap reached
500—Unexpected server error

  • GET .../voucher/voucher-exchange/eligible — check eligibility before calling this

  • GET .../issuances?type=VOUCHER — confirm the new voucher landed in inventory

Request​

Responses​

200 - Redemption Successful

Last updated on