Link Search Menu Expand Document

Bulk Claiming vouchers

Contents

Overview

  • Call name: claim-vouchers
  • Endpoint URL: https://api0.spaaza.com/claim-vouchers
  • Request methods: POST
  • Request Content-Type: application/json
  • Response Content-Type: application/json
  • Auth required: yes

This endpoint allows a user with admin or privileged access to claim one or multiple vouchers on behalf of a user. Optionally, it is also possible to lock the vouchers for a specific period.

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
N/A N/A

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 chain to which the user is connected.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint. For privileged authentication, the X-Spaaza-MyPrice-App-Hostname header must be passed in the request.

Headers

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

Parameter Description
X-Spaaza-MyPrice-App-Hostname (mandatory in the case of privileged authenticaiton) The hostname of the app which the user is associated with.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
entity (string, mandatory) Details of the retailer which is submitting the request.
chain_id (integer, mandatory) The Spaaza Chain ID of the retailer entity.
user (mandatory) Details of the user who is submitting the request. At least one of user_id (integer), username (string, RFC5322-compliant email address), member_number (string, usually an integer value), authentication_point_identifier (string), auxiliary_identifier (string), referral_code (string) are required to identify the user.
vouchers An identifier for each voucher to be claimed. At least one of voucher_key (string), voucher_id (integer) and voucher_third_party_id (integer) are required identify each voucher to be claimed. A maximum of 10 vouchers can be claimed per API call.
locking (string, optional) This field is optional it possible to claim multiple vouchers without locking them. The maximum allowed voucher_lock_period is 3600 seconds (1 hour), the minimum is 120 seconds (2 minutes). If the voucher_lock_period is not provided the default locking period is 300 seconds (5 minutes). Either retailer_basket_code or voucher_locking_code must be provided if the voucher is only to be redeemed by a transaction or redemption action with a matching code.

Sample request 

    {
      "user": {
        "user_id": 4232324
      },
      "entity": {
        "chain_id": 1799
      },
      "vouchers": [
        {
          "voucher_key": "1b2bb233bbhhb21b1b1b1212121b21ubiu3243299"
        }
      ],
      "locking": {
        "retailer_basket_code": "20240462148435877",
        "voucher_lock_period": 3600
      }
    }

