Link Search Menu Expand Document

Types of Competition Campaigns:

  • free_item
    • Customer might win one or more items if they buy one or more items
  • free_basket
    • Customer might get their current basket for free if they buy one or more items
  • grand_prize
    • 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 campaigns

free_item

Creating a free item_item campaign the following parameters must be passed

  • type - The type of campaign to create - competition
  • product_promotion_type - The type of promotion to create - free_item
  • assigned_barcodes_earn - The barcodes assigned to the campaign of items you must buy in order to be considered for the reward.
  • max_spend_quantity - This is the maximum number of items that the free_item voucher can be spent on.
  • min_earn_quantity - This is the minimum number of items that must be bought in order to be considered for the reward.
  • budget - The total budget for the campaign in the currency of the campaign
  • budget_period_quantity - The unit period of time for the campaign budget.
  • budget_period_quantity_unit - The unit (month, year, day) of time for the budget period.

example json to create the campaign: 

{
  "chain_id": 1743,
  "type": "competition",
  "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": "week",
  "title": "Win a free can of Coca Cola",
  "assigned_barcodes_earn": [
    "coca_cola"
  ],
  "max_spend_quantity": 1,
  "min_earn_quantity": 2,
  "product_promotion_type": "free_item"
}

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"
    }
}
note about response
  • Due to the campaign configuration the customer would have to buy at least 2 Coca-Cola’s 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

Creating a free free_basket campaign the following parameters must be passed

  • type - The type of campaign to create - competition
  • product_promotion_type - The type of promotion to create - free_basket
  • assigned_barcodes_earn - The barcodes assigned to the campaign of items you must buy in order to be considered for the reward.
  • min_earn_quantity - This is the minimum number of items that must be bought in order to be considered for the reward.
  • budget - The total budget for the campaign in the currency of the campaign
  • budget_period_quantity - The unit period of time for the campaign budget.
  • budget_period_quantity_unit - The unit (month, year, day) of time for the budget period.

example json to create the campaign: 

{
  "chain_id": 1743,
  "type": "competition",
  "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": "week",
  "title": "Potentially have a free basket when you buy a coca cola",
  "assigned_barcodes_earn": [
    "coca_cola"
  ],
  "min_earn_quantity": 1,
  "product_promotion_type": "free_basket"
}

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"
  }
}
note about response
  • 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.

free_item

Creating a free item_item campaign the following parameters must be passed

  • type - The type of campaign to create - competition
  • product_promotion_type - The type of promotion to create - free_item
  • assigned_barcodes_earn - The barcodes assigned to the campaign of items you must buy in order to be considered for the reward.
  • recipient_reward_amount this is the amount of the reward that the customer will receive.
  • budget - The total budget for the campaign in the currency of the campaign
  • budget_period_quantity - The unit period of time for the campaign budget.
  • budget_period_quantity_unit - The unit (month, year, day) of time for the budget period.

example json to create the campaign: 

{
  "chain_id": 1743,
  "type": "competition",
  "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": "week",
  "title": "R1,000 prize winner (\"Grand Prize\")",
  "assigned_barcodes_earn": [
    "coca_cola"
  ],
  "recipient_reward_amount": "1000",
  "product_promotion_type": "grand_prize",
  "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.