Link Search Menu Expand Document

Get basket adjustments

Introduction

  • Call name: get-basket-price
  • Endpoint URL: https://api0.spaaza.com/auth/get-basket-price
  • 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 provisional basket of products which are going to be bought at a retailer by a shopper in order to check for any Spaaza-related price adjustments. This call will look up information about the shopper and return an adjusted basket based on that individual shopper’s profile and activity. For each item in the basket, it will look up any applicable vouchers or loyalty programme adjustments and return the associated price and voucher information.

Once the client receives the response to this call, it is normal that the transction is confirmed with a call to the add-basket API call.

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”.

The basket information and other 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.

Uploading baskets for anonymous users

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.

JSON POST Request

The JSON file posted to the API call should be in the following format:

{
    "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"
    },
    "basket": {
        "basket_platform_type": "in_store",
        "retailer_basket_code": "70401",
        "voucher_locking_code": "locking4001",
        "supplementary_basket_codes": [
            "2023334434434343434",
            "arf5546hu00223333333"
        ],
        "basket_total_price": 2703.85,
        "basket_timestamp_iso8601": "2017-07-27T07:48:45+02:00",
        "basket_timezone_name": "Europe/Amsterdam",
        "basket_country_code": "NL",
        "shipping_charge": 8.75,
        "payment_methods": [
            {
                "payment_method": "cash",
                "payment_amount": 2000
            },
            {
                "payment_method": "mastercard",
                "payment_amount": 703.85
            }
        ], 
        "basket_notes": "Notes text here",
        "basket_vouchers_lock_exclusively": false,
        "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,
                "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.055,
                "item_quantity_unit": "kg",
                "item_price": 250.00
            },
            {
                "item_barcode": "2913458439012",
                "retailer_item_code": "line_2",
                "excluded_from_spaaza": false,
                "item_quantity": 1,
                "item_price": 750.00
            },
            {
                "item_barcode": "2913458434455",
                "retailer_product_variant_code": "70214506af",
                "retailer_item_code": "line_3",
                "item_quantity": 1,
                "item_price": 979.00,
                "item_is_promotional": true
            }
        ]
    }
}

Note that the arrangement of items and prices is provided for example and does not necessarily represent a real-world scenario.

Identifying the Retailer (entity)

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 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)

Field Description
basket required The section of the POSTed JSON providing information about the contents of the basket to be purchased by the shopper
basket_platform_type (string, optional, recommended) 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, mandatory) An 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, optional) A locking code which, when supplied, and when the basket_vouchers_lock_exclusively parameter is also supplied, is assigned to any vouchers which are automatically locked by the call to get-basket-price. If a voucher is locked with a voucher_locking_code it can only be redeemed by a call to add-basket using the same voucher_locking_code value. Note that, in the case of basket vouchers created on the fly by a “Basket Campaign” and representing a basket discount, any previously-created unredeemed and undeleted basket vouchers for the same customer with the same voucher_locking_code will be deleted before the creation of a new voucher.
supplementary_basket_codes (array, string elements) 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 format including timezone offset from UTC
basket_timezone_name The “tz database” timezone name - e.g. “Europe/Amsterdam” or “EST”. Note this field is optional and is not used for calculating timestamps but for returning timestamp names in API responses.

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.

Payment methods used for the basket (payment_methods)

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

It is not mandatory to POST payment methods to this call as they are often unknown at this stage.

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.

Controlling voucher locking behaviour (basket_vouchers_lock_exclusively)

Normally basket vouchers returned in the response to a get-basket-price call are locked for a default period of time in order to avoid an end customer removing or unclaiming the voucher before the purchase is complete. During the locking period it is still possible to redeem a claimed voucher in an add-basket call. It is also possible to use the basket_vouchers_lock_exclusively flag to control whether a voucher is locked in such a way that it can only be redeemed using an add-basket call with the same retailer_basket_code as the get-basket-price call performing the locking.

Field Description
basket_vouchers_lock_exclusively (optional, boolean) A field denoting whether any basket vouchers returned should be locked exclusively so that they can only be redeemed by an add-basket call with the same voucher_locking_code or retailer_basket_code as this call to get-basket-price. Not including this field or setting it to false will cause vouchers to be locked using the default behaviour, which is not to lock a voucher to a particular voucher_locking_code or retailer_basket_code.

