Competition Campaigns
Contents
Overview
Competition campaigns are campaigns which use a randomised algorith to decide whether an end-user wins the reward defined in the campaign. The reward can be a free item, free basket or a monetary voucher to be redeemed in a future transaction. Examples of future transactions can include a future purchase or an immediate redemption at a service kiosk in the case of a physical store.
Types of competition campaigns
The following types of competition campaigns are available in Spaaza:
- Free Item (
free_item)- The customer might win one or more items if they buy one or more items
- Free Basket (
free_basket)- The customer might get their current basket for free if they buy one or more items
- Grand Prize (
grand_prize)- The customer might be win a reward (BasketVoucher) in a
get-basket-pricerequest that they can use in a future transaction.
- The customer might be win a reward (BasketVoucher) in a
Setting up the various competition types
Free item competition (type = free_item)
Creating a free_item competition the following parameters may or must be passed:
| Parameter | Description |
|---|---|
type | (string, mandatory, 1 possible value = competition) The type of campaign to create. |
product_promotion_type | (string, mandatory, 1 possible value = free_item) The type of competition to create. |
budget | (float, mandatory) The total budget for the campaign in the currency of the campaign. This either applies for the entire length of the campaign between the active_date_from and active_date_until values, or, if the budget_period_quantity and budget_period_quantity_unit values are set, to a fixed budgetary period. |
budget_period_quantity | (integer, optional, if passed the budget_period_quantity_unit parameter must also be passed) The unit period of time for the campaign budget. The only possible non-null value is 1. |
budget_period_quantity_unit | (string, optional, if passed the budget_period_quantity parameter must also be passed) The unit of time for the budget period. The only possible non-null value is day. |
Note that other parameters are not required but may be important. These are found elsewhere in the documentation and include the following (amongst others):
assigned_barcodes_earnmax_spend_quantitymin_earn_quantityrecipient_message_text
There follow examples of JSON for creating and retrieving a free_item competition campaign, and some advisory notes:
example json to create the campaign
{
"chain_id": 1743,
"type": "competition",
"product_promotion_type": "free_item",
"active": true,
"currency_id": 2,
"spend_on_promotional_items": true,
"active_date_from": "2024-05-21 20:51:25",
"active_date_until": "2024-06-18 20:51:25",
"budget": 100,
"budget_period_quantity": 1,
"budget_period_quantity_unit": "day",
"title": "Win a free can of Coca Cola",
"assigned_barcodes_earn": [
"coca_cola"
],
"max_spend_quantity": 1,
"min_earn_quantity": 2
}
example get-basket-price request JSON:
{
"basket": {
"retailer_basket_code": "TESTBASKET1001",
"basket_items": [
{
"item_barcode": "coca_cola",
"item_quantity": 1,
"item_price": 1.79
},
{
"item_barcode": "coca_cola",
"item_quantity": 2,
"item_price": 1.79
},
{
"item_barcode": "apple",
"item_quantity": 1,
"item_price": 0.99
}
],
"basket_total_price": 6.36,
"basket_platform_type": "in_store",
"basket_currency": {
"currency_code": "EUR"
}
},
"entity": {
"entity_type": "chain",
"entity_id": 2
},
"user": {
"member_number": "7"
}
}
example get-basket-price response JSON:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket": {
"basket_country_code": null,
"basket_items": [
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 3,
"voucher_campaign_title": "Win a free can of Coca Cola",
"voucher_campaign_title_localised": "Win a free can of Coca Cola",
"voucher_distribution_amount": 1.79,
"voucher_id": 1,
"voucher_key": "8f92ce6ed9d4ec702eb3e04f895b8ddcf1a60a543d873aa79ee0fcbcd3eec35d",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "coca_cola",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.79,
"item_price_adjusted": 0,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 1.79,
"item_subtotal_adjusted": 0
},
{
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "coca_cola",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.79,
"item_price_adjusted": 1.79,
"item_quantity": 2,
"item_quantity_unit": "item",
"item_subtotal": 3.58,
"item_subtotal_adjusted": 3.58
},
{
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "apple",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 0.99,
"item_price": 0.99,
"item_price_adjusted": 0.99,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 0.99,
"item_subtotal_adjusted": 0.99
}
],
"basket_platform_type": "in_store",
"basket_tax": [],
"basket_timestamp_iso8601": "2024-06-04T20:51:26+00:00",
"basket_timezone_name": "UTC",
"basket_total_price": 6.36,
"basket_total_price_adjusted": 4.57,
"basket_vouchers_applied": [
{
"campaign_id": 3,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": "free_item",
"campaign_title": "Win a free can of Coca Cola",
"campaign_type": "competition",
"competition_campaign_voucher_identifier": null,
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"voucher_amount": 1.79,
"voucher_amount_original": 1.79,
"voucher_amount_redeemed": 1.79,
"voucher_basket_owner_code_exclusive": "TESTBASKET1001",
"voucher_created_datetime": "2024-06-04T20:51:26+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": "2025-06-04T20:51:26+00:00",
"voucher_expiry_seconds_remaining": 31536000,
"voucher_honour_code": null,
"voucher_id": 1,
"voucher_image_url": null,
"voucher_key": "8f92ce6ed9d4ec702eb3e04f895b8ddcf1a60a543d873aa79ee0fcbcd3eec35d",
"voucher_locked": true,
"voucher_locked_until": "2024-06-04 20:56:26",
"voucher_locking_code": null,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": "Win a free can of Coca Cola",
"voucher_third_party_id": 5425331364,
"voucher_title": null,
"voucher_type": "basket"
}
],
"chain_id": 1743,
"currency_id": 2,
"employee": {
"employee_code": null,
"employee_name": null
},
"honour_vouchers_applied": [],
"payment_methods": [],
"purchase_progress": [],
"regenerated_rewards": [],
"retailer_basket_code": "TESTBASKET1001",
"return_transactions": [],
"supplementary_basket_codes": null,
"vouchers_created": []
},
"calculated_basket_discounts": [
{
"achieved": true,
"campaign_id": 3,
"discount_value": 1.79,
"title": "competition requirement match result",
"type": "competition"
}
],
"user": {
"member_number": "7"
},
"result_type": "get-basket-price"
}
}
Notes
- Due to the campaign configuration the customer would have to buy at least 2 Coca-Cola items to be considered for the reward.
- The customer bought 3 cokes so they qualify for the reward.
- The customer “won” a free bottle of Coca-Cola and the value of the voucher generated is distributed over the first item.
Free basket competition (type = free_basket)
Creating a free_basket competition the following parameters may or must be passed:
| Parameter | Description |
|---|---|
type | (string, mandatory, 1 possible value = competition) The type of campaign to create. |
product_promotion_type | (string, mandatory, 1 possible value = free_basket) The type of competition to create. |
budget | (float, mandatory) The total budget for the campaign in the currency of the campaign. This either applies for the entire length of the campaign between the active_date_from and active_date_until values, or, if the budget_period_quantity and budget_period_quantity_unit values are set, to a fixed budgetary period. |
budget_period_quantity | (integer, optional, if passed the budget_period_quantity_unit parameter must also be passed) The unit period of time for the campaign budget. The only possible non-null value is 1. |
budget_period_quantity_unit | (string, optional, if passed the budget_period_quantity parameter must also be passed) The unit of time for the budget period. The only possible non-null value is day. |
Note that other parameters are not required but may be important. These are found elsewhere in the documentation and include the following amongst others:
assigned_barcodes_earnmin_earn_quantityrecipient_message_text
There follow examples of JSON for creating and retrieving a free_item competition campaign, and some advisory notes:
example json to create the campaign:
{
"chain_id": 1743,
"type": "competition",
"product_promotion_type": "free_basket",
"active": true,
"currency_id": 2,
"spend_on_promotional_items": true,
"active_date_from": "2024-05-21 21:02:19",
"active_date_until": "2024-06-18 21:02:19",
"budget": 100,
"budget_period_quantity": 1,
"budget_period_quantity_unit": "day",
"title": "Potentially have a free basket when you buy a coca cola",
"assigned_barcodes_earn": [
"coca_cola"
],
"min_earn_quantity": 1
}
example get-basket-price JSON:
{
"basket": {
"retailer_basket_code": "TESTBASKET1001",
"basket_items": [
{
"item_barcode": "coca_cola",
"item_quantity": 1,
"item_price": 1.79
},
{
"item_barcode": "coca_cola",
"item_quantity": 2,
"item_price": 1.79
},
{
"item_barcode": "sandwich",
"item_quantity": 1,
"item_price": 4.99
}
],
"basket_total_price": 10.36,
"basket_platform_type": "in_store",
"basket_currency": {
"currency_code": "EUR"
}
},
"entity": {
"entity_type": "chain",
"entity_id": 2
},
"user": {
"member_number": "7"
}
}
example get-basket-price response JSON:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket": {
"basket_country_code": null,
"basket_items": [
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 3,
"voucher_campaign_title": "Potentially have a free basket when you buy a coca cola",
"voucher_campaign_title_localised": "Potentially have a free basket when you buy a coca cola",
"voucher_distribution_amount": 1.79,
"voucher_id": 1,
"voucher_key": "7a47f66e3067888f6dfefea07553b10d09bd8c2c1a2ab3d1111ce83f7ab34059",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "coca_cola",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.79,
"item_price_adjusted": 0,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 1.79,
"item_subtotal_adjusted": 0
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 3,
"voucher_campaign_title": "Potentially have a free basket when you buy a coca cola",
"voucher_campaign_title_localised": "Potentially have a free basket when you buy a coca cola",
"voucher_distribution_amount": 3.58,
"voucher_id": 1,
"voucher_key": "7a47f66e3067888f6dfefea07553b10d09bd8c2c1a2ab3d1111ce83f7ab34059",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "coca_cola",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.79,
"item_price_adjusted": 0,
"item_quantity": 2,
"item_quantity_unit": "item",
"item_subtotal": 3.58,
"item_subtotal_adjusted": 0
},
{
"basket_voucher_distribution": [
{
"voucher_campaign_id": 3,
"voucher_campaign_title": "Potentially have a free basket when you buy a coca cola",
"voucher_campaign_title_localised": "Potentially have a free basket when you buy a coca cola",
"voucher_distribution_amount": 4.99,
"voucher_id": 1,
"voucher_key": "7a47f66e3067888f6dfefea07553b10d09bd8c2c1a2ab3d1111ce83f7ab34059",
"voucher_type": "basket"
}
],
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "sandwich",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 4.99,
"item_price": 4.99,
"item_price_adjusted": 0,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 4.99,
"item_subtotal_adjusted": 0
}
],
"basket_platform_type": "in_store",
"basket_tax": [],
"basket_timestamp_iso8601": "2024-06-04T21:02:20+00:00",
"basket_timezone_name": "UTC",
"basket_total_price": 10.36,
"basket_total_price_adjusted": 0,
"basket_vouchers_applied": [
{
"campaign_id": 3,
"campaign_image_dimension_x": null,
"campaign_image_dimension_y": null,
"campaign_image_filename": null,
"campaign_image_link": null,
"campaign_image_url": null,
"campaign_owner_code": null,
"campaign_product_promotion_type": "free_basket",
"campaign_title": "Potentially have a free basket when you buy a coca cola",
"campaign_type": "competition",
"competition_campaign_voucher_identifier": null,
"generating_return_transaction": null,
"parent_voucher": null,
"redeeming_basket": null,
"voucher_amount": 10.36,
"voucher_amount_original": 10.36,
"voucher_amount_redeemed": 10.36,
"voucher_basket_owner_code_exclusive": "TESTBASKET1001",
"voucher_created_datetime": "2024-06-04T21:02:20+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": "2025-06-04T21:02:20+00:00",
"voucher_expiry_seconds_remaining": 31536000,
"voucher_honour_code": null,
"voucher_id": 1,
"voucher_image_url": null,
"voucher_key": "7a47f66e3067888f6dfefea07553b10d09bd8c2c1a2ab3d1111ce83f7ab34059",
"voucher_locked": true,
"voucher_locked_until": "2024-06-04 21:07:20",
"voucher_locking_code": null,
"voucher_notes": null,
"voucher_redeemed_datetime": null,
"voucher_status": "claimed",
"voucher_text": "Potentially have a free basket when you buy a coca cola",
"voucher_third_party_id": 4703241546,
"voucher_title": null,
"voucher_type": "basket"
}
],
"chain_id": 1743,
"currency_id": 2,
"employee": {
"employee_code": null,
"employee_name": null
},
"honour_vouchers_applied": [],
"payment_methods": [],
"purchase_progress": [],
"regenerated_rewards": [],
"retailer_basket_code": "TESTBASKET1001",
"return_transactions": [],
"supplementary_basket_codes": null,
"vouchers_created": []
},
"calculated_basket_discounts": [
{
"achieved": true,
"campaign_id": 3,
"discount_value": 10.36,
"title": "competition requirement match result",
"type": "competition"
}
],
"user": {
"member_number": "7"
},
"result_type": "get-basket-price"
}
}
Notes
- Due to the campaign configuration the customer would have to buy at least 1 Coca-Cola’s to be considered for the reward.
- Since the customer bought 1 coca cola and won the competition they recieved a free basket.
- A 100% discount of 10.36 was calculated and a voucher of this amount was generated and applied to the basket.
- The voucher was distributed over the basket items.
Grand prize competition (type = grand_prize)
Creating a grand_prize competition the following parameters may or must be passed:
| Parameter | Description |
|---|---|
type | (string, mandatory, 1 possible value = competition) The type of campaign to create. |
product_promotion_type | (string, mandatory, 1 possible value = grand_prize) The type of competition to create. |
recipient_reward_amount | (float, mandatory) The reward value a customer will receive from the campaign. |
budget | (float, mandatory) The total budget for the campaign in the currency of the campaign. This either applies for the entire length of the campaign between the active_date_from and active_date_until values, or, if the budget_period_quantity and budget_period_quantity_unit values are set, to a fixed budgetary period. |
budget_period_quantity | (integer, optional, if passed the budget_period_quantity_unit parameter must also be passed) The unit period of time for the campaign budget. The only possible non-null value is 1. |
budget_period_quantity_unit | (string, optional, if passed the budget_period_quantity parameter must also be passed) The unit of time for the budget period. The only possible non-null value is day. |
Note that other parameters are not required but may be important. These are found elsewhere in the documentation and include the following amongst others:
assigned_barcodes_earnmin_earn_quantityrecipient_message_text
example json to create the campaign:
{
"chain_id": 1743,
"type": "competition",
"product_promotion_type": "grand_prize",
"active": "1",
"currency_id": "2",
"spend_on_promotional_items": "1",
"active_date_from": "2024-05-21 21:10:07",
"active_date_until": "2024-06-18 21:10:07",
"budget": "10000",
"budget_period_quantity": "1",
"budget_period_quantity_unit": "day",
"title": "R1,000 prize winner (\"Grand Prize\")",
"assigned_barcodes_earn": [
"coca_cola"
],
"recipient_reward_amount": "1000",
"created_voucher_claimed_by_default": "0"
}
example get-basket-price JSON:
{
"basket": {
"retailer_basket_code": "TESTBASKET1001",
"basket_items": [
{
"item_barcode": "coca_cola",
"item_quantity": 3,
"item_price": 1.79
},
{
"item_barcode": "sandwich",
"item_quantity": 1,
"item_price": 4.99
}
],
"basket_total_price": 10.36,
"basket_platform_type": "in_store",
"basket_currency": {
"currency_code": "EUR"
}
},
"entity": {
"entity_type": "chain",
"entity_id": 2
},
"user": {
"member_number": "7"
}
}
example get-basket-price response JSON:
{
"result": {
"code": 1,
"status": "ok"
},
"results": {
"basket": {
"basket_country_code": null,
"basket_items": [
{
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "coca_cola",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 1.79,
"item_price": 1.79,
"item_price_adjusted": 1.79,
"item_quantity": 3,
"item_quantity_unit": "item",
"item_subtotal": 5.37,
"item_subtotal_adjusted": 5.37
},
{
"excluded_from_spaaza": false,
"is_identified": false,
"item_barcode": "sandwich",
"item_cost_price": null,
"item_is_promotional": false,
"item_original_price": 4.99,
"item_price": 4.99,
"item_price_adjusted": 4.99,
"item_quantity": 1,
"item_quantity_unit": "item",
"item_subtotal": 4.99,
"item_subtotal_adjusted": 4.99
}
],
"basket_platform_type": "in_store",
"basket_tax": [],
"basket_timestamp_iso8601": "2024-06-04T21:10:07+00:00",
"basket_timezone_name": "UTC",
"basket_total_price": 10.36,
"basket_total_price_adjusted": 10.36,
"basket_vouchers_applied": [],
"chain_id": 1743,
"currency_id": 2,
"employee": {
"employee_code": null,
"employee_name": null
},
"honour_vouchers_applied": [],
"payment_methods": [],
"purchase_progress": [],
"regenerated_rewards": [],
"retailer_basket_code": "TESTBASKET1001",
"return_transactions": [],
"supplementary_basket_codes": null,
"vouchers_created": [
{
"amount": 1000,
"campaign_title": "R1,000 prize winner (\"Grand Prize\")",
"campaign_type": "competition",
"competition_campaign_voucher_identifier": "3-7-TESTBASKET1001",
"currency_code": "EUR",
"currency_symbol": "\u20ac",
"discount_ratio": 0,
"expiry_datetime_utc": "2025-06-04T21:10:07+00:00",
"id": 1,
"key": "0e842c336ec93b930f7acbc6d07f61dd3a9c2e7909d81f4d8720a7f7dc2fcecb",
"status": "generated",
"text": "R1,000 prize winner (\"Grand Prize\")",
"third_party_id": 2501762803,
"title": null,
"transaction_message": null,
"type": "basket"
}
]
},
"user": {
"member_number": "7"
},
"result_type": "get-basket-price"
}
}
note about response
- The campaign configuration required the customer to buy a coca cola to be considered for the reward.
- The customer was lucky and won the grand prize of 1000€.
- If the
get-basket-pricerequest is made with an API version greater than1.4.8thevouchers_createdarray will be populated with the voucher that was generated for the customer. - The voucher will not be redeemed by this basket and must be used in a future transaction.