Claiming an existing basket
Contents
- Overview
- Version-specific information
- Permissions and Authentication
- Headers
- HTTP Parameters
- Claiming a basket
- Possible error responses
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 accessto 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 |