Controlling the creation of dynamic vouchers (do_not_create_vouchers_dynamically)

The get-basket-price endpoint is designed to be able to create dynamic basket vouchers “on the fly” when campaigns (such as for basket-level discounts for certain customer segments) are configured to enable this. It is possible to override this using the do_not_create_vouchers_dynamically parameter at the basket level. It should be noted that this also has the effect of removing any automatic locking or adjustment of other vouchers.

It is recommended to use this parameter to improve performance when making large numbers of requests which don’t require any vouchers to be created or adjusted.

Field Description
do_not_create_vouchers_dynamically (optional, boolean) A field to override the default behaviour of creating basket vouchers dynamically when making a get-basket-price request for a customer.

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, mandatory) 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, optional) Any retailer-specific code applied by the retailer to the basket item.
item_type (string, optional) The type of item in the basket. Possible values are “product”, “gift_certificate” and “shipping”. If this parameter is missing then “product” will be assumed.
item_is_promotional (boolean, optional) Can be set true or false to override any existing Spaaza record of whether an item is on promotion. If this parameter is missing a default value of false is applied.
excluded_from_spaaza (boolean, optional) Can be set true or false to override any existing Spaaza record of whether an item is on promotion. If this parameter is missing a default value of false is applied.
item_quantity (float, optional) The quantity of an item. If this parameter is not supplied the quantity is assumed to be 1.
item_quantity_unit (string, optional) 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, mandatory) The gross price being charged for 1 quantity unit of an item. Note that this does not change if the quantity is increased.
item_subtotal (float, optional) The subtotal of the basket item - this is usually item_price multiplied by item_quantity. If this parameter is not supplied a default value of item_price multipled by item_quantity is applied.
product_name The name of the product.

JSON POST Response

A JSON response to the POST is sent in the following format:

{
    "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",
        "basket_country_code": "NL",
        "retailer_basket_code": "70401",
        "voucher_locking_code": "locking4001",
        "basket_total_price": 2703.85,
        "shipping_charge": 8.75,
        "payment_methods": [
            {
                "payment_method": "cash",
                "payment_amount": 2000
            },
            {
                "payment_method": "mastercard",
                "payment_amount": 653.85
            }
        ], 
        "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,
                "item_price": 79.95,
                "item_subtotal": 224.85,
                "item_is_promotional": true,
                "is_identified": true,
                "excluded_from_spaaza": false
            },
            {
                "item_barcode": null,
                "spaaza_product_id": 18605,
                "retailer_product_code": "WBGT0234",
                "retailer_item_code": "line_1",
                "item_type": "product",
                "item_quantity": 3,
                "item_price": 250.00,
                "item_is_promotional": false,
                "is_identified": true,
                "excluded_from_spaaza": false,
                "basket_voucher_distribution": [
                  {
                      "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                      "voucher_id": 84345653543
                      "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,
                    "contributing_campaign": {
                        "campaign_id": 500,
                        "campaign_title": "1 point for every €1 spent",
                        "campaign_title_localised": "1 point for every €1 spent",
                        "campaign_type": "cashback"
                    }
                  }
                ]
            },
            {
                "item_barcode": "2913458439012",
                "retailer_item_code": "line_2",
                "item_quantity": 1,
                "item_price": 750.00,
                "item_is_promotional": false,
                "is_identified": true,
                "excluded_from_spaaza": false,
                "basket_voucher_distribution": [
                  {
                      "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                      "voucher_id": 84345653543,
                      "voucher_distribution_amount": 25.00,
                  }
                ]
            },
            {
                "item_barcode": "2913458434455",
                "retailer_item_code": "line_3",
                "item_quantity": 1,
                "item_price": 979.00,
                "item_is_promotional": true,
                "is_identified": true,
                "excluded_from_spaaza": false
            }
        ],
        "basket_vouchers_applied": [
            {
                "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                "voucher_id": 84345653543,
                "voucher_status": "claimed",
                "voucher_locked": true,
                "campaign_id": 76,
                "campaign_type": "cashback",
                "campaign_title": "Store Rewards",
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 1082711675,
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_amount_original": 50,
                "voucher_amount_redeemed": 50,
                "voucher_amount": 50,
                "voucher_text": "",
                "voucher_type": "basket",
                "voucher_basket_owner_code_exclusive": "70401",
                "voucher_locking_code": "locking_4001",
                "voucher_honour_code": "honour0004"
            }
        ],
        "honour_vouchers_applied": [
            {
                "voucher_key": "ae8887274d771c676eeab406fddaa9c523875044d029ac91b8ac219f43e9972b",
                "voucher_id": 84345653544,
                "voucher_status": "claimed",
                "voucher_locked": true,
                "campaign_id": 79,
                "campaign_type": "loyalty",
                "campaign_title": "ACME loyalty",
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 1082711675,
                "voucher_currency_id": null,
                "voucher_currency_symbol": null,
                "voucher_amount_original": 0,
                "voucher_amount_redeemed": 0,
                "voucher_amount": 0,
                "voucher_text": "",
                "voucher_type": "honour",
                "voucher_basket_owner_code_exclusive": "70401",
                "voucher_locking_code": "locking_4001",
                "voucher_honour_code": "honour0008"
            }
        ],
        "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,
            "contributing_campaign": {
              "campaign_id": 500,
              "campaign_title": "1 point for every €1 spent",
              "campaign_title_localised": "1 point for every €1 spent",
              "campaign_type": "cashback"
            }
          }
        ],
        "supplementary_basket_codes": [
            "2023334434434343434",
            "arf5546hu00223333333"
        ],
        "basket_total_price_adjusted": 2653.85
    }
}

