Link Search Menu Expand Document

Unclaiming vouchers



  • Call name: unclaim-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

Unclaims a voucher (variable price or other kind of voucher) which has been claimed by a user.

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.

Note that if a voucher is locked it can only be unclaimed using Admin or Privileged authentication.

If the campaign has allows_end_user_to_claim_voucher set to false then only a user with privileged or admin authentication can unclaim 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 or third_party_id 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 unclaimed.

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": "a8c34c86c136e5ddf0ad374e140aa1e3504ebbf23d76d84788677268fd99b809",
        "voucher_id": 40577,
        "voucher_status": "generated",
        "voucher_locked": false,
        "campaign_id": 2,
        "campaign_type": "cashback",
        "campaign_title": "20 EUR voucher for every 200 EUR spent",
        "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
        "voucher_expiry_seconds_remaining": 1013819756,
        "voucher_currency_id": 2,
        "voucher_currency_symbol": "\u20ac",
        "voucher_amount_original": 20,
        "voucher_amount_redeemed": 0,
        "voucher_amount": 20,
        "voucher_text": "Your new voucher, enjoy!",
        "voucher_third_party_id": 3914599659,
        "user_id": 1,
        "user_entity_card": {
            "type": "regular",
            "code": "1"
        "result_type": "unclaim-voucher"