Link Search Menu Expand Document

Claiming an existing basket

Contents

Overview

  • Call name: claim-basket
  • Endpoint URL: https://api0.spaaza.com/auth/claim-basket
  • Request methods: POST
  • Request Content-Type: multipart/form-data or application/x-www-form-urlencoded
  • Response Content-Type: application/json
  • Auth required: yes

Allows a basket to be claimed - assign a user to a basket which is not associated with a user (i.e. is “anonymous”) at the time the call is made.

If the transaction was originally recorded anonymously this endpoint will do the following:

  • Assign the basket to the user.
  • Issue any points, wallet credit, vouchers or other rewards the user is entitled to.

Note that the issuing of rewards is based on campaign configuration at the moment the basket is claimed rather than at the time the basket was originally added.

Version-specific information

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

Version Change details
None None

Permissions and Authentication

This API call requires a valid Spaaza session (see authentication). The session can be as follows:

  • User authentication: a session generated by an end-user login.
  • Admin authentication: the performing user needs to be logged in and have write access to the chain to which the claiming user is connected.
  • Privileged authentication: the use of privileged authentication is permitted for this endpoint.

Headers

The following headers can/must be passed to the API call:

Parameter Description
X-Spaaza-MyPrice-App-Hostname (mandatory in the case of user authentication, must not be passed otherwise) The hostname of the app which the user is associated with.

HTTP Parameters

The following HTTP parameters can be passed to the API:

Parameter Description
chain_id (integer, mandatory with admin and privileged authentication) The id of the chain to which the basket belongs.
user_id¹ (integer) the Spaaza ID of the user who is to be assigned to the basket
member_number¹ (string, can be numeric) the member or customer number of the user who is to be assigned to the basket
username¹ (string) the email address of the user who is to be assigned to the basket
authentication_point_identifier¹ (string, can be numeric) The id of the user in a third-party identity system such as a webstore.
basket_id² (integer) the Spaaza ID of the existing basket
retailer_basket_code² (string, can be numeric) Any identifier in the brand or retailer’s system used to identify the existing basket.
supplementary_basket_codes² (string, can be numeric) A supplementary identifier in the brand or retailer’s system used to identify the existing basket.

¹ Except in the case of user authentication, one of the parameters user_id member_number username authentication_point_identifier is mandatory in order to identify the user who is to be assigned to the basket.
² One of the parameters basket_id retailer_basket_code supplementary_basket_code is mandatory in order to identify the existing basket.

Claiming a basket

The following shows an example CURL request. This endpoint is also represented in the Spaaza Spaaza POSTMAN collection.

curl --location --request POST 'https://api0.spaaza.com/claim-basket' \
--header 'X-Spaaza-API-version: 1.4.1' \
--header 'X-Spaaza-Session-User-Id: 555' \
--header 'X-Spaaza-Session-Key: 4d0a01b194ba376a293cd64655e26b336373afafc6e7056b3202cf771f1ef095' \
--header 'Content-Type: application/x-www-form-urlencoded' \
--data-urlencode 'chain_id=56789' \
--data-urlencode 'basket_id=123456' \
--data-urlencode 'member_number=10000125'

The endpoint returns JSON showing the details associated with the basket. An example response is shown below:

{
    "result": {
        "code": 1,
        "status": "ok"
    },
    "results": {
        "basket": {
            "basket_country_code": null,
            "basket_items": [
                {
                    "excluded_from_spaaza": false,
                    "is_identified": false,
                    "item_barcode": "011891_000_0802_L",
                    "item_is_promotional": false,
                    "item_original_price": 300,
                    "item_price": 300,
                    "item_price_adjusted": 300,
                    "item_quantity": 1,
                    "item_quantity_unit": "item",
                    "item_subtotal": 300,
                    "item_subtotal_adjusted": 300,
                    "purchase_progress_distribution": [
                        {
                            "contributing_campaign": {
                                "campaign_id": 5,
                                "campaign_title": "20 EUR voucher for every 200 EUR spent",
                                "campaign_title_localised": "20 EUR voucher for every 200 EUR spent",
                                "campaign_type": "cashback"
                            },
                            "purchase_progress_campaign_id": 4,
                            "purchase_progress_campaign_title": "This is a wallet where your rewards accumulate",
                            "purchase_progress_campaign_title_localised": "This is a wallet where your rewards accumulate",
                            "purchase_progress_campaign_type": "wallet",
                            "purchase_progress_distribution_amount": 30
                        }
                    ],
                    "retailer_item_code": "f7889c5d54ec3e77b59c6f0aa0"
                },
                {
                    "excluded_from_spaaza": false,
                    "is_identified": false,
                    "item_barcode": "011892_000_0801_L",
                    "item_is_promotional": false,
                    "item_original_price": 100,
                    "item_price": 100,
                    "item_price_adjusted": 100,
                    "item_quantity": 1,
                    "item_quantity_unit": "item",
                    "item_subtotal": 100,
                    "item_subtotal_adjusted": 100,
                    "purchase_progress_distribution": [
                        {
                            "contributing_campaign": {
                                "campaign_id": 5,
                                "campaign_title": "20 EUR voucher for every 200 EUR spent",
                                "campaign_title_localised": "20 EUR voucher for every 200 EUR spent",
                                "campaign_type": "cashback"
                            },
                            "purchase_progress_campaign_id": 4,
                            "purchase_progress_campaign_title": "This is a wallet where your rewards accumulate",
                            "purchase_progress_campaign_title_localised": "This is a wallet where your rewards accumulate",
                            "purchase_progress_campaign_type": "wallet",
                            "purchase_progress_distribution_amount": 10
                        }
                    ],
                    "retailer_item_code": "3703822e403a1f160629d7fb98"
                }
            ],
            "basket_platform_type": "online",
            "basket_tax": [],
            "basket_timestamp_iso8601": "2022-01-11T16:17:57+00:00",
            "basket_timezone_name": "UTC",
            "basket_total_price": "400.00",
            "basket_vouchers_applied": [],
            "chain_id": 1,
            "currency_id": 2,
            "employee": {
                "employee_code": null,
                "employee_name": null
            },
            "honour_vouchers_applied": [],
            "id": 1,
            "last_updated_by": {
                "name": "Admin Spaaza",
                "user_id": 2
            },
            "last_updated_date": "2022-01-11 16:17:57",
            "payment_methods": [],
            "purchase_progress": [
                {
                    "contributing_campaign": {
                        "campaign_id": 5,
                        "campaign_title": "20 EUR voucher for every 200 EUR spent",
                        "campaign_type": "cashback"
                    },
                    "purchase_progress_amount": 40,
                    "purchase_progress_balance": 40,
                    "purchase_progress_balance_previous": null,
                    "purchase_progress_campaign_id": 4,
                    "purchase_progress_campaign_title": "This is a wallet where your rewards accumulate",
                    "purchase_progress_campaign_type": "wallet"
                }
            ],
            "regenerated_rewards": [],
            "retailer_basket_code": "abc_xyz",
            "return_transactions": [],
            "supplementary_basket_codes": null
        },
        "result_type": "claim-basket",
        "user": {
            "authentication_point_identifier": "CUST_00042",
            "member_number": "10000125",
            "member_programme": "spaaza",
            "spaaza_user_id": 45678901
        }
    }
}

Possible error responses

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

Code Name and Description HTTP Status Code
3 http_vars_missing
This script is missing some required variables which must be submitted.
400
6 no_valid_session
The user needs to be logged in and a valid session key needs to be sent
401
68 permission_denied_or_non_existent
This user has insufficient permissions for this object or the object does not exist.
500
183 voucher_not_found
No voucher has been found matching this voucher_key or voucher_id.
404
228 auth_method_invalid
The given auth_method parameter has an invalid value.
500
265 authorization_invalid
The given authorization header is invalid.
400
266 access_token_invalid
The given access token is invalid.
401
499 basket_already_claimed
The basket is already assigned to a user
400