Note that the arrangement of items, prices, points, vouchers and other elements is provided for example purposes in order to demonstrate where fields and values may occur, and does not necessarily represent a real-world scenario.

The response can be described as follows:

Identifying the retailer

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-specifc branch code used by the retailer to identify individual branches in a chain. If the 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. 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 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.
employee_name The name of a retailer employee associated with the transaction. This information is commonly used on electronic receipts and in analytics.

Shopper Information (user)

In the case that an identified member is found based on the POST request, various details about the member are returned. In the case of an anonymous basket or the member not being found, these details are missing and various other details such as any Spaaza-specific discount information is not supplied.

Field Description
user The section of the JSON response describing the shopper (or member of a retailer programme such as a loyalty programme).
member_programme 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.
member_number 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.
send_email_receipt Whether the shopper should receive an email receipt if this service is activated for the retailer.

Describing the Basket Contents (basket)

Field Description
basket required The section of the POSTed JSON providing information about the contents of the basket to be purchased by the shopper
basket_platform_type 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 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.

Describing the timestamp and timezone of the Basket

Field Description
basket_timestamp_iso8601 The timestamp of the basket in ISO8601 format including timezone offset from UTC
basket_timezone_name The “tz database” timezone name - e.g. “Europe/Amsterdam” or “EST”. Note this field is optional and is not used for calculating timestamps but for returning timestamp names in API responses.

Currency used for the basket (basket_currency)

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.

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, should they have been posted.

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.

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 no payment methods have been POSTed then an empty “payment_methods” array will be returned.

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.
basket_items_subtotal 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 required 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 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_adjusted The total price of the basket sale/transaction to be paid by the shopper in currency. This is the amount calculated by Spaaza to be carried over to the next step add-basket
shipping_charge The amount paid by the customer for any shipping fees.
payment_method The method used to pay for the transaction.
basket_notes Any text notes the retailer wishes to add for future analytics purposes. These are stored by Spaaza and can be retrieved later.

Items in the Basket (basket_items)

