Competition campaigns

Competition Campaigns

Overview
Types of competition campaigns
Setting up the various competition types
Per-store budgets and wins

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-price request that they can use in a future transaction.

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_earn
max_spend_quantity
min_earn_quantity
recipient_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_earn
min_earn_quantity
recipient_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_earn
min_earn_quantity
recipient_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-price request is made with an API version greater than 1.4.8 the vouchers_created array 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.
Note: Vouchers created by grand_prize competitions are automatically restricted to be claimable only in the same branch where they were created. Refer to the claim-vouchers endpoint documentation for details on specifying the branch when claiming vouchers.

Per-store budgets and wins

Competition campaigns support per-store budgets and wins distribution, allowing for more controlled and fair distribution of competition rewards across different stores.

Per-store win limits

Competition campaigns implement store-specific win limits to ensure fair distribution of rewards:

Each store can limited to a configurable maximum number of wins per day
If the configured number of wins is not generated in a store on one calendar day, the remaining number of wins is carried into the next calendar day’s number of wins

Basket eligibility for wins

For a basket to be eligible for a competition win with per-store budgeting:

The basket must be associated with a store
The basket’s value must fall within a specified range (configured per competition) if that property is configured
The transaction must occur within the competition’s active distribution timeframe
The store must not have exceeded its daily win limit

Example implementation

When creating a competition campaign with per-store budgets, use the standard competition campaign parameters as documented in the sections above. The per-store budget functionality is automatically applied to all competition campaigns.

This feature ensures that competition rewards are distributed fairly across all stores, preventing any single store from consuming a disproportionate amount of the campaign budget.