Link Search Menu Expand Document

Adding a completed basket

Overview

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

This API call allows the uploading of a basket of products which have been bought at a retailer by a shopper once the transaction has closed. This is generally used to i) generate analytics figures for the retailer; ii) generate purchase history for shoppers who are Spaaza members which can be used to provide a more personalised shopping experience in future; and iii) update the status of any shopper vouchers or associated member profile records.

The shopper can be represented as a member of a Spaaza programme, as a member of another programme, or not be represented, in which case the basket is considered to be “anonymous”.

In general use of this API call is as a follow-up to the get-basket-price call which returns adjustments to the shopper’s provisional basket.

The basket information and other fields/parameters are JSON-encoded and POSTed as a single JSON file with content type application/json. Assuming that no error conditions are encountered, the call returns a JSON object containing various information, including a response for each basket item submitted.

Version-specific information

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

Version Change details
>= 1.4.2 Allow float values for basket item quantities

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.

Permissions

This API call requires the following permissions scenarios: Write permissions for the entity on behalf of which the call is being made.

Creating baskets

curl "https://api0.spaaza.com/auth/add-basket"

An example POST to add a basket

{
  "entity": {
      "entity_type": "chain",
      "entity_id": 1739,
      "branch_business_owner_code": "501",
      "branch_business_id": 1341,
      "employee_code": "AMS_007",
      "employee_name": "James Bond"
  },
  "user": {
      "member_programme": "spaaza",
      "member_number": "555555",
      "send_email_receipt": true
  },
  "basket": {
      "basket_platform_type": "in_store",
      "retailer_basket_code": "70401",
      "basket_country_code": "NL",
      "voucher_locking_code": "locking4001",
      "supplementary_basket_codes": [
          "2023334434434343434",
          "arf5546hu00223333333"
      ],
      "basket_total_price": 2653.85,
      "shipping_charge": 8.75,
      "payment_methods": [
          {
              "payment_method": "cash",
              "payment_amount": 2000
          },
          {
              "payment_method": "mastercard",
              "payment_amount": 653.85
          }
      ], 
      "basket_timestamp_iso8601": "2017-07-27T07:48:45+02:00",
      "basket_timezone_name": "Europe/Amsterdam",
      "basket_notes": "Notes text here",
      "basket_currency": {
          "currency_id": 2,
          "currency_code": "EUR"
      },
      "basket_tax": [
          {
              "tax_rate": 0.21,
              "tax_total": 521.00
          },
          {
              "tax_rate": 0.06,
              "tax_total": 36.29
          }
      ],
      "basket_items": [
          {
              "item_barcode": "2913458432854",
              "retailer_item_code": "line_0",
              "item_quantity": 3.0,
              "item_quantity_unit": "item",
              "item_price": 79.95,
              "item_subtotal": 224.85,
              "item_is_promotional": true
          },
          {
              "retailer_product_code": "WBGT0234",
              "retailer_item_code": "line_1",
              "item_type": "product",
              "item_quantity": 3,
              "excluded_from_spaaza": false,
              "item_price": 250.00,
              "basket_voucher_distribution": [
                {
                    "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                    "voucher_distribution_amount": 25.00
                }
              ]
          },
          {
              "item_barcode": "2913458439012",
              "retailer_item_code": "line_2",
              "item_quantity": 0.875,
              "item_quantity_unit": "kg",
              "item_price": 750.00,
              "basket_voucher_distribution": [
                {
                    "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                    "voucher_distribution_amount": 25.00
                }
              ]
          },
          {
              "item_barcode": "2913458434455"
              "retailer_item_code": "line_3",
              "item_quantity": 1,
              "item_price": 979.00,
              "item_is_promotional": true
          }
      ],
      "basket_vouchers": [
          {
              "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0"
          }
      ],
      "honour_vouchers": [
          {
              "voucher_key": "bb1e45cbd6d174164b77a58047779e8d0323fa9c61ac994d84223343c531334e"
          }
      ]
  }
}

An example response for an identified customer.

