Link Search Menu Expand Document

Locking vouchers

Returns an OK code and returns the details of the locked voucher:

  {
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "voucher_key": "0df3e1934e277240bd44072f302c75165dab108b6705d48695b38101634274ab",
        "voucher_id": 44974,
        "voucher_status": "claimed",
        "campaign_id": 2,
        "campaign_title": "20 EUR voucher for every 200 EUR spent",
        "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
        "voucher_expiry_seconds_remaining": 1126928505,
        "voucher_currency_id": 2,
        "voucher_amount": 20,
        "voucher_amount_redeemed": null,
        "voucher_text": "Your new voucher, enjoy!",
        "voucher_locked_until": "2018-10-16 15:54:01",
        "voucher_locking_code": "lock4001",
        "voucher_retailer_basket_code_exclusive": "RCPT401075452002",
        "user_id": 1,
        "user_entity_card": {
            "type": "regular",
            "code": "1"
        },
        "result_type": "lock-voucher"
    }
  }

Overview

  • Call name: lock-voucher
  • Endpoint URL: https://api0.spaaza.com/lock-voucher
  • Request methods: PUT
  • Request Content-Type: multipart/form-data or application/x-www-form-urlencoded (optional instead of DELETE params)
  • Response Content-Type: application/json
  • Auth required: yes

Lock a voucher which has already been created. Optionally add a period of time during which the voucher will be locked.

Note that currently, this logic only works for vouchers of type “basket voucher”.

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 chain to which the voucher 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 endpoint:

Parameter Description
voucher_key (string, mandatory*) The key of the voucher which is being locked. Typically, this information is retrieved from looking at the ‘progress’ or ‘wallet’ promotions in the result of the get-user-vouchers call.
voucher_id (integer, mandatory*) The ID of the voucher which is being locked.

* At least one of the parameters voucher_key or voucher_id must be used.

In the case of admin authentication, the following parameters can/must also be passed to the endpoint:

Parameter Description
retailer_basket_code (string, optional) this parameter ensures that, once the voucher is locked, it can only be redeemed during the lock period as part of a basket transaction with a retailer_basket_code matching this one. See get-basket-price and add-basket for more details of retailer_basket_code. This value can be an integer sent as a string.
voucher_locking_code (string, optional) this parameter ensures that, once the voucher is locked, it can only be redeemed as part of a basket transaction with a voucher_locking_code matching this one. If a voucher is locked with a voucher_locking_code, it must be redeemed by a basket transaction with a voucher_locking_code matching this value, regardless of the retailer_basket_code value sent. See get-basket-price and add-basket for more details of voucher_locking_code. This value can be an integer sent as a string.
voucher_lock_period The period in seconds for which the voucher should be locked. During this period it cannot be deleted except when redeemed as part of a basket transaction. It is highly recommended to lock the voucher for a period in the case of administrative login. The voucher_lock_period can be set to a minimum of 120 and a maximum of 3600 seconds. If no value is passed, the voucher_lock_period is set to a period of 300 seconds.