Field Description
basket_items The list of items in the basket. Each item must contain either a product_id or a product_owner code value to identify the product in the Spaaza system. For products for which a MyPrice voucher has been supplied, the product_id value must be supplied. If both are supplied, product_id overrides retailer_product_code. Alternatively, you can specify a product by giving either its inventory_id or its inventory_owner_code (typically a bar code). Use of inventory id/owner code overrides the use of product id / owner code. Other values are optional.
spaaza_product_id The Spaaza product_id of the item sold. Note that, for products for which a MyPrice voucher has been applied to the price of the product, this value (or an inventory_owner_code or inventory_id value) must be supplied or the sale will not be registered properly for analytics purposes.
product_name The name of the product.
retailer_product_code The product ID used by the retailer (the “product owner”) to identify the basket item. The retailer_product_code must already be included in the Spaaza system if the product is to be recognised.
retailer_item_code Any retailer-specific code applied by the retailer to the basket item.
spaaza_product_variant_id The Spaaza product variant ID of the item sold. This will be used to look up the product for the basket item.
retailer_product_variant_code The product variant code used by the retailer to identify the product variant for the item in the basket.
item_type 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 Can be set true or false to override any existing Spaaza record of whether an item is on promotion.
item_barcode 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 a product_id.
item_quantity The quantity of an item. If this is not supplied the quantity is assumed to be 1.
item_price The adjusted gross price being charged for the single-quantity item. Note that this does not change if the quantity is increased.
item_subtotal The subtotal of the basket item - this is usually item_price multiplied by item_quantity

Basket-Level Discounts (basket_vouchers_applied)

Discounts or loyalty rewards which are calculated at the basket level (such as a shopper applying their loyalty rewards on a purchase or a promotional mechanic such as “buy 3 items from a range of qualifying products and only pay the price of 2 of them”) are viewed as “vouchers” and are also applied at the basket item level using a “basket_voucher_distribution” method. This is explained in this section.

Details of the basket-level voucher

Field Description
basket_vouchers_applied A list of any basket-level discounts which are applied to this basket.
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_id A unique voucher ID generated by Spaaza and used to identify a voucher and tie it to a member and a basket.
voucher_status The status of the voucher. In nearly all cases this is set to “claimed” as it has been claimed by the shopper but not yet redeemed.
voucher_locked Whether the voucher is locked. When a call is made to get-basket-price, the voucher is generally locked for a short period of time to allow the same basket to be confirmed during the subsequent add-basket call. This avoids fraud such as a discount being provided to the customer in the response to get-basket-price and the customer deleting the voucher (they are unable to do this if it’s locked) before the transaction is confirmed in the add-basket call.
campaign_id The Spaaza ID of the promotional campaign which is being applied.
campaign_type The type of Spaaza promotional campaign which is being applied. Spaaza has several different types of retail mechanic available which can be applied at the basket level.
campaign_title The title of the Spaaza promotional campaign which is being applied.
voucher_expiry_datetime_utc The date and time in UTC when the voucher is due to expire and no longer be available for transactions.
voucher_expiry_seconds_remaining The remaining time in seconds until expiry of the voucher.
voucher_currency_id The Spaaza ID of the denomination currency of the voucher.
voucher_currency_symbol The ISO-4217 currency symbol of the denomination currency of the voucher.
voucher_amount_original The original value of the voucher. In some cases it is not possible to redeem 100% of the voucher value, but this value is always set to the 100% value.
voucher_amount_redeemed The amount of the voucher value which is actually redeemed in this transaction. Any remaining value will be returned to the customer.
voucher_amount An amount equating to voucher_amount_redeemed value above.
voucher_text Any text description accompanying the voucher. This can be used in a receipt or displayed upon completion of purchase.
voucher_type The type of the voucher
voucher_basket_owner_code_exclusive A text string (which can be numeric recorded as a string) which has been chosen by the retailer in order to identity individual promotions or vouchers in an external system.
voucher_locking_code A text string (which can be numeric recorded as a string) chosen as a locking code. If this code is present and the voucher is locked, it cannot be redeemed without supplying a matching voucher_locking_code value in the call to add-basket
voucher_honour_code 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 as normal.

Distribution of the basket voucher over each basket item

Field Description
basket_voucher_distribution A list of basket-level vouchers which are applied to this purchase.
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_id A unique voucher ID 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_applied)

Vouchers which can be used to redeem (“honour”) third party promotions in systems such as webshops or POS devices. These are recognised by the 3rd-party ‘voucher_honour_code’.