{
    "basket": {
        "id": 1163166,
        "chain_id": 1739,
        "basket_platform_type": "in_store",
        "currency_id": 2,
        "basket_total_price": 2653.85,
        "shipping_charge": 8.75,
        "basket_timestamp_iso8601": "2017-07-27T07:48:45+02:00",
        "basket_timezone_name": "Europe/Amsterdam",
        "basket_country_code": "NL",
        "retailer_basket_code": "70401",
        "voucher_locking_code": "locking4001",
        "payment_methods": [
            {
                "payment_method": "cash",
                "payment_amount": 2000
            },
            {
                "payment_method": "mastercard",
                "payment_amount": 653.85
            }
        ], 
        "basket_items": [
            {
                "spaaza_product_id": 1905743,
                "item_barcode": "2913458432854",
                "product_name": "Winter sweater",
                "retailer_item_code": "line_0",
                "item_quantity": 3.25,
                "item_is_promotional": true,
                "item_price": 74.95,
                "item_original_price": 79.95,
                "item_subtotal": 224.85,
                "is_identified": true,
                "excluded_from_spaaza": false,
            },
            {
                "item_barcode": null,
                "product_name": "Vest Kiara",
                "retailer_product_code": "WBGT0234",
                "retailer_item_code": "line_1",
                "item_type": "product",
                "item_quantity": 3,
                "item_is_promotional": false,
                "item_price": 250.00,
                "item_original_price": 250.00,
                "item_subtotal": 750.00,
                "is_identified": true,
                "excluded_from_spaaza": false,
                "basket_voucher_distribution": [
                    {
                        "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                        "voucher_type": "basket",
                        "voucher_distribution_amount": 25.00
                    }
                ],
                "purchase_progress_distribution": [
                    {
                        "purchase_progress_campaign_id": 76,
                        "purchase_progress_campaign_title": "Store Rewards",
                        "purchase_progress_campaign_type": "cashback",
                        "purchase_progress_distribution_amount": 37.50
                    }
                ]
            },
            {
                "item_barcode": "2913458439012",
                "product_name": "Leather gloves",
                "retailer_item_code": "line_2",
                "item_quantity": 1,
                "item_is_promotional": false,
                "item_price": 750.00,
                "item_original_price": 750.00,
                "item_subtotal": 750.00,
                "is_identified": true,
                "excluded_from_spaaza": false,
                "basket_voucher_distribution": [
                    {
                        "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                        "voucher_type": "basket",
                        "voucher_distribution_amount": 25.00
                    }
                ]
            },
            {
                "item_barcode": "2913458434455",
                "product_name": "Khaki pants",
                "retailer_item_code": "line_3",
                "item_quantity": 1,
                "item_is_promotional": true,
                "item_price": 979.00,
                "item_original_price": 979.00,
                "item_subtotal": 979.00,
                "is_identified": true,
                "excluded_from_spaaza": false,
            }
        ],
        "basket_vouchers_applied": [
            {
                "voucher_key": "bb1e45cbd6d174164b77a58047779e8d0323fa9c61ac994d84223343c531334e",
                "voucher_id": 112656,
                "voucher_status": "redeemed",
                "voucher_locked": true,
                "campaign_id": 402,
                "campaign_type": "loyalty",
                "campaign_title": "ACME Rewards",
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 1082631271,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_amount_original": 50.00,
                "voucher_amount_redeemed": 50.00,
                "voucher_amount": 50.00,
                "voucher_text": "Thanks for shopping with ACME",
                "voucher_basket_owner_code_exclusive": "",
                "voucher_locking_code": "locking4001",
                "voucher_type": "basket",
                "voucher_honour_code": null
            }
        ],
        "honour_vouchers_applied": [
            {
                "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                "voucher_id": 11268,
                "voucher_status": "redeemed",
                "voucher_locked": true,
                "campaign_id": 76,
                "campaign_type": "cashback",
                "campaign_title": "ACME Rewards",
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 1082631271,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_amount_original": 50.00,
                "voucher_amount_redeemed": 50.00,
                "voucher_amount": 50.00,
                "voucher_text": "Thanks for shopping with ACME",
                "voucher_basket_owner_code_exclusive": "",
                "voucher_locking_code": "locking4001",
                "voucher_type": "honour",
                "voucher_honour_code": "HON0042"
            }
        ],
        "return_transactions": [],
        "purchase_progress": [
            {
                "purchase_progress_campaign_id": 76,
                "purchase_progress_campaign_title": "Store Rewards",
                "purchase_progress_campaign_type": "cashback",
                "purchase_progress_amount": 37.50
            }
        ],
        "supplementary_basket_codes": [
            "2023334434434343434",
            "arf5546hu00223333333"
        ]
    },
    "user": {
        "member_programme": "spaaza",
        "member_number": "555555",
        "user_id": 268003,
        "send_email_receipt": true
    }
}

