Link Search Menu Expand Document

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-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.
active_date_from (datetime, mandatory) Date/time (in UTC) from which the campaign is active. If both are populated, the active_date_from field must not be after the active_date_until field.
active_date_until (datetime, mandatory) Date/time (in UTC) until which point in time the campaign is active. If both are populated, the active_date_until field must not be before the active_date_from field.
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.
active_date_from (datetime, mandatory) Date/time (in UTC) from which the campaign is active. If both are populated, the active_date_from field must not be after the active_date_until field.
active_date_until (datetime, mandatory) Date/time (in UTC) until which point in time the campaign is active. If both are populated, the active_date_until field must not be before the active_date_from field.
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.
active_date_from (datetime, mandatory) Date/time (in UTC) from which the campaign is active. If both are populated, the active_date_from field must not be after the active_date_until field.
active_date_until (datetime, mandatory) Date/time (in UTC) until which point in time the campaign is active. If both are populated, the active_date_until field must not be before the active_date_from field.
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.