Skip to main content

Get user vouchers

Get all vouchers for a user​

Contents​

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 systems
  • var_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.

VersionChange details
>= 1.6.5Voucher 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.0All 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 access to 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:

ParameterDescription
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(string, optional) Controls which vouchers are returned. Permitted values:
- existing (default) — returns only vouchers with a status of claimed or generated that have not yet expired. This is the value used when the parameter is omitted or set to any unrecognised value.
- all — returns all vouchers regardless of status or expiry, including redeemed and expired vouchers.

Headers​

The following headers can/must be passed to the API call:

ParameterDescription
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.

Response (redeemed voucher)​

Example response for a voucher that has already been redeemed (used). This is the same voucher object as in the Response example above, but in a redeemed state. Redeemed vouchers are only returned when the filter=all HTTP parameter is supplied (see HTTP parameters).

Compared with the claimed example, a redeemed voucher differs as follows:

  • voucher_status is redeemed.
  • voucher_redeemed_datetime is populated with the UTC timestamp at which the voucher was redeemed (it is null for vouchers that have not been redeemed).
  • voucher_amount_redeemed reflects the amount that was redeemed, and voucher_amount is adjusted to match the redeemed amount.
  • redemption_count reflects the number of times the voucher has been redeemed.
  • redeeming_basket describes the basket (transaction) in which the voucher was redeemed. It is null for vouchers that have not been redeemed.
{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "basket_vouchers": [
            {
                "voucher_id": 151011,
                "voucher_key": "5a5329f82d9a7d702cc17406487e75d23f43912e9ce7d51e82e5e0ba82186c21",
                "voucher_type": "basket",
                "voucher_status": "redeemed",
                "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": 10,
                "voucher_amount": 10,
                "voucher_redeemed_datetime": "2026-06-01T14:32:10+00:00",
                "voucher_text": "",
                "redemption_count": 1,
                "redeeming_basket": {
                    "basket_id": 9087654,
                    "branch_business_id": 1234,
                    "branch_owner_code": "ACME001",
                    "platform_type": "in_store",
                    "retailer_basket_code": "BASKET-2026-06-01-000123",
                    "total_value": 49.95
                },
                "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"
    }
}