The following is the response from a basket upload for an anonymous user. Notice that the “user” parameter is now set to null:

{
  "result": {
      "code": 1,
      "status": "ok"
  },
  "results": {
    "user": null,
    "basket": {
        "id": 5,
        "business": {
            "id": 1411
        },
        "basket_timestamp_iso8601": "2017-07-27T07:48:45+02:00",
        "basket_timezone_name": "Europe/Amsterdam",
        "basket_country_code": "NL",
        "app_platform_type": "in_store",
        "currency": {
            "currency_id": 2,
            "currency_code": "EUR",
            "currency_name_en": "Euro",
            "currency_symbol": "€"
        },
        "total_value": 234.33,
        "owner_code": "70401",
        "items": [
            {
                "id": 3,
                "item_barcode": "2913458432854",
                "product_sale_price": 234.33,
                "item_quantity": 1,
                "retailer_item_code": "abcdef",
                "item_subtotal": 234.33
            }
        ]
    }
  },
  "result_type": "add-basket"
}

It is possible to upload a basket without specifying a shopper’s member number. In that case, pass in null as the parameter to “user”, instead of the user object.

Fields in the POSTed JSON

Identifying the Retailer (entity)

Details of the retailer which is submitting the basket.

Field Description
entity (required) Details of the retailer which is submitting the basket.
entity_type required The type of entity of the retailer. If the retailer is a chain with branches, this will be “chain”. If the retailer is an independent business with a single branch, this will be “business”.
entity_id required The Spaaza ID of the retailer entity.
branch_business_owner_code A retailer-specific branch code used by the retailer to identify individual branches in a chain. If the Spaaza-specific branch_business_id value is also supplied, then branch_business_id takes precedence. If the basket_platform_type is “in_store” and this value is not supplied, nor is a valid branch_business_id supplied, then the basket is recorded as a basket for the chain with no branch business_id associated with it and a warning is returned. In the case of most integrations with a POS or other in-store device this field is sent and the branch_business_id field is not used. If the basket_platform_type is “online” this field is not mandatory.
branch_business_id The Spaaza ID of the business to identify an individual branch in a chain. If the branch_business_owner_code value is also supplied, then branch_business_id takes precedence. If the basket_platform_type is “in_store” and this value is not supplied, nor is a valid branch_business_owner_code supplied, then the basket is recorded as a basket for the chain with no branch business_id associated with it and a warning is returned.
employee_code (string, max 64 chars) A number or string used to identify a retailer employee associated with the transaction. Commonly this may be a store assistant or other member of staff. If no employee is associated with the sale this field should not be included.
employee_name The name of a retailer employee associated with the transaction. This information is commonly used on electronic receipts and in analytics. If no employee is associated with the sale this field should not be included.

Sending Shopper Information (user)

The user section of the basket JSON is used to identify and to pass other information about the shopper making the purchase (or member of a retailer programme such as a loyalty programme). It is possible to use one of several identifiers to identify the customer - these are detailed in the “shopper identification fields” section.

General Fields

The following are general fields used to supply customer information:

Field Description
user (JSON object) The section of the JSON response describing the shopper (or member of a retailer programme such as a loyalty programme).
member_programme (string) The name of the membership programme the shopper is a member of. If this is not supplied, a default value of “spaaza” is assumed, implying the member_number being supplied is for a Spaaza membership programme. This can also be used to supply details of another membership programme.
send_email_receipt (boolean) Whether the shopper should receive an email receipt if the service is activated for this retailer.

Shopper Identification Fields

One of the fields below must be used if the shopper is to be identified. If it is not possible to identify the shopper, they are presumed to be anonymous. The possible fields are described below:

Field Description
member_number (string) The unique membership number or code for the shopper. If an unrecognised code or no code is given, the shopper is presumed to be anonymous. However, if a chain business opts to allow for anonymous returns, the shopper will be recognised by the member_number from the original_retailer_basket_code.
authentication_point_identifier (string) The ID of the customer on a third-party identity system, such as a webstore. In order to be used, this value must be known in the Spaaza system.
spaaza_user_id (integer) The Spaaza-unique user ID for the shopper. Used if known and if member_number and authentication_point_identifier are not used. It is not recommended to use this field unless the Spaaza ID of all shoppers is known.

Describing the Basket Contents (basket)

The section of the POSTed JSON providing information about the contents of the basket to be purchased by the shopper.