All fields and properties of honour vouchers are the same as for basket vouchers (see “Basket-Level Discounts”) but the following should be noted about honour vouchers:

  • A monetary value is not necessary
  • A currency is not necessary
  • When redeemed, the value of an honour voucher is not recorded and no value is distributed over individual items in the basket

Distribution of the amount earned in a progress campaign over each basket item

Field Description
purchase_progress_distribution An amount of purchase progress from a purchase progress campaign which are applied to this purchase.
purchase_progress_campaign_id The Spaaza ID of the progress campaign
purchase_progress_campaign_title The name or title of the progress campaign
purchase_progress_campaign_type The type of campaign such as ‘cashback’ or ‘progress’.
purchase_progress_distribution_amount The amount of progress or currency which is applied to this individual basket item.

Purchase Progress (purchase_progress)

Any amounts earned in progress campaigns such as balance-based loyalty rewards or spending target-based programmes are recorded in this section of the response.

Field Description
purchase_progress Progress made in spending or progress campaigns on a per-campaign basis. This progress is also shown distributed on a per item basis in this response.
purchase_progress_campaign_id The Spaaza ID of a progress campaign.
purchase_progress_campaign_title The name or title of a progress campaign.
purchase_progress_campaign_type The type of campaign such as ‘cashback’ or ‘progress’.
purchase_progress_amount The amount of currency earned.

Processing Returns

The (simplified) JSON below illustrates an item being returned in the same basket as a sale item, with annotation of fields/parameters not explained elsewhere on this page:

{
    "entity": {
        "entity_type": "chain",
        "entity_id": "1739",
        "branch_business_owner_code": "0123"
    },
    "user": {
        "member_programme": "spaaza",
        "member_number": "123456"
    },
    "basket": {
        "basket_platform_type": "in_store",
        "retailer_basket_code": "50000123456",
        "basket_currency": {
            "currency_code": "EUR"
        },
        "basket_tax": [{
            "tax_rate": 21,
            "tax_total": 4.69
        }],
        "basket_total_price": 27.00,
        "basket_items": [
            {
                "item_barcode": "2000053021012",
                "item_quantity": 1,
                "item_price": 68.00
            },
            {
                "item_barcode": "4000053029999",
                "item_quantity": 1,
                "return_item": true,
                "item_price": -41.00,
                "original_retailer_basket_code": "500002016088"
            }
        ]
    }
}
{
    "user": {
        "member_number": "123456"
    },
    "basket": {
        "chain_id": 1739,
        "basket_platform_type": "in_store",
        "currency_id": 2,
        "basket_total_price": 27.00,
        "retailer_basket_code": "50000123456",
        "basket_items": [],
        "basket_vouchers_applied": [],
        "return_transactions": [{
            "basket_id": 338467,
            "returned_items": [{
                "item_id": 6157023,
                "return_price": -41.00,
                "quantity": 1,
                "owner_code": null,
                "sale_price": 41.00
            }]
        }],
        "purchase_progress": null,
        "basket_total_price_adjusted": 27.00
    }
}

Returned items can be handled inline in the same basket JSON by flagging items in the basket as return items. It is possible for a return item to be the only item in a basket, or mixed with other purchased items (and other returned items).

POSTing Return Items

Field Description
basket_total_price The total cash price paid for the basket. It is possible for this value to be negative if the price of items being returned is greater than the price of items being purchased.
return_item A boolean value indicating that this is an item being returned - set this to true for a return item.
item_price The single-quantity price of the item. In the case of a return, this is usually negative.
original_retailer_basket_code The retailer_basket_code (transaction ID or number) of the basket in which the item was originally purchased. Note that if there were also supplementary_basket_code values POSTed with the original basket then it is possible to use those instead. If both fields are supplied then the original_retailer_basket_code takes precedence.
original_supplementary_basket_code One of the supplementary_basket_code values of the basket in which the item was originally purchased.

Response to POSTed Return Items

Field Description
return_transactions An array of return transactions in a basket. Items from different original retailer baskets are separated into individual return transactions.
basket_id The Spaaza basket ID of the original purchase transaction.
returned_items An array of individual returned items.
item_id The original Spaaza item ID of the returned item.
return_price The price at which the item is being returned.
sale_price The price at which the item is originally sold.