Lock vouchers

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://{API hostname}/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".

Version-specific information

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

Version	Change details
>= 1.5.6	If a chain does not allow repeated use of retailer_basket_code values for baskets, an exclusive retailer_basket_code parameter will now generate a basket_already_exists error when an associated basket already exists.

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.