Field Description
basket_platform_type (string, optional) The type of platform supplying the basket. If this basket is being uploaded from a retail store, this should be set to “in_store”. If it’s coming from a store’s website, it should be set to “online”. In the case that this value is not supplied, this will be set to “in_store”.
retailer_basket_code (string, can be numeric, mandatory) Any identifier in the retailer’s system used to identify a particular user basket. This is stored by Spaaza and can be used to identify individual baskets at a later time, such as during any returns or refund process which may be in place. Please note that if a chain opts to be strict about repeated baskets, when an add-basket call is made with a retailer_basket_code which already exists in the Spaaza system, this will return a warning with Status Code 311 (basket_already_exists) and will return the previous existing basket.
voucher_locking_code (string, can be numeric, optional) A locking code which, when supplied, allows any locked basket vouchers supplied in the call to be redeemed if they have a matching voucher_locking_code - if the vouchers are locked and do not have a matching voucher_locking_code they will not be redeemed. This parameter takes precedence over retailer_basket_code when used for voucher locking, meaning that i) if there is a match between the voucher_locking_code of a basket and that of a voucher, the voucher will be redeemed regardless of any “retailer_basket_code_exclusive” value it has; and ii) if the voucher and basket have voucher_locking_code values which do not match, the voucher will not be redeemed, regardless of whether there is a match with the voucher’s retailer_basket_code_exclusive value.
supplementary_basket_codes (array, string elements which can be numeric, optional) An array containing one or many supplementary identifiers in the retailer’s system used to identify a particular user basket - for example a shipping code. This is stored by Spaaza and can be used to identify individual baskets at a later time, such as during any returns or refund process which may be in place.
basket_items_subtotal (float, optional) The total price of the basket sale/transaction to be paid by the shopper in currency for the items as calculated, before the subtraction (or addition) of any basket-level discounts or additions. This equates to the sum of each item_subtotal in the basket. This value is used to record the total gross revenue to the retailer for this basket, a value which is also used to calculate effects on member programmes such as loyalty schemes. If the total price of items in the basket does not add up to basket_total_price, the basket_total_price value is used for these calculations.
basket_total_price (float, recommended) The total price of the basket sale/transaction to be paid by the shopper in currency. This value is used to record the total gross revenue to the retailer for the items purchased in this basket, a value which is also used to calculate effects on member programmes such as loyalty schemes. If the total price of items in the basket does not add up to basket_total_price, the basket_total_price value is used for these calculations. If this field is not populated, a value of 0 is recorded rather than returning an error.
shipping_charge (float, optional) The amount paid by the customer for any shipping fees. This field can be removed or set to 0 if there is no shipping charge.
basket_notes (string, optional) Any text notes the retailer wishes to add for future analytics purposes. These are stored by Spaaza and can be retrieved later.

Setting the timestamp and timezone of the Basket

Setting the local time and timezone of the moment the basket was created is useful and is used for generation of receipts and other purposes. If these fields are omitted, Spaaza will set the timestamp of the basket and assume a UTC timezone.

Field | Description —- | ———————- basket_timestamp_iso8601 | The timestamp of the basket in ISO8601 extended format including timezone offset from UTC. Note that the timestamps of all baskets are converted to UTC (if not already in UTC) before storage in the Spaaza datastore. basket_timezone_name | The “tz database” timezone name - e.g. “Europe/Amsterdam” or “EST”. Note this field is optional. If the basket_timezone_name field does not the timezone offset in the basket_timestamp_iso8601 field, the basket_timezone_name field is used to store the value.

Currency used for the basket (basket_currency)

The section of the JSON response describing the currency used. If this section of the JSON is not included the default currency for the retailer is assumed, except in the case of a return item, where the currency used in the original purchase transaction of the returned item is assumed.

Field Description
currency_id The Spaaza ID of the currency used in the basket calculations. IDs for common currencies are 2 = EUR, 3 = GBP and 4 = USD.
currency_code The ISO-4217 three letter code of the currency used in the basket calculations. If the currency_id field is not supplied this field can be used exclusively.

Country code of the basket

Field Description
basket_country_code (string, 2 letters, optional) The ISO 3166-2 alpha-2 two-letter country code of the country the transaction is associated with, e.g. ‘NL’. If no basket_country_code field is supplied, the endpoint will attempt to use the country code of a branch, in the case of an in-store purchase, followed by the country code of the customer, if present.

Payment methods used for the basket (payment_methods)

The section of the JSON response describing the single or multiple methods used to pay for the basket.

