Link Search Menu Expand Document

Claiming vouchers



  • Call name: claim-voucher
  • Endpoint URL:
  • Request methods: POST or PUT
  • Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
  • Response Content-Type: application/json
  • Auth required: yes

Claims a voucher (variable price or other kind of voucher) which has been offered to a user.

The claim-voucher API allows a user to claim a voucher which has been earned through campaign rewards or through other voucher generation mechanisms. It uses the voucher identifier values supplied to claim the voucher. Once the voucher has been claimed it can be redeemed.

Please see the vouchers page for more information on vouchers and how they work in Spaaza.

Version-specific information

The following version-specific changes apply to this endpoint. See the versioning page for more details.

Version Change details

Permissions and Authentication

This API call requires a valid Spaaza session. The session 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 write access to the entity (business or chain) to which the user is connected.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.

If the campaign has allows_end_user_to_claim_voucher set to false then only a user with privileged or admin authentication can claim the voucher.


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

Parameter Description

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
voucher_key (string, mandatory if voucher_id or third_party_id not used to identify voucher) The unique voucher key generated for the voucher. This is a string, for instance c4bc4a3115e21e228936f4223dd89b22c238847c935514e1fdcb96f3c75118ac.
voucher_id (integer, mandatory if voucher_key or third_party_id not used to identify voucher) The unique id generated for the voucher. This is an integer, for instance 4064783. It is recommended to use the voucher_key parameter if possible.
third_party_id (integer, mandatory if voucher_id or voucher_key not used to identify voucher) The unique id generated for a voucher whill be generated when the chain has uses_third_party_voucher_id set true.
user_id (integer, mandatory with admin and privileged authentication) The Spaaza user id of the user whose voucher is being claimed.

At least one of the parameters voucher_key, voucher_id or third_party_id must be used to identify the voucher.

Sample request

The endpoint returns JSON showing the details associated with the voucher including the new value of the voucher_status field. An example is shown below:

    "result": {
        "code": 1,
        "status": "ok"
    "results": {
        "voucher_key": "13918dc12e44bc183cb168fa10684d0714115ff37132d4c265f4a8ab6678a741",
        "voucher_id": 35735,
        "voucher_status": "claimed",
        "voucher_locked": false,
        "campaign_id": 136,
        "campaign_type": "signup",
        "campaign_title": "Earn €5 on signup",
        "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
        "voucher_expiry_seconds_remaining": 996899028,
        "voucher_currency_id": 2,
        "voucher_currency_symbol": "€",
        "voucher_amount_original": 5,
        "voucher_amount_redeemed": 0,
        "voucher_amount": 5,
        "voucher_text": null,
        "voucher_third_party_id": 3914599659,
        "user_id": 1107604,
        "user_entity_card": {
            "type": "custom",
            "code": "404064"
        "result_type": "claim-voucher"