Skip to main content
POST
/
me
/
redemptions
Redeem a voucher at an outlet
curl --request POST \
  --url http://localhost:4000/me/redemptions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "voucherId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "outletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "pin": "4829",
  "consumerLat": 0,
  "consumerLng": 0,
  "gpsAccuracyMeters": 1
}
'
{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "voucherId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "outletId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "cycleKey": "<string>",
  "gpsAvailable": true,
  "gpsDistanceMeters": 123,
  "code": "<string>",
  "redeemedAt": "2023-11-07T05:31:56Z"
}

Authorizations

​
Authorization
string
header
required

Bearer JWT signed by your app, with iss matching the issuer registered on the partner record. Verified against your JWKS URL or static public key.

Body

application/json
​
voucherId
string<uuid>
required

The voucher being redeemed.

​
outletId
string<uuid>
required

The outlet the user is physically at.

​
pin
string
required

4-digit PIN the outlet staff enters. Compared bcrypt-side; case-sensitive.

Pattern: ^\d{4}$
Example:

"4829"

​
consumerLat
number

Optional. Device latitude. Required to record status=SUCCESS; otherwise the redemption is flagged.

Required range: -90 <= x <= 90
​
consumerLng
number

Optional. Device longitude. Must be provided together with consumerLat.

Required range: -180 <= x <= 180
​
gpsAccuracyMeters
number

Optional. Reported accuracy of the GPS fix; stored for audit.

Required range: x >= 0

Response

Redemption committed.

Redemption committed.

​
id
string<uuid>
​
userId
string<uuid>
​
voucherId
string<uuid>
​
outletId
string<uuid>
​
cycleKey
string

Bucket key for the voucher's refresh cycle (e.g. 2026-05 for monthly).

​
status
enum<string>
Available options:
SUCCESS,
FLAGGED
​
flagReason
null | enum<string>

Set when status=FLAGGED.

Available options:
outlet_not_geolocated,
gps_unavailable,
null
​
gpsAvailable
boolean
​
gpsDistanceMeters
null | number
​
code
null | string

Dispensed voucher code when the voucher is configured with MANUAL/AUTO codes. Show this to the user.

​
redeemedAt
string<date-time>