Returns an OK code and a JSON information of the claimed vouchers.:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "vouchers": [
            {
                "campaign_id": 1,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "campaign_image_filename": null,
                "campaign_image_link": null,
                "campaign_image_url": null,
                "campaign_owner_code": null,
                "campaign_product_promotion_type": null,
                "campaign_title": "Loyalty campaign for FOO Chain, inc.",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "Admin Spaaza",
                    "user_id": 2
                },
                "generating_return_transaction": null,
                "parent_voucher": null,
                "redeeming_basket": null,
                "user_entity_card": {
                    "code": "20000000001",
                    "type": "custom"
                },
                "user_id": 4,
                "voucher_amount": 20,
                "voucher_amount_original": 20,
                "voucher_amount_redeemed": 0,
                "voucher_created_datetime": "2024-04-24T15:37:06+00:00",
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "\u20ac",
                "voucher_description": null,
                "voucher_discount_ratio": 0,
                "voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
                "voucher_expiry_seconds_remaining": 7775999,
                "voucher_honour_code": null,
                "voucher_id": 1,
                "voucher_image_url": null,
                "voucher_key": "d333a0b891b473c9ddede5543043c01d5339a074ce19e0b2671e877fa33b990b",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_redeemed_datetime": null,
                "voucher_status": "claimed",
                "voucher_text": null,
                "voucher_third_party_id": null,
                "voucher_title": null,
                "voucher_type": "basket"
            },
            {
                "campaign_id": 1,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "campaign_image_filename": null,
                "campaign_image_link": null,
                "campaign_image_url": null,
                "campaign_owner_code": null,
                "campaign_product_promotion_type": null,
                "campaign_title": "Loyalty campaign for FOO Chain, inc.",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "Admin Spaaza",
                    "user_id": 2
                },
                "generating_return_transaction": null,
                "parent_voucher": null,
                "redeeming_basket": null,
                "user_entity_card": {
                    "code": "20000000001",
                    "type": "custom"
                },
                "user_id": 4,
                "voucher_amount": 20,
                "voucher_amount_original": 20,
                "voucher_amount_redeemed": 0,
                "voucher_created_datetime": "2024-04-24T15:37:06+00:00",
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "\u20ac",
                "voucher_description": null,
                "voucher_discount_ratio": 0,
                "voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
                "voucher_expiry_seconds_remaining": 7775999,
                "voucher_honour_code": null,
                "voucher_id": 2,
                "voucher_image_url": null,
                "voucher_key": "f7a59feb4393c73f717ac863320c008f96ba6221e3fa3ab3d0e90a21cf79619f",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_redeemed_datetime": null,
                "voucher_status": "claimed",
                "voucher_text": null,
                "voucher_third_party_id": null,
                "voucher_title": null,
                "voucher_type": "basket"
            },
            {
                "campaign_id": 1,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "campaign_image_filename": null,
                "campaign_image_link": null,
                "campaign_image_url": null,
                "campaign_owner_code": null,
                "campaign_product_promotion_type": null,
                "campaign_title": "Loyalty campaign for FOO Chain, inc.",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "Admin Spaaza",
                    "user_id": 2
                },
                "generating_return_transaction": null,
                "parent_voucher": null,
                "redeeming_basket": null,
                "user_entity_card": {
                    "code": "20000000001",
                    "type": "custom"
                },
                "user_id": 4,
                "voucher_amount": 20,
                "voucher_amount_original": 20,
                "voucher_amount_redeemed": 0,
                "voucher_created_datetime": "2024-04-24T15:37:06+00:00",
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "\u20ac",
                "voucher_description": null,
                "voucher_discount_ratio": 0,
                "voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
                "voucher_expiry_seconds_remaining": 7775999,
                "voucher_honour_code": null,
                "voucher_id": 3,
                "voucher_image_url": null,
                "voucher_key": "26fd293d39d9c621a6fb937faa1ee033de3a049fffdff1e11d914589a3788cf4",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_redeemed_datetime": null,
                "voucher_status": "claimed",
                "voucher_text": null,
                "voucher_third_party_id": null,
                "voucher_title": null,
                "voucher_type": "basket"
            },
            {
                "campaign_id": 1,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "campaign_image_filename": null,
                "campaign_image_link": null,
                "campaign_image_url": null,
                "campaign_owner_code": null,
                "campaign_product_promotion_type": null,
                "campaign_title": "Loyalty campaign for FOO Chain, inc.",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "Admin Spaaza",
                    "user_id": 2
                },
                "generating_return_transaction": null,
                "parent_voucher": null,
                "redeeming_basket": null,
                "user_entity_card": {
                    "code": "20000000001",
                    "type": "custom"
                },
                "user_id": 4,
                "voucher_amount": 20,
                "voucher_amount_original": 20,
                "voucher_amount_redeemed": 0,
                "voucher_created_datetime": "2024-04-24T15:37:06+00:00",
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "\u20ac",
                "voucher_description": null,
                "voucher_discount_ratio": 0,
                "voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
                "voucher_expiry_seconds_remaining": 7775999,
                "voucher_honour_code": null,
                "voucher_id": 4,
                "voucher_image_url": null,
                "voucher_key": "72f781ddd8a8ab121103de7a00243c50091344b47fcbff167afae09699066d72",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_redeemed_datetime": null,
                "voucher_status": "claimed",
                "voucher_text": null,
                "voucher_third_party_id": null,
                "voucher_title": null,
                "voucher_type": "basket"
            },
            {
                "campaign_id": 1,
                "campaign_image_dimension_x": null,
                "campaign_image_dimension_y": null,
                "campaign_image_filename": null,
                "campaign_image_link": null,
                "campaign_image_url": null,
                "campaign_owner_code": null,
                "campaign_product_promotion_type": null,
                "campaign_title": "Loyalty campaign for FOO Chain, inc.",
                "campaign_type": "loyalty",
                "creating_user": {
                    "full_name": "Admin Spaaza",
                    "user_id": 2
                },
                "generating_return_transaction": null,
                "parent_voucher": null,
                "redeeming_basket": null,
                "user_entity_card": {
                    "code": "20000000001",
                    "type": "custom"
                },
                "user_id": 4,
                "voucher_amount": 20,
                "voucher_amount_original": 20,
                "voucher_amount_redeemed": 0,
                "voucher_created_datetime": "2024-04-24T15:37:06+00:00",
                "voucher_currency_code": "EUR",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "\u20ac",
                "voucher_description": null,
                "voucher_discount_ratio": 0,
                "voucher_expiry_datetime_utc": "2024-07-23T15:37:06+00:00",
                "voucher_expiry_seconds_remaining": 7775999,
                "voucher_honour_code": null,
                "voucher_id": 5,
                "voucher_image_url": null,
                "voucher_key": "41a2eb41409dc7fa028100b6cede593effaf2bb520b1c1dbb7283327df9a86bd",
                "voucher_locked": false,
                "voucher_notes": null,
                "voucher_redeemed_datetime": null,
                "voucher_status": "claimed",
                "voucher_text": null,
                "voucher_third_party_id": null,
                "voucher_title": null,
                "voucher_type": "basket"
            }
        ],
        "result_type": "claim-vouchers"
    }
}