Field Description
payment_method (string, max 64 chars) The payment method used, such as “mastercard” or “cash”.
payment_amount (float) The amount of the payment paid with this method.

For each payment method POSTed, both fields must be populated or else the payment method will not be recorded.

If a single “payment_method” is provided in the POSTed JSON, this is treated as if it were the first in the array and the “basket_total_price” value is used as the “payment_amount”.

If an error is detected in the payment methods POSTed a warning will be returned inline in the JSON response, but the basket will still be processed and no payment method saved.

Basket tax structure (basket_tax)

Multiple tax rates can be applied a basket. This section shows the total amount present for each tax rate.

Field Description
tax_rate A percentage rate at which tax is charged on this basket. For example, a value of 0.21 here equates to a 21% tax rate.
tax_total The total currency amount of tax paid at a particular rate

Items in the Basket (basket_items)

The section of the JSON describing the items in the basket is introduced with the following field:

Field Description
basket_items The list of items in the basket. Each item must contain a valid identifier to identify the product in the Spaaza system. For products for which a Personal Pricing campaign voucher has been supplied, the spaaza_product_id value must be supplied. If both are supplied, spaaza_product_id overrides retailer_product_code. Alternatively, you can specify a product by passing its item_barcode.

An item in the basket is identified as a product in the Spaaza data structure using one of a number of possible identifiers - with item_barcode being the most commonly-used parameter. Additionally, other information is supplied such as the price of the item, the quantity and whether the item is promotional.

One of the following identifiers must be used to identify the item:

Field Description
item_barcode (string, numeric allowed, mandatory) Preferred. The barcode used by the retailer to identify the inventory item. The inventory_barcode must already be included in the Spaaza inventory system if the product is to be recognised. For basket items where this value is used, it is not necessary to supply another product identifier. Most integrations with point of sale (POS) or webshops use this field exclusively.
retailer_product_code (string, optional, mandatory if no item_barcode value is supplied) The product or SKU identifier used by the retailer to identify the basket item. The retailer_product_code must already be included in the Spaaza system if the product is to be recognised. In most cases this is used as a fallback value.

Additionally, the following fields are used to supply the other information about the item in the basket:

Field Description
retailer_item_code (string) Any retailer-specific code applied by the retailer to the basket item.
item_type (string) The type of item in the basket. Possible values are “product”, “gift_certificate” and “shipping”. If this is missing then “product” will be assumed.
item_is_promotional (boolean) Can be set true or false to override any existing Spaaza record of whether an item is on promotion.
excluded_from_spaaza (boolean) Can be set true or false to override any existing Spaaza record of whether an item is on promotion.
item_quantity (float) The quantity of an item. If this is not supplied the quantity is assumed to be 1.
item_quantity_unit (string) The unit used for the quantity of the item. This could be “item” (the item is sold in single units, such as t-shirts), or another unit such as “kg” or “litres”. If no value is supplied, the unit is assumed to be “item.”
item_price (float) The original gross price being charged for 1 quantity unit of an item. Note that this does not change if the quantity is increased. Note also that if vouchers are being redeemed, this value does not reduce.
item_subtotal (float) The subtotal of the basket item - this is usually item_price multiplied by item_quantity
product_name The name of the product.

Basket-Level Discounts (basket_vouchers)

Discounts, standalone vouchers or loyalty reward redemptions which are calculated at the basket level (such as a shopper redeeming their loyalty rewards on a purchase, a promotional mechanic such as “buy 3 items from a range of qualifying products and only pay the price of 2 of them”, or a customer being given a one-time €10 discount voucher) are termed “basket vouchers” in the Spaaza basket. A basket voucher can be redeemed by specifying the unique “voucher_key” of the voucher in the “basket_vouchers” section of the JSON. In order to be redeemed a basket voucher should have a status of “claimed”, indicating it is ready to be redeemed by the customer.

The following fields are used to signal a basket voucher for redemption in a basket:

Field Description
basket_vouchers The section of the add-basket JSON which lists basket vouchers to be redeemed.
voucher_key A unique voucher key for each basket voucher to be redeemed.
voucher_id A unique voucher ID for each basket voucher to be redeemed. This can be used instead of voucher_key.

For each voucher_key or voucher_id value supplied, the Spaaza API carries out various checks, such as whether the voucher applies to this customer and that the status of the voucher is set to “claimed”. If the checks pass, the voucher status is set to “redeemed” so it cannot be used again and various other reconciliation actions may take place in the background according to the rules associated with the voucher. Note that, at this stage discounts may already have been applied in the partner system so the onus is on the partner logic to ensure beforehand (partly using other available Spaaza API endpoints) that the voucher is valid for this customer.

