Returning items inline in get-basket-price and add-basket endpoints
Contents
- Overview
- Return Currency
- Rules Surrounding Recognising the Original Purchase Basket/Transaction
- Fields Posted For a Return
- Fields in The Response For a Return
- Example Requests
Overview
This page documents fields needed when returning previously-purchased items inline in calls to the get-basket-price and add-basket endpoints. It focuses on the fields needed to return items in either of those endpoints.
Version-Specific Information
The following version-specific changes apply to this endpoint. See the versioning page for more details.
| Version | Change details |
|---|---|
| >= 1.5.5 | If it is not possible to match a returned item to an original purchase item, the item will be treated as a negatively-priced purchase item in the returning basket and the excluded_from_spaaza parameter will be set to true to avoid applying any Spaaza campaign logic to the item. |
| >= 1.5.4 | The endpoints now return a original_basket_item_not_found warning if a return item cannot be matched to an original purchase transaction (backwards compatible to version 1.0.0) |
Return Currency
In the case that a basket is received containing return items, but where the basket currency is not supplied, the currency of the original transaction of the last-supplied returned item is applied instead of the default currency of the retailer.
Rules Surrounding Recognising the Original Purchase Basket/Transaction
In order to reverse the effect of any points earned and points or vouchers spent on a original transaction, a return transaction needs to be able to look up the original transaction of a returned item. In general, it uses the ‘original_retailer_basket_code’ and ‘original_retailer_item_code’ fields to do this. There is some logic to be aware of here:
- The customer account associated with the return item is, by default, independent of the customer account associated with the “returning” transaction in which the return item is being returned. This means that it is possible for “customer B” to return an item bought by “customer A”, and, even if “customer B” also buys items in the transaction where the item is returned, “customer A” will be created with any points or voucher reversals.
- It is possible to return an item in a basket where the “returning” customer remains anonymous. In that case, whether the revenue associated with the “returning” basket (which may be negative or positive depending on whether other items are purchased in that basket), depends on the retailer’s settings in Spaaza.
- In the case of a return item which does not have an ‘original_retailer_basket_code’, if the returning transaction is associated with a customer then an attempt will be made to find the original purchase item based on the barcode (or other identifier) of the return item - all items purchased by the customer with the same barcode will be checked, and the most recent item which has not yet been returned will be assumed to be the original purchase item.
- If it is not possible to match the returned item to an original purchase item, the item will be treated as a negatively-priced purchase item in the returning basket and the
excluded_from_spaazaparameter will be set totrueto avoid applying any Spaaza campaign logic to the item. See Items in the basket in theget-basket-priceendpoint documentation and - Items in the basket in the
add-basketendpoint documentation for more information.
Fields Posted For a Return
Returned items can be handled inline in the same basket JSON by flagging items in the basket as return items. It is possible for a return item to be the only item in a basket, or mixed with other purchased items (and other returned items).
The following field descriptions focus on fields relevant to returns. Other fields are described in the documentation for the parent calls, get-basket-price and add-basket.
Basket-level
| Field | Description |
|---|---|
| basket_total_price | (float, recommended) The total cash price paid for the basket. This value is negative if the price of items being returned is greater than the price of items being purchased. |
| 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. |
Return item-level
| Field | Description |
|---|---|
| return_item | (boolean, mandatory) A boolean value indicating that this is an item being returned - set this to true for a return item |
| item_barcode | (string, numeric allowed, mandatory if no retailer_product_code value is supplied) Preferred. The barcode used by the retailer to identify the basket item. This must be the same barcode used in the original purchase transaction or else it will not be possible to retrieve the original purchase item from the backend and process voucher refunds and wallet mutation reversals. |
| 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. In most cases this is used as a fallback value. |
| item_price | (float, recommended) The single-quantity price of the item. In the case of a return, a negative value should be used and this value should be the negative of the cash price paid for the item, net of any voucher value redeemed on the item. In the case that this value is not supplied, the negative of the original single-quantity item price is assumed. |
| item_quantity | (float) The quantity of an item. If this is not supplied the quantity is assumed to be 1. |
| original_retailer_basket_code | (string, mandatory) The retailer_basket_code (transaction ID or number) of the basket in which the item was originally purchased. Note that if there were also supplementary_basket_code values POSTed with the original basket then it is possible to use those instead. If both fields are supplied then the original_retailer_basket_code takes precedence. |
| original_retailer_item_code | (string, optional) The retailer_item_code of the item in the basket in which the item was originally purchased. This can be used to return specific items in a case where multiple items were purchased with the same identifier (e.g. the same barcode) and a retailer_item_code was specified in the original basket. |
| original_supplementary_basket_code | (string, optional) One of the supplementary_basket_code values of the basket in which the item was originally purchased. To be used if no original_retailer_basket_code value is supplied. |
Fields in The Response For a Return
The following fields are notable in the basket level of the response after posting a return.
| Field | Subfield 1 | Subfield 2 | Description |
|---|---|---|---|
| basket_vouchers_applied | Any basket vouchers which are being redeemed in this transaction. Note that, in the case that a retailer is configured to automatically and immediately redeem vouchers which were redeemed in the original purchase transaction, this field may be populated even without voucher details being supplied in the request JSON, and this type of “regenerated” voucher is redeemed before other vouchers supplied in the JSON request. | ||
| return_transactions | An array of return transactions in a basket. Items from different original retailer baskets are separated into individual return transactions. | ||
| basket_id | The Spaaza basket ID of the original purchase transaction. | ||
| returned_items | An array of individual returned items. | ||
| item_id | The original Spaaza item ID of the returned item. | ||
| return_price | The price at which the item is being returned. | ||
| sale_price | The price at which the item is originally sold. | ||
| voucher_distribution_refunds | Any refunds of amounts of vouchers which were redeemed (spent) on the originally-purchased item. | ||
| purchase_progress_distribution_reclaims | Any reclaim of amounts of points or wallet amounts earned on the originally-purchased items. | ||
| regenerated_rewards | An array of rewards, including basket vouchers, which have been automatically generated for immediate redemption on purchased items in the returning basket. For example, if a customer returns an item on which a voucher was partially redeemed, and immediately wishes to redeem the same voucher on the new item, this will appear in this section as a regenerated reward, in addition to appearing in the “basket_vouchers_applied” section of the response. This field also appears in the response to the “get-basket-price” endpoint (see “Requesting an adjusted basket”) although in the response to that endpoint any voucher keys or IDs have not yet been populated. |
Example requests
- see “Get basket adjustments” for more information on making a call to the get-basket-price endpoint
- see “Adding baskets” for more information on calls to the add-basket endpoint and on interpreting response fields
The response part of the sample JSON below illustrates that an item is being returned, and that in the case of this retailer, the returned value of the voucher which was redeemed in the original transaction on the purchase item which is now being returned in this transaction, is immediately being redeemed on the new purchase item.
get-basket-price
The JSON below illustrates a POST request to the get-basket-price endpoint of an item being returned in the same basket as a sale item with the same barcode - this is effectively an “exchange” transaction.
{
"entity": {
"chain_id": 1743
},
"user": {
"member_programme": "Spaaza",
"member_number": "303484"
},
"basket": {
"basket_platform_type": "in_store",
"retailer_basket_code": "20190127_test_00000003",
"basket_total_price": 2.08,
"basket_timestamp_iso8601": "",
"basket_timezone_name": "Europe/Amsterdam",
"shipping_charge": 0,
"payment_methods": [],
"basket_currency": {
"currency_id": 0,
"currency_code": "EUR"
},
"basket_tax": [],
"basket_items": [
{
"retailer_item_code": "line_3",
"item_barcode": "8718299601410",
"item_quantity": 1.425,
"item_price": -47.91,
"return_item": true,
"original_retailer_basket_code": "20190127_test_00000002"
},
{
"item_barcode": "8718299601410",
"retailer_item_code": "line_2",
"item_quantity": 1,
"item_price": 49.99
}
]
}
}
The JSON below illustrates the response for a POST request to the get-basket-price endpoint of an item being returned in the same basket as a sale item with the same barcode - this is effectively an “exchange” transaction.
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"user": {
"member_programme": "Spaaza",
"member_number": "303484"
},
"basket": {
"chain_id": 1743,
"basket_platform_type": "in_store",
"currency_id": 2,
"basket_total_price": 2.08,
"retailer_basket_code": "20190127_test_00000003",
"basket_items": [
{
"spaaza_product_id": null,
"product_name": null,
"retailer_product_code": null,
"item_quantity": 1,
"retailer_item_code": "line_2",
"item_is_promotional": false,
"item_price": 49.99,
"item_original_price": 49.99,
"item_subtotal": 49.99,
"is_identified": false,
"excluded_from_spaaza": false,
"basket_voucher_distribution": [
{
"voucher_campaign_id": 192,
"voucher_campaign_title": "Welcome gift",
"voucher_key": null,
"voucher_id": null,
"voucher_type": "basket",
"voucher_distribution_amount": 2.08
}
],
"item_barcode": "8718299601410"
}
],
"basket_vouchers_applied": [],
"return_transactions": [
{
"basket_id": 362722,
"returned_items": [
{
"item_id": 535952,
"return_price": -47.91,
"quantity": 1,
"owner_code": "line_2",
"sale_price": 49.99,
"voucher_distribution_refunds": [
{
"voucher_key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b",
"voucher_id": 2630,
"campaign_id": 192,
"amount": 2.08
}
],
"purchase_progress_distribution_reclaims": [
{
"campaign_id": 152,
"amount": -48
}
]
}
]
}
],
"payment_methods": [],
"supplementary_basket_codes": null,
"regenerated_rewards": [
{
"voucher_key": null,
"voucher_id": null,
"voucher_status": "claimed",
"voucher_locked": false,
"campaign_id": 192,
"campaign_type": "signup",
"campaign_title": "Welcome gift",
"voucher_expiry_datetime_utc": "2019-07-09 07:25:10",
"voucher_expiry_seconds_remaining": 14033163,
"voucher_redeemed_datetime": null,
"generating_return_transaction": {
"return_transaction_id": null,
"returning_basket_id": null,
"returning_basket_retailer_basket_code": "20190127_test_00000003"
},
"parent_voucher": {
"voucher_id": 2630,
"voucher_key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b",
"voucher_redeemed_datetime": "2019-01-27T21:13:37+00:00",
"voucher_amount_original": 5,
"voucher_amount_redeemed": 5,
"voucher_amount": 5,
"redeeming_basket": {
"basket_id": 362722,
"retailer_basket_code": "20190127_test_00000002"
}
},
"voucher_currency_id": 2,
"voucher_currency_symbol": "€",
"voucher_amount_original": 2.08,
"voucher_amount_redeemed": 2.08,
"voucher_amount": 2.08,
"voucher_text": "New ACME Club Member",
"redeeming_basket": []
}
],
"employee": {
"employee_code": null,
"employee_name": null
},
"purchase_progress": null,
"basket_total_price_adjusted": 0
},
"result_type": "get-basket-price"
}
}
Sample JSON
- see “Adding a completed basket” for more information on making a call to the add-basket endpoint
The JSON below illustrates an item being returned in the same basket as a sale item, with annotation of fields/parameters not explained elsewhere on this page:
{
"entity": {
"chain_id": 1743
},
"user": {
"member_programme": "Spaaza",
"member_number": "303484"
},
"basket": {
"basket_platform_type": "in_store",
"retailer_basket_code": "20190127_test_00000003",
"basket_total_price": 0,
"basket_timestamp_iso8601": "",
"basket_timezone_name": "Europe/Amsterdam",
"apply_refunds": true,
"shipping_charge": 0,
"payment_methods": [],
"basket_currency": {
"currency_id": 0,
"currency_code": "EUR"
},
"basket_tax": [],
"basket_items": [
{
"retailer_item_code": "line_3",
"item_barcode": "8718299601410",
"item_quantity": 1,
"item_price": -47.91,
"return_item": true,
"original_retailer_basket_code": "20190127_test_00000002"
},
{
"item_barcode": "8718299601410",
"retailer_item_code": "line_2",
"item_quantity": 1,
"item_price": 49.99
}
]
}
}
The JSON below illustrates the response to return items posted.
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket": {
"id": 362723,
"chain_id": 1756,
"basket_platform_type": "in_store",
"currency_id": 2,
"basket_total_price": 0,
"shipping_charge": 0,
"retailer_basket_code": "20190127_test_00000003",
"basket_items": [
{
"spaaza_product_id": null,
"product_name": null,
"retailer_product_code": null,
"item_quantity": 1,
"retailer_item_code": "line_2",
"item_is_promotional": false,
"item_price": 49.99,
"item_original_price": 49.99,
"item_subtotal": 49.99,
"is_identified": false,
"excluded_from_spaaza": false,
"basket_voucher_distribution": [
{
"voucher_campaign_id": 192,
"voucher_campaign_title": "Welkomstcadeau",
"voucher_key": "b3cbf91d1f95e95d7412ec47aaafb9708c762ba7d94c71b5c454c39cdca64d93",
"voucher_id": 80252,
"voucher_type": "basket",
"voucher_distribution_amount": 2.08
}
],
"purchase_progress_distribution": [
{
"purchase_progress_campaign_id": 152,
"purchase_progress_campaign_title": "Didi's",
"purchase_progress_campaign_type": "points_wallet",
"purchase_progress_distribution_amount": 47,
"contributing_campaign": {
"campaign_id": 153,
"campaign_title": "Didi's",
"campaign_type": "cashback"
}
}
],
"item_barcode": "8718299601410"
}
],
"basket_vouchers_applied": [
{
"voucher_key": "b3cbf91d1f95e95d7412ec47aaafb9708c762ba7d94c71b5c454c39cdca64d93",
"voucher_id": 80252,
"voucher_status": "redeemed",
"voucher_locked": false,
"campaign_id": 192,
"campaign_type": "signup",
"campaign_title": "Welkomstcadeau",
"voucher_expiry_datetime_utc": "2019-07-09 07:25:10",
"voucher_expiry_seconds_remaining": 14032990,
"voucher_redeemed_datetime": "2019-01-27T21:22:00+00:00",
"generating_return_transaction": {
"return_transaction_id": 1171,
"returning_basket_id": 362723,
"returning_basket_retailer_basket_code": "20190127_test_00000003"
},
"parent_voucher": {
"voucher_id": 2630,
"voucher_key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b",
"voucher_redeemed_datetime": "2019-01-27T21:13:37+00:00",
"voucher_amount_original": 5,
"voucher_amount_redeemed": 5,
"voucher_amount": 5,
"redeeming_basket": {
"basket_id": 362722,
"retailer_basket_code": "20190127_test_00000002"
}
},
"voucher_currency_id": 2,
"voucher_currency_symbol": "€",
"voucher_amount_original": 2.08,
"voucher_amount_redeemed": 2.08,
"voucher_amount": 2.08,
"voucher_text": "Nieuwe Didi Club Member",
"redeeming_basket": {
"basket_id": 362723,
"retailer_basket_code": "20190127_test_00000003"
}
}
],
"return_transactions": [
{
"id": 1171,
"basket_id": 362722,
"returned_items": [
{
"id": 1221,
"return_transaction_id": 1171,
"item_id": 535952,
"return_price": -47.91,
"quantity": 1,
"owner_code": "line_2",
"sale_price": 49.99,
"voucher_distribution_refunds": [
{
"voucher_key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b",
"voucher_id": 2630,
"campaign_id": 192,
"amount": 2.08
}
],
"purchase_progress_distribution_reclaims": [
{
"campaign_id": 152,
"amount": -48
}
]
}
],
"returning_basket_id": 362723
}
],
"payment_methods": [],
"supplementary_basket_codes": null,
"regenerated_rewards": [
{
"voucher_key": "b3cbf91d1f95e95d7412ec47aaafb9708c762ba7d94c71b5c454c39cdca64d93",
"voucher_id": 80252,
"voucher_status": "redeemed",
"voucher_locked": false,
"campaign_id": 192,
"campaign_type": "signup",
"campaign_title": "Welkomstcadeau",
"voucher_expiry_datetime_utc": "2019-07-09 07:25:10",
"voucher_expiry_seconds_remaining": 14032990,
"voucher_redeemed_datetime": "2019-01-27T21:22:00+00:00",
"generating_return_transaction": {
"return_transaction_id": 1171,
"returning_basket_id": 362723,
"returning_basket_retailer_basket_code": "20190127_test_00000003"
},
"parent_voucher": {
"voucher_id": 2630,
"voucher_key": "0886407851fc56c6211f01abe1b4eab1fb1b48640efb73b1169c1d7a50e9467b",
"voucher_redeemed_datetime": "2019-01-27T21:13:37+00:00",
"voucher_amount_original": 5,
"voucher_amount_redeemed": 5,
"voucher_amount": 5,
"redeeming_basket": {
"basket_id": 362722,
"retailer_basket_code": "20190127_test_00000002"
}
},
"voucher_currency_id": 2,
"voucher_currency_symbol": "€",
"voucher_amount_original": 2.08,
"voucher_amount_redeemed": 2.08,
"voucher_amount": 2.08,
"voucher_text": "Nieuwe Didi Club Member",
"redeeming_basket": {
"basket_id": 362723,
"retailer_basket_code": "20190127_test_00000003"
}
}
],
"employee": {
"employee_code": null,
"employee_name": null
},
"purchase_progress": [
{
"purchase_progress_campaign_id": 152,
"purchase_progress_campaign_title": "Didi's",
"purchase_progress_campaign_type": "points_wallet",
"purchase_progress_amount": 47,
"contributing_campaign": {
"campaign_id": 153,
"campaign_title": "Didi's",
"campaign_type": "cashback"
}
},
{
"purchase_progress_campaign_id": 152,
"purchase_progress_campaign_title": "Didi's",
"purchase_progress_campaign_type": "points_wallet",
"purchase_progress_amount": -48,
"contributing_campaign": null,
"return_transaction_id": 1171,
"returned_item_id": 1221
}
]
},
"user": {
"member_programme": "Spaaza",
"member_number": "303484",
"spaaza_user_id": 3354863
},
"result_type": "add-basket"
}
}