Link Search Menu Expand Document

Get all vouchers for a user

Contents

Overview

  • Call name: get-user-vouchers
  • Endpoint URL: https://api0.spaaza.com/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.

Version Change details
>= 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 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:

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 (mandatory for admin and privileged authentication) The id in the Spaaza backend (user_id, integer) or member number (member_number, 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 (#request)

Example curl request:

curl --location 'https://api0.spaaza.com/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.5.0'

Response (#response)

Example response:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "basket_vouchers": [
            {
                "voucher_id": 896626,
                "voucher_key": "c40012d4deb2cc37c7e699f475f43576d47334aa8659367770ad301aeeaa6424",
                "voucher_created_datetime": "2023-11-01T17:38:35+00:00",
                "voucher_type": "basket",
                "voucher_status": "claimed",
                "voucher_locked": false,
                "campaign_id": 2106,
                "campaign_type": "signup",
                "campaign_product_promotion_type": null,
                "campaign_title": "Acme Signup",
                "campaign_owner_code": null,
                "campaign_image_filename": null,
                "campaign_image_url": null,
                "campaign_image_link": null,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "campaign_voucher_title_localised": "10€ voucher for signing up",
                "voucher_expiry_datetime_utc": "2024-10-31T17:38:35+00:00",
                "voucher_expiry_seconds_remaining": 22647172,
                "voucher_redeemed_datetime": null,
                "generating_return_transaction": null,
                "parent_voucher": null,
                "voucher_title": "10€ voucher for signing up",
                "voucher_text": "Acme Signup",
                "voucher_description": null,
                "voucher_notes": null,
                "voucher_honour_code": null,
                "voucher_image_url": null,
                "voucher_discount_ratio": 0,
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_amount_original": 10,
                "voucher_amount_redeemed": 0,
                "voucher_amount": 10,
                "redeeming_basket": null
            },
            {
                "voucher_id": 915837,
                "voucher_key": "90412e8de8f3cedd981113cca3e552a27656195bcef5ee9957e7ec29d355f127",
                "voucher_created_datetime": "2024-01-25T07:00:49+00:00",
                "voucher_type": "basket",
                "voucher_status": "generated",
                "voucher_locked": false,
                "campaign_id": 1695,
                "campaign_type": "birthday",
                "campaign_product_promotion_type": null,
                "campaign_title": "Happy Birthday",
                "campaign_owner_code": "ACME_BDAY_05AF04",
                "campaign_image_filename": null,
                "campaign_image_url": null,
                "campaign_image_link": null,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "voucher_expiry_datetime_utc": "2025-01-24T07:00:49+00:00",
                "voucher_expiry_seconds_remaining": 29952906,
                "voucher_redeemed_datetime": null,
                "generating_return_transaction": null,
                "parent_voucher": null,
                "voucher_title": null,
                "voucher_text": "Happy Birthday",
                "voucher_description": "null",
                "voucher_notes": "null",
                "voucher_honour_code": null,
                "voucher_image_url": "https://spaaza-customer-import-file-test01.s3.amazonaws.com/chain/1743/1743-1652901890154-20220518-192450000",
                "voucher_discount_ratio": 0,
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_amount_original": 10,
                "voucher_amount_redeemed": 0,
                "voucher_amount": 10,
                "redeeming_basket": null
            }
        ],
        "honour_vouchers": [],
        "promotions": {
            "basket": [],
            "birthday": [],
            "interaction": [],
            "item_purchase_count": [],
            "login": [],
            "loyalty": [],
            "matching_item": [],
            "product": [],
            "progress": [],
            "purchase_count": [],
            "referral": [],
            "signup": [],
            "wallets": {
                "points": [],
                "wallet": []
            }
        },
        "var_price_vouchers": [],
        "wallet": null,
        "result_type": "get-user-vouchers"
    }
}