Get basket adjustments
Contents
- Overview
- Version-Specific Information
- Permissions and Authentication
- Constructing Baskets
- Fields In the Posted JSON
- Interpreting the Response
- Possible error responses
Overview
- 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 transaction 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.8 | Response JSON: new structure for purchase_progress array and addition of vouchers_created array |
>= 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
for the chain on behalf of which the call is being made. - Privileged authentication: the use of privileged authentication is permitted for this endpoint.
Constructing Baskets
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.
Example basket JSON
There follows sample JSON for a POST request and response. The Spaaza POSTMAN collection also contains more samples - details here.
An example POST to send a provisional 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"
},
"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",
"apply_refunds": true,
"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.
Fields in the POSTed JSON
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_owner_code takes precedence. If this value is not supplied, nor is a valid branch_business_id supplied, or if this value is supplied and there is no branch found with a matching branch_business_owner_code , then the basket is recorded as a basket for the chain with no branch 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, although often this value is used to identify an e-commerce channel. |
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_owner_code takes precedence assuming its value can be resolved to a valid branch in the Spaaza backend. If this value is not supplied, nor is a valid branch_business_owner_code supplied, or if this value is supplied and there is no branch found with a matching branch_business_id , 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. |
Dummy shopper
It is possible to apply a “dummy” shopper account in order to force the endpoint to simulate a shopper-specific response, such as the number of points to be earned for a transaction or discounts which would be applied. In addition, it is possible to specify a segment ID which the dummy customer is a member of. The following fields are used to specify a dummy shopper:
Field | Description |
apply_artificial_user | (boolean, optional) Whether to use a dummy shopper in the request. Any previously-identified “real” shoppers specified in the user section override this setting and cause a dummy shopper (and segment) not to be applied. |
artificial_segment_ids | (array of strings, optional) The IDs of customer segments (managed in Spaaza Console). If this parameter is used the dummy shopper will “match” any segments associated with campaigns. If this parameter is not specified or its array is empty, the “Opted-in Customers” standard segment will be used if a dummy shopper is deployed. |
If a dummy shopper is applied, the do_not_create_vouchers_dynamically
parameter will be set to true automatically.
An example of dummy shopper JSON is as follows:
"user": {
"apply_artificial_user": true,
"artificial_segment_ids": [
"AXwrhxrBxvui4MoE3uLw",
"AXXb2XNQlg22bgNfhlbI"
]
}
Baskets with No Shopper Information (anonymous baskets)
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.
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 (see ‘Controlling voucher locking behaviour’ below), 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. |
apply_refunds | (boolean, optional, default true) Whether to refund rewards redeemed on previously-purchased items which are returned in a basket. See information about returns for more information. The value of this field does not affect the processing of rewards earned on the previously-purchased item. If this field is omitted, the value is assumed to be true. |
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. If the basket_timestamp_iso8601 field does not contain the timezone offset, 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 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)
Voucher locking is a method used to prevent fraud. See the voucher locking section for more information.
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 . |
NOTE when using percentage discount vouchers (with type ‘basket_pct’) you MUST set the basket_vouchers_lock_exclusively
flag to true
in this request as an anti-fraud measure, and the voucher can only be redeemed by an add-basket
call with a matching code. This is because the voucher is assigned a monetary value during the get-basket-price
call and it might be possible for it to be redeemed by another call were this flag not set.
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, default “product”) The type of item in the basket. Possible values are “product”, “gift_certificate” and “shipping”. |
item_is_promotional | (boolean, optional, default false) Can be set true or false to override any existing Spaaza record of whether an item is on promotion. |
excluded_from_spaaza | (boolean, optional, default false) Can be set true or false to exclude an item from all Spaaza campaigns. |
item_quantity | (float, optional, default 1) The quantity of an item. |
item_quantity_unit | (string, optional, default “item”) 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”. |
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_original_price | (float, optional) The original price of the item. This is not used in the get-basket-price call. |
item_subtotal | (float, optional, default item_price * item_quantity ) The subtotal of the basket item - this is usually item_price multiplied by item_quantity. |
product_name | (string, optional) The name of the product. |
Note: Return items are also represented within the basket_items
array, but are covered by separate documentation in the returns section of the documentation.
Interpreting the Response
Example JSON Response
A response to the POST is sent which is equivalent to the following sample JSON:
{
"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
},
{
"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_price_adjusted": 79.95,
"item_subtotal": 224.85,
"item_subtotal_adjusted": 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,
"item_price_adjusted": 241.67,
"item_subtotal": 750,
"item_subtotal_adjusted": 725,
"item_is_promotional": false,
"is_identified": true,
"excluded_from_spaaza": false,
"basket_voucher_distribution": [
{
"voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
"voucher_id": 84345653543,
"voucher_distribution_amount": 25
}
],
"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,
"item_price_adjusted": 725,
"item_subtotal": 750,
"item_subtotal_adjusted": 725,
"item_is_promotional": false,
"is_identified": true,
"excluded_from_spaaza": false,
"basket_voucher_distribution": [
{
"voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
"voucher_id": 84345653543,
"voucher_distribution_amount": 25
}
]
},
{
"item_barcode": "2913458434455",
"retailer_item_code": "line_3",
"item_quantity": 1,
"item_price": 979,
"item_price_adjusted": 979,
"item_subtotal": 979,
"item_subtotal_adjusted": 979,
"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": [
{
"balance_new": 87.50,
"balance_previous": 50,
"campaign_id": 76,
"campaign_type": "points_wallet",
"is_default": true,
"mutations": [
{
"amount": 37.50,
"contributing_campaign_id": 500,
"contributing_campaign_title": "1 point for every €1 spent",
"contributing_campaign_title_localised": "1 point for every €1 spent",
"contributing_campaign_type": "cashback",
"log_message": "contribution from cashback",
"timestamp": "2023-05-08T12:35:53+00:00",
"type": "campaignContribution"
}
],
"title": "ACME Points Wallet"
},
{
"balance_new": 0,
"balance_previous": 0,
"campaign_id": 1255,
"campaign_type": "wallet",
"is_default": true,
"mutations": [],
"title": "ACME Monetary Wallet"
}
],
"supplementary_basket_codes": [
"2023334434434343434",
"arf5546hu00223333333"
],
"vouchers_created": [
{
"amount": 10,
"campaign_title": "ACME Loyalty Campaign",
"campaign_type": "loyalty",
"currency_code": "EUR",
"currency_symbol": "€",
"discount_ratio": 0,
"expiry_datetime_utc": "2023-07-08T12:35:53+00:00",
"id": null,
"key": "cb0a182488c05823ee8d0a35e52327d7138b559adc1cbe5edd4be2a73d76b9ac",
"loyalty_rule": {
"loyalty_rule_id": 88,
"loyalty_rule_type": "points_tracker"
},
"status": "generated",
"text": "Your Voucher",
"type": "basket"
}
],
"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:
General Basket Information
Retailer information
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. |
branch_business_id | The Spaaza ID of the business to identify an individual branch in a chain. |
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. |
Basket Contents (basket)
Field | Description |
---|---|
basket | 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. |
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 | 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)
Items in the basket are described in the basket_items
section of the JSON response. The following fields are returned for each item in the basket:
Field | Description |
---|---|
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 gross price being charged for the single-quantity item. Note that this does not change if the quantity is increased. |
item_price_adjusted | The adjusted (after basket vouchers and other discounts) price being charged for the single-quantity item. Note that this does not change if the quantity is increased. It is intended that the value of this field be used as the item_price field in the subsequent add-basket call. |
item_subtotal | The subtotal of the basket item - this is usually item_price multiplied by item_quantity |
item_subtotal_adjusted | The adjusted (after basket vouchers and other discounts) subtotal of the basket item - this is usually item_price_adjusted multiplied by item_quantity |
Note: Return items are also represented within the basket_items
array, but are covered by separate documentation in the returns section of the documentation.
Discounts, Wallets and Vouchers
See the vouchers section for more information on how vouchers work.
Vouchers applied (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 shown in the basket_vouchers_applied
array of the response.
The intention of showing applicable vouchers in the response is to allow the client to the apply the vouchers returned in the subsequent call to add-basket
so that the vouchers can be redeemed.
The distribution of voucher value at the basket item level is carried out using a “basket_voucher_distribution” method. This is explained in this section.
Details of each voucher in the basket_vouchers_applied
array:
Field | Description |
---|---|
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_locked_until | A datetime indicating the time until which the voucher is locked. |
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. |
Voucher distribution
Spaaza automatically calculates the distribution of the value of basket vouchers which are redeemed on individual items in a basket. 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. This is known as “voucher distribution” - i.e. distributing the value of the voucher over the items in the basket.
Note that the distribution of voucher value in a basket item also affects the net price paid for the item. The new per-single-unit price is reflected in the item_price_adjusted
field of the basket item in the response.
In the response, how the value of the voucher is apportioned to each basket item is shown in the basket_voucher_distribution
array under each basket item. The following key fields are returned:
Field | Description |
---|---|
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
Wallet or progress amounts earned (purchase_progress)
Any amounts earned in wallets or progress campaigns such as balance-based loyalty rewards or spending target-based programmes are recorded in the purchase_progress
array in the response. Each active wallet is returned as an element in the array, even if no points, wallet or purchase progress amounts have been awarded.
Each (points) wallet or purchase progress object in the array contains the following fields:
Field | Description |
---|---|
balance_new | The new balance of the wallet after the transaction. |
balance_previous | The old balance of the wallet before the transaction. |
campaign_id | The Spaaza ID of the wallet or purchase progress campaign. |
campaign_type | The type of campaign such as ‘wallet’, ‘points_wallet’ or ‘progress’. |
is_default | Whether this is the default wallet for the member. |
title | The name or title of the wallet or purchase progress campaign. |
mutations | An array of mutations to the wallet or purchase progress campaign. This array may contain no or multiple elements. |
Each mutation object in the mutations
array contains the following fields:
Field | Description |
---|---|
amount | The amount of currency awarded. |
contributing_campaign_id | The Spaaza ID of the campaign which contributed to this mutation. |
contributing_campaign_title | The name or title of the campaign which contributed to this mutation. |
contributing_campaign_type | The type of campaign which contributed to this mutation. |
log_message | A message describing the reason for the mutation. |
timestamp | The time in UTC at which the mutation was awarded. |
type | The type of mutation. |
Progress or wallet distribution
Spaaza automatically calculates the distribution of the amount earned in a progress or wallet campaign over each basket item in a basket. This ensures that, should the item be returned, the correct action can be taken to reconcile the amount of the progress or wallet campaign earned on the item - for example by reclaiming points from a customer’s loyalty wallet. This is known as “purchase progress distribution”
- i.e. distributing the amount earned in a progress or wallet campaign over the items in the basket.
The following fields are returned in each element of the purchase_progress_distribution
array under each basket item:
Field | Description |
---|---|
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. |
Vouchers created (vouchers_created)
Any vouchers created as a result of the basket transaction are returned in the vouchers_created
array in the response.
Each voucher in the array contains the following fields:
Field | Description |
---|---|
amount | An amount equating to voucher_amount_redeemed value above. |
campaign_title | The title of the Spaaza 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. |
currency_code | The ISO-4217 three letter code of the denomination currency of the voucher. |
voucher_currency_symbol | The ISO-4217 currency symbol of the denomination currency of the voucher. |
discount_ratio | The discount ratio of the voucher, denoting the percentage discount it may offer on a purchase. This is expressed as a decimal, where 0 is 0% discount and 1 is 100% discount. |
expiry_datetime_utc | The date and time in UTC when the voucher is due to expire and no longer be available for transactions. |
id | A unique voucher ID generated by Spaaza and used to identify a voucher and tie it to a member and a basket. |
key | A unique voucher key generated by Spaaza and used to identify a voucher and tie it to a member and a basket. |
loyalty_rule | An object describing any rule used to create the voucher and including the ‘loyalty_rule_id’ and ‘loyalty_rule_type’ fields |
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. |
text | Any text description accompanying the voucher. This can be used in a receipt or displayed upon completion of purchase. |
type | The type of the voucher |
Possible error responses
The following represents a list of possible error responses for the get-basket-price
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 |
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 |