POST/tenants/{tenantId}/transactions/redeem-quote

Dry-run redemption — calculates the exact discount without writing anything to the database. Use this to power "you would save R0.50" previews at checkout before the member confirms they want to redeem.

No side effects — this endpoint never creates records, never deducts points, and is not idempotent. It is safe to call on every keypress in a "points to redeem" input field.

Path Parameters

tenantIdstring uuid
required
Your tenant UUID.

Request Body

memberRefstring
required
Your customer's identifier. Must match an existing member.
amountinteger
required
Basket total in cents. Used to apply maxDiscountPercentOfBasket constraints.
pointsRequestedinteger
required
Points the member wants to redeem.
campaignIdstring uuid
optional
Pin the quote to a specific campaign's burn rule.
storeRefstring
optional
Store identifier if campaigns use store targeting.

Response 200

pointsToRedeeminteger
required
Points that will be deducted — may be less than pointsRequested if a constraint applies.
discountAmountinteger
required
Discount in cents. Apply this at checkout.
discountAmountRandnumber
required
Discount in rand for display. discountAmount / 100.
pointsPerRandnumber
required
Active burn rate — points required per rand of discount.
balanceAfterinteger
required
Projected member balance if they confirm the redemption.
constraintAppliedstring | null
optional
Populated when a rule capped the redemption. Values: MAX_POINTS_PER_REDEMPTION · MAX_DISCOUNT_PERCENT_OF_BASKET · INSUFFICIENT_BALANCE

Error Codes

StatusCodeDescription
400VALIDATION_ERRORMissing or invalid field
401UNAUTHORIZEDMissing or invalid API key
403MEMBER_SUSPENDEDMember is suspended
404MEMBER_NOT_FOUNDmemberRef does not match any member
422INSUFFICIENT_POINTSMember balance is below pointsRequested

Related endpoints

POST /transactions/redeem — confirm the redemption →GET /transactions/burn-rate — look up pointsPerRand →

Request

cURL
curl -X POST "https://loyalty-engine-production-e5cb.up.railway.app/v1/tenants/$TENANT_ID/transactions/redeem-quote" \
  -H "X-API-Key: sk_test_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "memberRef":       "customer_27821234567",
    "amount":          15000,
    "pointsRequested": 500
  }'

Response — no constraint

200 OK
{
  "pointsToRedeem":     500,
  "discountAmount":     50,
  "discountAmountRand": 0.50,
  "pointsPerRand":      10,
  "balanceAfter":       150,
  "constraintApplied":  null
}

Response — constraint applied

200 OK
{
  "pointsToRedeem":     300,
  "discountAmount":     30,
  "discountAmountRand": 0.30,
  "pointsPerRand":      10,
  "balanceAfter":       350,
  "constraintApplied":  "MAX_DISCOUNT_PERCENT_OF_BASKET"
}

When constraintApplied is set, show the customer: "Maximum discount on this basket is discountAmountRand"

Redeem Quote — API Reference