Link Search Menu Expand Document

Creating vouchers

Returns an OK code and returns the details of the created voucher

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
      "voucher_key": "0df3e1934e277240bd44072f302c75165dab108b6705d48695b38101634274ab",
      "voucher_id": 44974,
      "voucher_status": "generated",
      "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": 40,
      "voucher_amount_redeemed": null,
      "voucher_honour_code": "honour0004",
      "voucher_title": "€20 Voucher",
      "voucher_text": "Your new voucher, enjoy!",
      "voucher_description": "Redeem this voucher in store to get €20 off your purchase.",
      "voucher_notes": "Here is the place to put long-form notes such as terms and conditions or instructions for use.",
      "voucher_image_url": "https://www.example.com/voucher-image.jpg",
      "user_id": 1,
      "user_entity_card": {
          "type": "regular",
          "code": "1"
      },
      "result_type": "create-voucher"
  }
}

Overview

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

Creates a basket voucher for use in the next purchase.

Note that currently, this logic only works for vouchers from campaigns of type “wallet” and type “loyalty”.

The create call takes a ‘campaign id’ and a voucher amount.

In the case of a wallet campaign, the user being granted the voucher must have enough balance in the wallet for a voucher to be created.

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.

HTTP Parameters

The following HTTP parameters can be passed to the endpoint:

Parameter Description
campaign_id (integer, mandatory) The id of the wallet or loyalty campaign. Typically, this id is retrieved from looking at the ‘progress’, ‘wallet’ or ‘loyalty’ sections in the result of the get-card or get-user-vouchers call.
voucher_amount (float, mandatory in the case of ‘voucher_type’ being ‘basket’, prohibited in the case of ‘voucher_type’ being ‘basket_pct’) A floating point value greater than 0 and representing the value of the voucher.
set_claimed (boolean, optional) A boolean flag. When set to true, the generated voucher gets the voucher_status claimed immediately and will thus be directly used in the next sales transaction. Otherwise, the voucher gets the status generated, and must first be set to claimed in order to be used.
delete_existing (boolean, optional) A boolean flag. When set to true, any previous unlocked wallet vouchers will be deleted before creating a new wallet voucher.

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

Parameter Description
user_id or member_number (one or other mandatory for admin authentication in the case of ‘voucher_type’ being ‘basket’, user_id mandatory in the case of privileged authentication in the case of ‘voucher_type’ being ‘basket’) The id or member_number (user code) of the user for whom the permissions details are being requested.
voucher_type (string, optional, default ‘basket’) The type of voucher to be created. Possible options are ‘basket’ for a basket voucher, ‘basket_pct’ for a basket percentage voucher and ‘honour’ for an honour voucher
voucher_discount_ratio (float, maximum 3 decimal places, mandatory in the case of ‘voucher_type’ being ‘basket_pct’, prohibited in the case of ‘voucher_type’ being ‘basket’) A floating point value representing a decimal discount provided by this voucher. For example, a value of 0.25 represents a 25% discount.
voucher_lock_period (integer, optional) 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 or privileged authenticationn. 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.
voucher_locking_code (string, optional) If the voucher is locked this parameter ensures 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_title (string, optional, max 255 char.) A title to be used with the voucher.
voucher_text (string, optional, max 255 char.) A text string to be added to the voucher (which may be displayed in a client such as a browser or mobile app).
voucher_description (string, optional, max 1024 characters) A longer-form description for the voucher.
voucher_notes (string, optional, max 4095 char.) A field of notes to be added to the voucher which can be used for e.g. terms and conditions.
voucher_honour_code (string, mandatory with voucher_type ‘honour’, otherwise optional) A code which can be used to signal that the voucher should be honoured in a 3rd party system. For example, a promotional code can be used to signal to a webshop that this voucher should be redeemed and the customer issued with a free gift item. The webshop can then redeem the voucher using the traditional means.
voucher_image_url (string, optional) The URL of an image associated with the voucher.
retailer_basket_code (string, optional) If the voucher is locked this parameter ensures it can only be redeemed 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.
expiry_date (date, optional) The date after which the voucher should no longer be valid. This parameter can be in ‘Y-m-d’ date or ‘Y-m-d H:i:s’ format. If ‘Y-m-d’ format is used an expiry date is created using 00:00:00 as the time - e.g. ‘Y-m-d 00:00:00’. All times are in UTC.