Get user vouchers
Get all vouchers for a user
Contents
- Overview
- Version-specific information
- Permissions and Authentication
- HTTP parameters
- Headers
- Example request & response
Overview
- Call name: get-user-vouchers
- Endpoint URL: https://{API hostname}/get-user-vouchers
- Request methods: GET
- Response Content-Type: application/json
- Auth required: yes
The get-user-vouchers API retrieves the applicable vouchers for a user, given the user's ID or entity card (member) number and the chain ID.
It will return:
basket_vouchers- vouchers that are available for redemption by an end-user.honour_vouchers- vouchers that are used to redeem rewards offers in 3rd party systemsvar_price_vouchers, which are vouchers for a specific product (Personal Pricing)
See the vouchers documentation for a more general overview of how vouchers work in the Spaaza system.
Version-specific information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| >= 1.6.5 | Voucher campaign details are returned in a nested campaign object instead of the legacy flat campaign_* voucher fields. The nested campaign object also includes an assignments array with the assigned business, barcode, business format, business region, currency, channel and group dimensions for each assignment, plus assignment_count, assignment_count_by_type and assignment_types_excluded to describe assignment counts. |
| >= 1.5.0 | All non-voucher fields (promotions and wallet) deprecated and will be removed in versions >= 1.5.1 - it is now recommended to use the get-campaigns endpoint for campaign information |
Permissions and Authentication
This API call requires valid Spaaza authentication. The authentication can be as follows:
- User authentication: a session generated by an end-user login.
- Admin authentication: the performing user needs to be logged in and have
read accessto the entity (chain) to which the user is connected. - Privileged authentication: the use of privileged authentication is permitted for this endpoint.
HTTP Parameters
The following HTTP parameters can be passed to the API:
| Parameter | Description |
|---|---|
| chain_id | (integer, mandatory for admin and privileged authentication) The id of the chain for which the information is being requested. |
| user_id or member_number or authentication_point_identifier | (mandatory for admin and privileged authentication) The id in the Spaaza backend (*user_id, integer), member number (*member_number, string) or identity in a third-party authentication system (authentication_point_identifier, string) of the user for whom the voucher details are being requested. |
| filter | (optional, permitted value all) when set to all, redeemed or 'used' vouchers will also be returned in the response together with expired vouchers that were not used. |
Headers
The following headers can/must be passed to the API call:
| Parameter | Description |
|---|---|
| X-Spaaza-MyPrice-App-Hostname | (mandatory in the case of user authentication, not required otherwise) The hostname of the app for which the user is requesting the card. |
Example Request & Response
Request
Example curl request:
curl --location 'https://{API hostname}/get-user-vouchers?chain_id=1743&member_number=3930589' \
--header 'X-Spaaza-Session-User-Id: 1548854' \
--header 'X-Spaaza-Session-Key: 564e5b4faa7f639dacf1983f1dae62155d5734b789b06b5986c43bfe2542854e' \
--header 'X-Spaaza-API-Version: 1.6.5'
Response
Example response. The nested campaign object on each voucher, including the assignments array, applies to API version 1.6.5 and above. See Version-specific information for how the response differs for earlier API versions.
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket_vouchers": [
{
"voucher_id": 151011,
"voucher_key": "5a5329f82d9a7d702cc17406487e75d23f43912e9ce7d51e82e5e0ba82186c21",
"voucher_type": "basket",
"voucher_status": "claimed",
"voucher_locked": false,
"voucher_expiry_datetime_utc": "2026-12-01T00:00:00+00:00",
"voucher_expiry_seconds_remaining": 18316800,
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "€",
"voucher_amount_original": 10,
"voucher_amount_redeemed": 0,
"voucher_amount": 10,
"voucher_text": "",
"campaign": {
"id": 57,
"type": "cashback",
"product_promotion_type": null,
"title": "Store Rewards",
"owner_code": "store-rewards",
"assignment_count": 2,
"assignment_count_by_type": {
"business": 1,
"currency": 0,
"group": 0,
"business_format": 0,
"business_region": 0,
"channel": 0,
"barcode_earn": 0,
"barcode_spend": 1
},
"assignment_types_excluded": [],
"assignments": [
{
"type": null,
"barcode": null,
"business": {
"id": 1234,
"name": "ACME Store 1",
"owner_code": "ACME001"
},
"business_format": null,
"business_region": null,
"currency": null,
"channel": null,
"group": null
},
{
"type": "spend",
"barcode": "8712345678901",
"business": null,
"business_format": null,
"business_region": null,
"currency": null,
"channel": null,
"group": null
}
]
}
}
],
"honour_vouchers": [],
"var_price_vouchers": [],
"wallet": null,
"result_type": "get-user-vouchers"
}
}
If a campaign has more assignment rows of a given type than the serialization limit, that type is omitted from assignments and listed in assignment_types_excluded. The assignment_count and assignment_count_by_type fields always reflect the full counts, including any types that were excluded from assignments.