Get basket adjustments

Contents

• Overview
• Version-Specific Information
• Permissions and Authentication
• Constructing Baskets
  • Example basket JSON
• Fields In the Posted JSON
  • Identifying the Retailer
  • Sending Shopper Information
    • General fields
    • Shopper identification fields
    • Dummy shopper
    • Baskets with no shopper information (anonymous baskets)
  • Describing The Basket Contents
    • Setting the timestamp and timezone of the basket
    • Currency used for the basket
    • Country code of the basket
    • Payment methods used for the basket
    • Basket tax structure
    • Controlling voucher locking behaviour
    • Controlling the creation of dynamic vouchers
    • Items in the basket
• Interpreting the Response
  • Example JSON response
  • General Basket Information
    • Retailer information
    • Shopper information
  • Basket Contents
    • Timestamp and timezone of the Basket
    • Currency used for the basket
    • Country code of the basket
    • Payment methods used for the basket
    • Basket tax structure
    • Items in the basket
  • Discounts, Wallets and Vouchers
    • Vouchers applied
    • Voucher distribution
    • Honour vouchers
    • Wallet or progress amounts earned
    • Progress or wallet distribution
    • Vouchers created
• 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.

Important: It is important to note that it is possible to make repeated calls to the get-basket-price endpoint for the same transaction. For example, if a customer adds an item to the basket, or if they decide between the first and a subsequent request that they would like to redeem a voucher by setting its status to claimed. Basket state is not stored in Spaaza between get-basket-price requests and values sent in subsequent requests should not reflect any prices or other information received in the previous get-basket-price responses for the same transaction, or there may be a risk of discount values being multiplied erroneously.

Version-Specific Information

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

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": {
        "chain_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": 2717.98,
        "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": 717.98
            }
        ], 
        "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.125,
                "item_subtotal": 764.13
            },
            {
                "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)

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:

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:

Note if it is not possible to identify the shopper based on the fields supplied, the basket is considered to be an “anonymous” basket (see below) and a warning will be returned in the response.

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:

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)

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.

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.

Country code of the basket

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.

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.

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.

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.

Items in the Basket (basket_items)

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

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:

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

Note: In the subsequent add-basket call to add a basket, supplementary basket_item-level fields can be used to create a store of item and product metadata which can then be used to form segments used in Spaaza campaigns, populate item names on e-receipts and apps, and show sales performance analytics sliced by item, category, store, customer segment and other properties. More details can be found in the following document in this site: Creating products and product variants using the add-basket endpoint.

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 (although note that objects and elements in the response are in alphabetical order):

{
    "user": {
        "authentication_point_identifier": "1234567890",
        "member_number": "555555",
        "member_programme": "spaaza",
        "spaaza_user_id": 3928927
    },
    "basket": {
        "basket_country_code": "NL",
        "basket_notes": "Notes text here",
        "basket_platform_type": "in_store",
        "basket_total_price": 2703.85,
        "basket_total_price_adjusted": 2653.85,
        "retailer_basket_code": "70401",
        "shipping_charge": 8.75,
        "voucher_locking_code": "locking4001",
        "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.125,
                "item_price_adjusted": 241.674,
                "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": [
            {
                "campaign_id": 76,
                "campaign_owner_code": "ACME_CASHBACK_001",
                "campaign_product_promotion_type": null,
                "campaign_title": "Store Rewards",
                "campaign_type": "matching_item",
                "voucher_amount": 50,
                "voucher_amount_original": 50,
                "voucher_amount_redeemed": 50,
                "voucher_basket_owner_code_exclusive": "70401",
                "voucher_currency_id": 2,
                "voucher_currency_symbol": "€",
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 1082711675,
                "voucher_honour_code": null,
                "voucher_id": 84345653543,
                "voucher_key": "ac189592441c9c4e4d0a0f5be03216f6a7e026f0d482c44a293da8e373163fd0",
                "voucher_locked": true,
                "voucher_locking_code": "locking_4001",
                "voucher_status": "claimed",
                "voucher_text": "",
                "voucher_type": "basket"
            }
        ],
        "honour_vouchers_applied": [
            {
                "campaign_id": 79,
                "campaign_owner_code": "ACME_LOYALTY_001",
                "campaign_product_promotion_type": null,
                "campaign_title": "ACME loyalty",
                "campaign_type": "loyalty",
                "voucher_amount": 0,
                "voucher_amount_original": 0,
                "voucher_amount_redeemed": 0,
                "voucher_basket_owner_code_exclusive": "70401",
                "voucher_currency_id": null,
                "voucher_currency_symbol": null,
                "voucher_expiry_datetime_utc": "2050-01-01 00:00:00",
                "voucher_expiry_seconds_remaining": 1082711675,
                "voucher_honour_code": "honour0008",
                "voucher_id": 84345653544,
                "voucher_key": "ae8887274d771c676eeab406fddaa9c523875044d029ac91b8ac219f43e9972b",
                "voucher_locked": true,
                "voucher_locking_code": "locking_4001",
                "voucher_status": "claimed",
                "voucher_text": "",
                "voucher_type": "honour"
            }
        ],
        "payment_methods": [
            {
                "payment_method": "cash",
                "payment_amount": 2000
            },
            {
                "payment_method": "mastercard",
                "payment_amount": 653.85
            }
        ],
        "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"
            }
        ],
        "return_transactions": [],
        "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"
                }
        ]
    }
}

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

Shopper Information (user)

In the case that an identified user/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.

Basket Contents (basket)

The subsections below describe the fields returned in the basket section of the JSON response.

Top-level elements in the basket

The following top-level elements are returned in the basket section of the JSON response:

Timestamp and timezone of the Basket

Currency used for the basket (basket_currency)

Country code of the basket

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.

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.

Items in the basket (basket_items)

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

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:

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

Note: Supplementary fields can be used to create a store of item and product metadata which can then be used to form segments used in Spaaza campaigns, populate item names on e-receipts and apps, and show sales performance analytics sliced by item, category, store, customer segment and other properties. For more details please see the Creating products section of this site.

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:

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:

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:

Each mutation object in the mutations array contains the following fields:

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:

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:

Possible error responses

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