Implementing third party promotional discounts in a Spaaza Basket
Overview
The add-basket endpoint of the Spaaza API allows for the application of third-party promotional discounts. This functionality is achieved by setting promotional_override to true for each basket_item in the request, facilitating custom discount calculations based on the provided item prices and quantities.
Below is an example of how to utilise the promotional_override feature, the following structure should be used for the API request:
{
"item_barcode": "almonds",
"item_quantity": 4,
"promotional_override": true,
"item_original_price": 1.99,
"item_price": 1.69,
"override_campaign_id": 123,
"override_campaign_owner_code": "owner_code_123"
}
Key Points
- Promotional Override: By setting
promotional_overridetotruefor each applicablebasket_itemin thebasket_itemsarray, the API applies a custom discount calculation. - Discount Calculation: The discount is calculated as the sum of the difference between
item_priceanditem_original_price, multiplied byitem_quantity. - Campaign Override:
- The
override_campaign_idandoverride_campaign_owner_codeare used to specify the Basket Campaign to which the promotion will apply. - In the absence of
override_campaign_idoroverride_campaign_owner_code, the promotion defaults to the Loyalty Campaign of the Chain.
- The
Example Without Campaign Identifiers
The following request demonstrates how a discount will be calculated and applied to the Loyalty Campaign of the chain when no campaign identifiers are provided:
{
"basket": {
"retailer_basket_code": "TESTBASKET1001",
"basket_items": [
{
"item_barcode": "almonds",
"item_quantity": 4,
"promotional_override": true,
"item_original_price": 1.99,
"item_price": 1.69
},
{
"item_barcode": "cashews",
"item_quantity": 2,
"promotional_override": true,
"item_original_price": 1.89,
"item_price": 1.69
},
{
"item_barcode": "peanuts",
"item_quantity": 1,
"promotional_override": true,
"item_original_price": 1.79,
"item_price": 1.69
},
{
"item_barcode": "hazelnuts",
"item_quantity": 3,
"promotional_override": true,
"item_original_price": 1.99,
"item_price": 1.69
}
],
"basket_total_price": 16.9,
"basket_platform_type": "in_store",
"basket_currency": {
"currency_code": "EUR"
}
},
"entity": {
"entity_type": "chain",
"entity_id": 2,
"branch_business_owner_code": "271"
},
"user": {
"member_number": "2000001"
}
}
Example response of the previous request
The response below illustrates the application of a €2.60 discount. This discount is calculated as the aggregate of the differences between item_price and item_original_price, each multiplied by their respective item_quantity. The value of the voucher is then proportionately distributed across each item in the basket.
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket": {
"basket_country_code": null,
"basket_items": [
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 4,
"voucher_campaign_title": "Supermarket Loyalty Programme",
"voucher_campaign_title_localised": "Supermarket Loyalty Programme",
"voucher_distribution_amount": 1.2,
"voucher_id": 1,
"voucher_key": "498cafac498a991706a6b62ae2e0a294f04d0362ae55f5d93b720cd55d84a8f2",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "almonds",
"item_is_promotional": false,
"item_original_price": 1.99,
"item_price": 1.69,
"item_quantity": 4,
"item_quantity_unit": "item",
"item_subtotal": 6.76
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 4,
"voucher_campaign_title": "Supermarket Loyalty Programme",
"voucher_campaign_title_localised": "Supermarket Loyalty Programme",
"voucher_distribution_amount": 0.4,
"voucher_id": 1,
"voucher_key": "498cafac498a991706a6b62ae2e0a294f04d0362ae55f5d93b720cd55d84a8f2",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "cashews",
"item_is_promotional": false,
"item_original_price": 1.89,
"item_price": 1.69,
"item_quantity": 2,
"item_quantity_unit": "item",
"item_subtotal": 3.38
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 4,
"voucher_campaign_title": "Supermarket Loyalty Programme",
"voucher_campaign_title_localised": "Supermarket Loyalty Programme",
"voucher_distribution_amount": 0.1,
"voucher_id": 1,
"voucher_key": "498cafac498a991706a6b62ae2e0a294f04d0362ae55f5d93b720cd55d84a8f2",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "peanuts",
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.69,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 1.69
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 4,
"voucher_campaign_title": "Supermarket Loyalty Programme",
"voucher_campaign_title_localised": "Supermarket Loyalty Programme",
"voucher_distribution_amount": 0.9,
"voucher_id": 1,
"voucher_key": "498cafac498a991706a6b62ae2e0a294f04d0362ae55f5d93b720cd55d84a8f2",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "hazelnuts",
"item_is_promotional": false,
"item_original_price": 1.99,
"item_price": 1.69,
"item_quantity": 3,
"item_quantity_unit": "item",
"item_subtotal": 5.07
}
],
"basket_platform_type": "in_store",
"basket_tax": [],
"basket_timestamp_iso8601": "2023-12-11T13:19:03+00:00",
"basket_timezone_name": "UTC",
"basket_total_price": 16.9,
"basket_vouchers_applied": [
{
"campaign_id": 4,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_title": "Supermarket Loyalty Programme",
"campaign_title_localised": "Supermarket Loyalty Programme",
"campaign_type": "loyalty",
"campaign_voucher_text_localised": "Your Supermarket bonus voucher",
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": {
"basket_id": 1,
"branch_business_id": 6,
"branch_owner_code": "271",
"platform_type": "in_store",
"retailer_basket_code": "TESTBASKET1001",
"total_value": 16.9
},
"voucher_amount": 2.6,
"voucher_amount_original": 2.6,
"voucher_amount_redeemed": 2.6,
"voucher_created_datetime": "2023-12-11T13:19:04+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2023-12-11T14:04:04+00:00",
"voucher_expiry_seconds_remaining": 2700,
"voucher_honour_code": null,
"voucher_id": 1,
"voucher_image_url": null,
"voucher_key": "498cafac498a991706a6b62ae2e0a294f04d0362ae55f5d93b720cd55d84a8f2",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": "2023-12-11T13:19:04+00:00",
"voucher_status": "redeemed",
"voucher_text": "Supermarket Loyalty Programme",
"voucher_title": null,
"voucher_type": "basket"
}
],
"chain_id": 2,
"currency_id": 2,
"employee": {
"employee_code": null,
"employee_name": null
},
"honour_vouchers_applied": [],
"id": 1,
"payment_methods": [],
"purchase_progress": [],
"regenerated_rewards": [],
"retailer_basket_code": "TESTBASKET1001",
"return_transactions": [],
"supplementary_basket_codes": null
},
"user": {
"authentication_point_identifier": null,
"member_number": "2000001",
"member_programme": "spaaza",
"spaaza_user_id": 7
},
"result_type": "add-basket"
}
}
An example request with override_campaign_owner_code and override_campaign_id
This example demonstrates how to structure a request incorporating both override_campaign_owner_code and override_campaign_id. These fields allow you to specify which Basket campaign the discount should be applied to for each item.
{
"basket": {
"retailer_basket_code": "TESTBASKET1002",
"basket_items": [
{
"item_barcode": "almonds",
"item_quantity": 1,
"promotional_override": true,
"override_campaign_owner_code": "owner_code_002",
"item_original_price": 1.99,
"item_price": 1.69
},
{
"item_barcode": "blueberrys",
"item_quantity": 2,
"promotional_override": true,
"override_campaign_id": 18,
"item_original_price": 1.89,
"item_price": 1.69
},
{
"item_barcode": "peanuts",
"item_quantity": 2,
"promotional_override": true,
"override_campaign_owner_code": "owner_code_002",
"item_original_price": 1.79,
"item_price": 1.69
},
{
"item_barcode": "cranberrys",
"item_quantity": 1,
"promotional_override": true,
"override_campaign_id": 18,
"item_original_price": 1.99,
"item_price": 1.69
}
],
"basket_total_price": 10.139999999999999,
"basket_platform_type": "in_store",
"basket_currency": {
"currency_code": "EUR"
}
},
"entity": {
"entity_type": "chain",
"entity_id": 2,
"branch_business_owner_code": "271"
},
"user": {
"member_number": "2000001"
}
}
Example Response for the Request with override_campaign_owner_code and override_campaign_id
The response below demonstrates how a €1.20 discount is applied. This discount results from the cumulative differences between item_price and item_original_price, each multiplied by their respective item_quantity. The value of the voucher is then equitably distributed across each item in the basket.
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket": {
"basket_country_code": null,
"basket_items": [
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 18,
"voucher_campaign_title": "25% off all products",
"voucher_campaign_title_localised": "25% off all products",
"voucher_distribution_amount": 0.3,
"voucher_id": 1,
"voucher_key": "c6121fbcf260341bcc2235d6bd37ef14a39570d05dadc61518792ae092cee3aa",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "almonds",
"item_is_promotional": false,
"item_original_price": 1.99,
"item_price": 1.69,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 1.69
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 18,
"voucher_campaign_title": "25% off all products",
"voucher_campaign_title_localised": "25% off all products",
"voucher_distribution_amount": 0.4,
"voucher_id": 1,
"voucher_key": "c6121fbcf260341bcc2235d6bd37ef14a39570d05dadc61518792ae092cee3aa",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "blueberrys",
"item_is_promotional": false,
"item_original_price": 1.89,
"item_price": 1.69,
"item_quantity": 2,
"item_quantity_unit": "item",
"item_subtotal": 3.38
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 18,
"voucher_campaign_title": "25% off all products",
"voucher_campaign_title_localised": "25% off all products",
"voucher_distribution_amount": 0.2,
"voucher_id": 1,
"voucher_key": "c6121fbcf260341bcc2235d6bd37ef14a39570d05dadc61518792ae092cee3aa",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "peanuts",
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.69,
"item_quantity": 2,
"item_quantity_unit": "item",
"item_subtotal": 3.38
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 18,
"voucher_campaign_title": "25% off all products",
"voucher_campaign_title_localised": "25% off all products",
"voucher_distribution_amount": 0.3,
"voucher_id": 1,
"voucher_key": "c6121fbcf260341bcc2235d6bd37ef14a39570d05dadc61518792ae092cee3aa",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "cranberrys",
"item_is_promotional": false,
"item_original_price": 1.99,
"item_price": 1.69,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 1.69
}
],
"basket_platform_type": "in_store",
"basket_tax": [],
"basket_timestamp_iso8601": "2023-12-11T13:29:32+00:00",
"basket_timezone_name": "UTC",
"basket_total_price": 10.14,
"basket_vouchers_applied": [
{
"campaign_id": 18,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_title": "25% off all products",
"campaign_type": "basket",
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": {
"basket_id": 1,
"branch_business_id": 6,
"branch_owner_code": "271",
"platform_type": "in_store",
"retailer_basket_code": "TESTBASKET1002",
"total_value": 10.14
},
"voucher_amount": 1.2,
"voucher_amount_original": 1.2,
"voucher_amount_redeemed": 1.2,
"voucher_created_datetime": "2023-12-11T13:29:32+00:00",
"voucher_currency_code": "EUR",
"voucher_currency_id": 2,
"voucher_currency_symbol": "\u20ac",
"voucher_description": null,
"voucher_discount_ratio": 0,
"voucher_expiry_datetime_utc": "2023-12-11T14:14:32+00:00",
"voucher_expiry_seconds_remaining": 2700,
"voucher_honour_code": null,
"voucher_id": 1,
"voucher_image_url": null,
"voucher_key": "c6121fbcf260341bcc2235d6bd37ef14a39570d05dadc61518792ae092cee3aa",
"voucher_locked": false,
"voucher_notes": null,
"voucher_redeemed_datetime": "2023-12-11T13:29:32+00:00",
"voucher_status": "redeemed",
"voucher_text": "25% off all products",
"voucher_title": null,
"voucher_type": "basket"
}
],
"chain_id": 2,
"currency_id": 2,
"employee": {
"employee_code": null,
"employee_name": null
},
"honour_vouchers_applied": [],
"id": 1,
"payment_methods": [],
"purchase_progress": [],
"regenerated_rewards": [],
"retailer_basket_code": "TESTBASKET1002",
"return_transactions": [],
"supplementary_basket_codes": null
},
"user": {
"authentication_point_identifier": null,
"member_number": "2000001",
"member_programme": "spaaza",
"spaaza_user_id": 7
},
"result_type": "add-basket"
}
}