Adding a completed basket

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
    • 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
    • Items in the basket
  • Basket Discounts and Vouchers
    • Voucher Distribution
    • Overriding Spaaza-Calculated Basket Voucher Distribution
  • Honour Vouchers
• Interpreting the Response
• Possible error responses

Overview

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

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

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

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

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

Note: Please note it is possible to add fields to item information in the add-basket endpoint in order to create a record of product information in Spaaza. This is useful for information displayed on receipts, for analytics purposes, and for campaign targeting. The required fields are not documented here, but in a separate document: Creating products and product variants using the add-basket endpoint.

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 add a basket:

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

An example response for an identified customer.

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

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

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

Fields in the POSTed JSON

Identifying the Retailer (entity)

Details of the retailer which is submitting the basket.

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.

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)

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

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 response describing the single or multiple methods used to pay for the basket.

Note that Spaaza records the payment methods used to pay for a basket, but no logic is applied to them and they are independent of other amounts in the basket.

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 to a basket. This section shows the total amount present for each tax rate.

Note that Spaaza records the tax rates applied to a basket, but no logic is applied to them and they are independent of other amounts in the basket.

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.

Note: Please note it is possible to add extra fields to item information in the add-basket endpoint in order to create a record of product information in Spaaza. This is useful for information displayed on receipts, for analytics purposes, and for campaign targeting. The required fields are not documented here, but in a separate document: Creating products and product variants using the add-basket endpoint.

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

Basket Discounts and Vouchers (basket_vouchers)

Discounts, standalone vouchers or loyalty reward redemptions are calculated and can be applied to a basket by passing details of the voucher(s) to be redeemed. Examples of this include: a shopper redeeming their loyalty rewards on a purchase, a promotional mechanic such as “buy 3 items from a range of qualifying products and only pay the price of 2 of them”, or a customer being given a one-time €10 discount voucher.

The concept of a “basket voucher” is used to record the discount or voucher redemption. More information on how vouchers work in Spaaza in general can be found on the Vouchers page of this site. Applying a basket voucher to a basket is called “redeeming” the voucher.

Whether a voucher is applied to all items in a basket, or only certain items, is controlled at the campaign level. When a voucher is redeemed in a basket, its value is spread over the items to which is it applied. This is known as “voucher distribution” - i.e. distributing the value of the voucher over the items in the basket. See the “Voucher Distribution” section below for more information.

A basket voucher can be redeemed by specifying the unique voucher_key or voucher_id of the voucher in the basket_vouchers section of the JSON POSTed to the endpoint. In order to be redeemed a basket voucher should have a status of “claimed”, indicating it is ready to be redeemed by the customer.

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

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

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.

The following points are important to note:

• If the value of a voucher is distributed over an item, the value of that distribution is shown in the response in the basket_voucher_distribution section for each item which the voucher value is distribued over.
• It is not possible to distribute more of the value of a voucher on an item than the value of the item itself. In the case of “standalone” monetary vouchers, if the value of the voucher is greater than the value of the items over which it is distributed, what happens to the non-redeemed portion of the voucher is determined by the campaign settings. The default behaviour is to create an additional voucher which can be used by the customer on a subsequent transaction.
• In order to correctly calculate the distribution of the value of basket vouchers across individual items in a basket, the item_original_price field must be populated for each item in the basket. This is the original gross price being charged for 1 quantity unit of an item.
• If the item_original_price field is not populated or is set to 0, the voucher distribution will be calculated based on the item_price field. Note that if the item_price field is set to 0 and the item_original_price field is not populated, the value of the voucher will not be distributed across the items in the basket because they are seen to have zero value.
• In the case of requests including basket vouchers to be redeemed that have been created on-the-fly by promotional campaigns, a voucher_distribution_estimated warning is generated if the item_original_price field is not populated, and an estimated distribution of vouchers is recorded.

It is possible to override the Spaaza-calculated voucher distribution (see “Overriding Spaaza-Calculated Basket Voucher Distribution” below), but this is not recommended.

Overriding Spaaza-Calculated Basket Voucher Distribution (basket_voucher_distribution)

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

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

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

Distribution in the basket item:

Honour Vouchers (honour_vouchers)

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

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

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

Interpreting the Response

Except for the xxxx_adjusted fields and the population of IDs of objects returned, the response to add-basket is broadly the same as the response to get-basket-price. Please consult that section of the documentation for more information.

Possible error responses

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