Overriding Spaaza-Calculated Basket Voucher Distribution (basket_voucher_distribution)

For each basket-level discount (“basket voucher”) redeemed in a basket, each item in the basket is assigned a proportion of the value of the voucher. This ensures that, should the item be returned, the correct action can be taken to reconcile the amount of the voucher spent on the item - for example by returning points to a customer’s loyalty wallet.

Normally the distribution of the value of basket vouchers across individual items in a basket is calculated automatically by this API endpoint and returned in the response, but it is possible to override this by supplying a distribution amount for a particular voucher inline in the JSON for a particular item. Note that this overrides all voucher distribution amounts for the same basket voucher for other items in the same basket, so it is necessary to supply a voucher distribution amount for each item in the basket for which an amount is intended - zero basket voucher distribution will be applied to items omitted.

Note also that manually overriding the automatically-generated distribution of a basket voucher for items in a basket overrides any background settings such as not allowing basket vouchers to be distributed over promotional items or forcing the redemption of the full value of a voucher in all cases. For example, if a basket voucher is created for a value of 10 currency units and only 8 of them are distributed, 2 unused currency units will be returned to the shopper regardless of other settings.

Distribution in the basket item:

Field Description
basket_voucher_distribution A list of basket-level vouchers which are applied at the item level. In the case that this is not supplied, the distribution method used in the previous step (get-basket-price) will be applied.
voucher_key A unique voucher key generated by Spaaza and used to identify a voucher and tie it to a member and a basket.
voucher_distribution_amount The amount of the voucher distributed to this basket item. This can be used to show a line-item discount on a receipt, for example.

Honour Vouchers (honour_vouchers)

Vouchers which are generated by or stored in Spaaza and used to redeem (“honour”) third-party promotions or other mechanics outside of Spaaza are termed “honour vouchers” in the Spaaza basket. When an honour voucher is redeemed, it can be included in the basket contents and Spaaza will update its status to redeemed. An honour voucher can be redeemed by specifying the unique “voucher_key” of the voucher in the “honour_vouchers” section of the JSON. In order to be redeemed a basket voucher should have a status of “claimed”, indicating it is ready to be redeemed by the customer.

The following fields are used to signal an honour voucher for redemption in a basket:

Field Description
honour_vouchers The section of the add-basket JSON which lists honour vouchers to be redeemed.
voucher_key A unique voucher key for each honour voucher to be redeemed.
voucher_id A Spaaza-unique voucher ID for each honour voucher to be redeemed. This can be used instead of voucher_key.

For each voucher_key or voucher_id value supplied, the Spaaza API carries out various checks, such as whether the voucher applies to this customer and that the status of the voucher is set to “claimed”. If the checks pass, the voucher status is set to “redeemed” so it cannot be used again and various other reconciliation actions may take place in the background according to the rules associated with the voucher. Note that, at this stage discounts may already have been applied in the partner system so the onus is on the partner logic to ensure beforehand (partly using other available Spaaza API endpoints) that the voucher is valid for this customer.

Possible error responses

The following represents a list of possible error responses for the add-basket endpoint:

Code Name and Description HTTP Status Code
3 http_vars_missing
This script is missing some required variables which must be submitted.
400
6 no_valid_session
The user needs to be logged in and a valid session key needs to be sent
401
68 permission_denied_or_non_existent
This user has insufficient permissions for this object or the object does not exist.
500
183 voucher_not_found
No voucher has been found matching this voucher_key or voucher_id.
404
228 auth_method_invalid
The given auth_method parameter has an invalid value.
500
231 currency_not_found
The given currency passed must exist in the list of currencies available
500
252 basket_currency_missing
The basket_currency information is missing from the basket.
500
262 app_platform_type_not_allowed
The app_platform_type submitted is not permitted.
400
265 authorization_invalid
The given authorization header is invalid.
400
266 access_token_invalid
The given access token is invalid.
401
267 no_valid_user
A valid username needs to be specified
401
309 original_basket_item_not_found
Could not find the original basket item for the owner code specified
400
311 basket_already_exists
A basket with this owner code has already been submitted
200
319 return_item_not_negative_value
A return item must have negative value
400
337 basket_platform_type_unrecognised
The basket_platform_type or app_platform_type is missing or unrecognised.
400
407 calculation_error
There has been a calculation error
400