Link Search Menu Expand Document

Redeeming vouchers

Contents

Overview

  • Call name: redeem-voucher
  • Endpoint URL: https://api0.spaaza.com/auth/redeem-voucher
  • Request methods: POST, PUT
  • Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
  • Response Content-Type: application/json
  • Auth required: yes

An endpoint to fully or partially redeem a basket or honour Voucher. More information on how vouchers work in Spaaza in general can be found on the Vouchers page of this site.

Permissions and Authentication

This API call requires a valid Spaaza session. The session can be as follows:

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

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter       Description
voucher_key (string, mandatory if not using voucher_id) A unique voucher key for each basket voucher to be redeemed.
voucher_id (integer, mandatory if not using voucher_key) A unique voucher ID for each basket voucher to be redeemed. This can be used instead of voucher_key.
chain_id (integer, mandatory) The particular chain_id for the Chain you’re requesting.
user_id (integer, optional) A user_id can be passed but it is not required. If no user_id is passed and the voucher does not have an associated user then the voucher will be redeemed without a user attributed to it. If the voucher already has a user associated with the voucher and no user_id is passed then the voucher will be redeemed as normal.
amount (float, optional) The amount is the amount of the voucher to be redeemed. If amount is not set then the maximum possible amount of the available voucher will be redeemed. If an amount value is set then that amount will be redeemed and if there is some value remaining on the voucher then, by default, according to campaign logic, a new regenerated voucher will be created.

Response

Returns an OK code and echoes the updated voucher details including the new voucher_status field. A sample is below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "voucher_key": "b45069f0c789fe686b7d538eb97b6d017225a119e43733f73ccd230f12024eb5",
        "voucher_id": 438595,
        "voucher_created_datetime": "2021-03-16T13:14:32+00:00",
        "voucher_type": "basket",
        "voucher_status": "redeemed",
        "voucher_locked": false,
        "campaign_id": 300,
        "campaign_type": "loyalty",
        "campaign_title": "ACME Loyalty Campaign",
        "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": "2050-06-12 15:41:40",
        "voucher_expiry_seconds_remaining": 922690040,
        "task": {
            "task_id": 450,
            "task_type": "create voucher",
            "title": "no_amount"
        },
        "voucher_redeemed_datetime": "2021-03-17T08:54:10+00:00",
        "generating_return_transaction": [],
        "parent_voucher": null,
        "voucher_title": "no_amount",
        "voucher_text": "no_amount",
        "voucher_description": "voucher text",
        "voucher_notes": "Noted again and again!",
        "voucher_honour_code": "",
        "voucher_image_url": null,
        "voucher_discount_ratio": 0,
        "voucher_currency_id": 2,
        "voucher_currency_symbol": "€",
        "voucher_amount_original": 10,
        "voucher_amount_redeemed": 2,
        "voucher_amount": 2,
        "redeeming_basket": [],
        "user_id": null,
        "user_entity_card": null,
        "regenerated_voucher": {
            "voucher_key": "91c187e8b1d078983302380d76c2029dfb2274a09b32605b15e548b2e698cadc",
            "voucher_id": 439468,
            "voucher_created_datetime": "2021-03-17T08:54:10+00:00",
            "voucher_type": "basket",
            "voucher_status": "generated",
            "voucher_locked": false,
            "campaign_id": 300,
            "campaign_type": "loyalty",
            "campaign_title": "ACME Loyalty Campaign",
            "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": "2050-06-12 15:41:40",
            "voucher_expiry_seconds_remaining": 922690040,
            "voucher_redeemed_datetime": null,
            "generating_return_transaction": [],
            "parent_voucher": {
                "voucher_id": 438595,
                "voucher_key": "b45069f0c789fe686b7d538eb97b6d017225a119e43733f73ccd230f12024eb5",
                "voucher_redeemed_datetime": "2021-03-17T08:54:10+00:00",
                "voucher_amount_original": 10,
                "voucher_amount_redeemed": 2,
                "voucher_amount": 10,
                "redeeming_basket": []
            },
            "voucher_title": "no_amount",
            "voucher_text": "no_amount",
            "voucher_description": "voucher text",
            "voucher_notes": "Noted again and again!",
            "voucher_honour_code": null,
            "voucher_image_url": null,
            "voucher_discount_ratio": 0,
            "voucher_currency_id": 2,
            "voucher_currency_symbol": "€",
            "voucher_amount_original": 8,
            "voucher_amount_redeemed": 0,
            "voucher_amount": 8,
            "redeeming_basket": []
        },
        "result_type": "redeem-voucher"
    }
}