Campaign type and fields

Different campaign types in Spaaza share common fields. There are also fields which are specific to certain campaign types.

General campaign fields

Campaign Styling Parameters

These parameters are used to provide custom styling on a campaign that will be displayed on the Spaaza Embed. Typically, the loyalty campaign will have the base styling, but each individual campaign can also have its own styling which will override the loyalty campaigns styling.

JSON supplied should not be prettified. This example (and those shown below) is shown as an unprettified string:

{"topnav":{"a":{"background-color":"#420","overflow":"hidden"},"a.hover":{"float":"right","color":"#f2f2f2"}}}

Campaign field localisation

It is possible to localise the values for fields in a campaign, such as campaign_title or voucher_text. This is done by using a JSON string containing the localisations required for each field in the campaign which should be localised.

For information on setting localisation strings in campaigns, please see the campaign localisation section of the campaigns documentation.

When a field localisation is requested, either using the Accept-Language header or by the code for a call examining the language of a user account, the most appropriate
language string is selected and returned as a .._localised field in the API response.

JSON supplied should not be prettified. This example is shown as an unprettified string:

{"title":{"en":{"default":"Sample Basket Campaign","en-UK":"Sample Basket Campaign UK","en-US":"Sample Basket Campaign US"},"nl":{"default":"Voorbeeld Basket Campagne","nl-NL":"Voorbeeld Basket Campagne NL","nl-BE":"Voorbeeld Basket Campagne BE"},"fr":{"default":"Exemple Campagne Panier","fr-FR":"Exemple Campagne Panier français","fr-BE":"Exemple Campagne Panier belge"}},"voucher_text":{"nl":{"default":"Voorbeeld voucher","nl-NL":"Voorbeeld voucher NL","nl-BE":"Voorbeeld voucher BE"},"fr":{"default":"Bonne Exemple","fr-FR":"Bonne Exemple français","fr-BE":"Bonne Exemple belge"}}}

A prettified example is shown below:

 {
	"title": {
		"en": {
			"default": "Sample Basket Campaign",
			"en-UK": "Sample Basket Campaign UK",
			"en-US": "Sample Basket Campaign US"
		},
		"nl": {
			"default": "Voorbeeld Basket Campagne",
			"nl-NL": "Voorbeeld Basket Campagne NL",
			"nl-BE": "Voorbeeld Basket Campagne BE"
		},
		"fr": {
			"default": "Exemple Campagne Panier",
			"fr-FR": "Exemple Campagne Panier français",
			"fr-BE": "Exemple Campagne Panier belge"
		}
	},
	"voucher_text": {
		"nl": {
			"default": "Voorbeeld voucher",
			"nl-NL": "Voorbeeld voucher NL",
			"nl-BE": "Voorbeeld voucher BE"
		},
		"fr": {
			"default": "Bonne Exemple",
			"fr-FR": "Bonne Exemple français",
			"fr-BE": "Bonne Exemple belge"
		}
	}  
}

Campaign images

It is possible to upload an individual image, in PNG or JPG format, to be associated with a campaign. Various other parameters can also be associated with the image. Details of how to upload images and the meaning of the other parameters associated with them are found in this section.

When posting images to be added with a new campaign or to an existing campaign, the Content-Type of the call must be set to multipart/form-data in the HTTP headers. For images uploaded, type must be set to file in form data terms.

Contributor campaign fields

The following fields are specific to campaigns which contribute to a wallet or points wallet campaign.

Reward Messages

The recipient_message_text field can be used to provide a message to a customer when they receive a reward from a campaign. Typically, this message gives some context to the reward given, for example: “Thank you for choosing Acme! Exchange this voucher for a €5 discount on your next purchase in our cafeteria.”

In the response to a call to either get-basket-price or add-basket, the recipient_message_text field will be added to the summary of each reward generated by its campaign as follows:

• for vouchers in the transaction_message field of its summary in the vouchers_created array
• for user purchase progression updates in the transaction_message of its summary in the purchase_progress array

If a campaign’s recipient_message_text field is empty, the transaction_message field in the reward summary records will be null.

Reward Message Placeholders

Reward messages can contain dynamic elements called placeholders. These are a select group of tokens you can place inside a reward message that will be replaced with the calculated value when the basket is processed. This can be useful if you wish to include data points from the transaction itself inside the message.

A placeholder is a (compound) word inside a single pair of curly braces with no extra spaces, for example: {firstname}. Placeholders are case-insensitive so the placeholders {firstname}, {FirstName} and {FIRSTNAME} are equivalent.

The transaction_message in the reward summary will have each placeholder replaced with their corresponding value based on the user making the transaction, the campaign being applied and the basket and its contents.

If an unknown placeholder is encountered, it will be replaced with an error message in the transaction_message field as follows: [unknown placeholder: {meaningoflife}]. Ensure you catch any misspelled placeholders during testing by looking out for these errors.

For example, a recipient_message_text of Hello {firstname}, enjoy your free coffee! would result in a transaction_message of Hello Jane, enjoy your free coffee! if the customer’s first name was “Jane”.

The following list contains all placeholders supported in reward messages and the API version from which the placeholder is first supported. This list will be updated as new placeholders are added.

Fields specific to type: basket

Basket campaigns are campaigns which apply to the entire contents of a shopper’s basket rather than to individual product. For example, a retailer may assign a group of products to a basket campaign and then apply an “accumulator” rule to the products, meaning that if the shopper buys multiple products in the group a different discount is applied to all those products present in the basket.

For example, the retailer may offer a promotion where purchasing 1 products in the group gives the shopper a 10% discount, but if they purchase 3 or more products in the group a 25% discount is applied.

Basket campaigns are applied as a basket voucher which is used as a discount on a specific basket. The value of the basket voucher is calculated by iterating through the individual items in the basket.

It is possible to configure multiple basket campaigns in parallel, in which case the highest possible applicable discount is granted to the customer.

It is also possible to configure a basket campaign to exclude any campaign assignment matches, in which case all basket items which do not match the campaign assignments will be given the applicable discount.

Product Promotion Types and Details

The different product promotion types are described below.

Fixed Monetary Discount (type = fixed_monetary_discount)

A basket campaign with product promotion type fixed_monetary_discount will apply a fixed monetary discount to every item in the basket which matches the configured campaign assignments.

In order to configure a fixed_monetary_discount campaign the following fields must be set:

• recipient_reward_amount - this indicates the fixed monetary discount a customer will receive for each item matching the campaign assignments for this particular promotion.

Free Product (type = free_product)

A basket campaign with product promotion type free_product will apply sufficient discount so that the cheapest item in a group of items matching configured campaign assignments is free.

This product promotion type can be used to implement “2 for 1” or “3 for 2” type promotions such as “buy 3 bags of snacks and the cheapest one is free.” It can also be used to implement “get a free t-shirt when you buy a sweater” type campaigns or “members always get a free collectible key-ring” campaigns.

A group of matching items can have a size of 1 or more. The campaign works by creating a basket voucher with a monetary value of the regular price of the free item. In the get-basket-price call, the basket voucher is applied to the basket and the value of the voucher is subtracted from the total basket value.

In order to configure a free_product campaign the following fields must be set:

• assigned_barcodes - the barcodes of products that apply to the campaign
• min_earn_quantity - the minimum number of items that must be purchased per group of items in order for a user to be considered for a discount
• min_spend_quantity - the number of free items a customer will receive per group of items purchased

Meal Deal (type = meal_deal)

A basket campaign with product promotion type meal_deal will apply a fixed price to a group of items where each item in the group matches a different subgroup of campaign assignments.

This product promotion type can be used to implement “buy a burger, fries and a drink for $5” type promotions. It is not restricted in value or size of groupings of items, so can be used for promotions such as “buy a Volkswagen, a Mercedes and a Honda for €100,000”.

In order to configure a meal_deal campaign the following fields must be set:

• assigned_groups - an array of arrays of barcodes of products that apply to the campaign. In order for the promotion to apply, one item must be purchased from each group. The format of this array is best shown using the “burger, fries and drink” model described above:
  • assigned_groups['burgers'] - an array of barcodes of burgers that apply to the campaign
  • assigned_groups['fries'] - an array of barcodes of fries that apply to the campaign
  • assigned_groups['drinks'] - an array of barcodes of drinks that apply to the campaign
• recipient_reward_amount - the fixed price a customer will pay for the group of items matching the campaign assignments for this particular promotion
• min_earn_quantity - the minimum number of items that must be purchased in order to qualify for the discount - each of these items must be from a different group in the assigned_groups array

It is possible to qualify for the same discount multiple times in a single basket when using the get-basket-price, add-basket or add-basket-item calls. For example, if a customer adds 2 burgers, 2 fries and 2 drinks to their basket, they will qualify for the discount twice and will pay 2 x recipient_reward_amount for the 6 items.

Product Combination Price (type = product_combo_price)

A basket campaign with product promotion type product_combo_price campaign will apply a fixed price for a group of items are purchased together. This type of campaign is similar to a meal_deal campaign, but the items in the group must be purchased together and there is no requirement to buy from multiple subgroups.

This product promotion type can be used to implement “3 large bottles of soft drinks for €5” type promotions. It is not restricted in value or size of groupings of items, so can be used for promotions such as “any 10 rugs for $1,000”.

In order to configure a product_combo_price campaign the following fields must be set:

• assigned_barcodes - the barcodes of products that apply to the campaign
• min_earn_quantity - the number of items that must be purchased in order to qualify for the discount
• recipient_reward_amount - the fixed price a customer will pay for the group of items matching the campaign assignments for this particular promotion

It is possible to qualify for the same discount multiple times in a single basket when using the get-basket-price, add-basket or add-basket-item calls. For example, if a customer adds 6 bottles of soft drinks to their basket, they will qualify for the discount twice and will pay 2 x recipient_reward_amount for the 6 items.

Fields specific to type: wallet

A wallet campaign functions as a ‘savings account’ for a customer. A customer’s wallet is credited with balances amounts as a customer makes purchases, completes other actions, or when a member of staff assigns an amount to the customer.

The balance in a wallet, or a fraction of it, can be converted into a voucher whose value can be redeemed against a purchase by a customer. This takes place through the :ref:create-voucher call. The moment that the wallet balance is redeemed is either chosen by the customer or occurs automatically according to campaign rules.

A wallet campaign is usually configured in conjunction with other campaigns. These are known as ‘contributors’ and contain different logic for contributing amounts to a wallet balance when certain actions take place or rules are matched.

A wallet campaign is usually configured with a real-life currency.

Spaaza supports the ability to run multiple wallet and points_wallet campaigns by having the concept of a default wallet. Typically, the first points_wallet and wallet of a chain will be the default. If a wallet or points_wallet is configured to be no-longer the default wallet by setting is_default:false any campaign that was contributing into that wallet or points_wallet will be set inactive and their recipient_campaign_id will be set null.

Fields specific to type: wallet, points wallet and entries wallet

A points wallet campaign is similar to a wallet campaign in that it acts as a ‘savings account’ for a customer, with the exception that it is not normally possible to convert a points wallet balance into a voucher which can be redeemed against a purchase. Instead, it is possible to configure campaigns which take other actions when a certain number of points is saved by the customer.

A points wallet is also usually configured in conjunction with other campaigns in the same way as a wallet campaign. Again, these are known as ‘contributors’.

A points campaign is always configured with a virtual currency such as ‘points’ or ‘punten’.

Fields specific to type: loyalty

A loyalty campaign allows the creation of rules to enable multi-level loyalty programmes. The rules which can be set in place are designed to trigger when certain events take place for a customer (purchase particular items, transactions above a certain value, points balance passing a defined threshold) and take actions which are also configured as part of the rule set (issue a voucher to the customer, raise their membership level, allow them extra discounts).

Loyalty campaign rules can generally be configured in conjunction with other existing campaigns.

It is possible to configure loyalty campaign rules so that any vouchers issued to customers are either directly associated with the loyalty campaign or with one of the other campaigns associated with the loyalty campaign.

Fields specific to type: progress

This campaign type functions as a kind of ‘savings account’ type. By tracking the customer behaviour, this campaign will generate a new voucher for the customer to use whenever a certain spending threshold is reached.

A progress campaign can be configured to activate the first time the spending threshold is reached or every time a multiple of the spending threshold is reached.

A progress campaign can be configured as a ‘contributor’ to a wallet or points wallet campaign. When the spending target is reached the specified amount of currency or points is contributed to the shopper’s wallet or points wallet.

Fields specific to type: matching_item

A Matching Item Campaign awards customers a predetermined amount or reward when the items in their cart align with a specified campaign assignment.

When establishing this campaign, there are mandatory configurations:

1. Campaign Assignment: This can be any of the following: assigned_barcodes, assigned_currencies, or assigned_business_ids.

2. Recipient Reward Method: Choose from voucher, percentage_basket_voucher, points, or wallet.

3. Recipient Reward Amount: The designated amount or percentage of purchase value the customer will receive as a reward.

The default setting grants a reward for every qualifying item in the customer’s basket. However, it is possible to award a customer on the total value of the qualifying items or the value of the basket. For this, set award_calculated_on_item_value or award_calculated_on_basket_value.

For example, to configure a campaign where 20% of the value of purchased items is awarded as a wallet amount, and where a minimum quantity of 3 items must be purchased to receive this reward, set the following parameters:

• recipient_reward_method: wallet
• recipient_reward_amount: 0.2
• award_calculated_on_item_value: true
• min_earn_quantity: 3

Fields specific to type: cashback

A cashback campaign is a campaign which ‘contributes’ a proportion of the value of every basket a customer purchases either in currency to a wallet or in points to a points wallet.

It is possible to configure a cashback campaign to contribute to a wallet or points wallet in a granular way. For example, a cashback campaign can be configured only to contribute to a (points) wallet when a customer purchases non-promotional items.

Fields specific to type: profile_completion

Use this campaign to reward customers for filling in certain fields of their profile. A reward will only ever be given once per user per campaign.

* For a reward to be given based on a user’s address, all of the following four user address fields must be populated: address_streetname, address_housenumber, address_postalcode, address_towncity

Fields specific to type: interaction

Fields specific to type: purchase_count

This campaign rewards customers who return to make several purchases.

Each time a customer makes a transaction when this campaign is active, their transactions that are not pure returns, i.e. a new item was purchased, are tallied up and if their number meets or exceeds the “target_count” parameter of this call, a reward is given to the customer in the form of a voucher or a contribution to their wallet or points balance, depending on the “recipient_reward_method” parameter in this call. The value of the reward is set in the “recipient_reward_amount” parameter in this call.

The campaign will only issue the reward at most once per campaign per customer. If a customer had already made a sufficient number of eligible transactions before the campaign was started, they will be rewarded on their next transaction.

Optionally, you can specify the “include_old_baskets” parameter. By default, transactions made before the campaign was created are included. By setting “include_old_baskets” to false (or 0) only transactions made after the campaign was created are considered. This will allow your previous customers with potentially many purchases to still be able to receive the reward of this campaign.

Fields specific to type: item_purchase_count

This campaign issues a fixed award to a user based on the number of purchases of a particular item. When creating the campaign you set a target_count which the number of times you must have purchased an item to be issued a reward. It is also possible to exclude items that were purchased before the campaign was created by setting include_old_baskets false.

When configuring the campaign you must set a campaign_assignment eg. assigned_barcodes, assigned_currencies, assigned_business_ids as well as the recipient_reward_method voucher, points, wallet and a recipient_reward_amount.

Fields specific to type: signup

This campaign gives a new customer a configurable reward for signing up for a programme.

A signup campaign can be configured as a standalone campaign, in which case a basket voucher is issued which can be redeemed against a subsequent purchase by the customer, or as a ‘contributor’ to a wallet or points wallet campaign, in which case an amount of points or currency is contributed to the customer’s (points) wallet when they join the programme.

It is possible to restrict a signup campaign so that the amount is only issued when the customer joins via the webshop, a store staff app or via the mobile app.

Fields specific to type: content and mobile_content

This type of campaign is used for management of general content including images and includes prioritisation features.

mobile_content campaigns extends content campaigns to allow them to be used specifically for management of content in a mobile context.

Fields specific to type: login

This campaign gives a customer a configurable reward when logging in as a user from a particular channel, ie. webshop, or a particular app ie Android, iOS.

When configuring this campaign_type you must set the user_channel campaign parameter which will be stored as a comma separated string eg. mobile:android,mobile:iOS.

Fields specific to type: subscription campaign

Fields specific to type: referral

This campaign type rewards members for inviting their friends to join the programme. When this campaign is enabled, a member-unique signup code is created for display on the member’s card page in e.g. a mobile app. This is displayed in the results of the :ref:get-card call in the promotions > referral section.

A member can be invited to join by sending them a URL containing the signup code (e.g. via email or social media). The invitation recipient (“recipient”) clicks on the link. When they register, a reward may be given to the recipient in the form of a voucher or a contribution to their wallet or points balance, depending on the “recipient_reward_method” parameter in this call. The value of the reward is set in the “recipient_reward_amount” parameter in this call.

When the recipient makes their first purchase, a reward may be give given in the form of a voucher or a contribution to their wallet or points balance, depending on the “sender_reward_method” parameter in this call. The value of the reward is set in the “sender_reward_amount” or the “sender_reward_discount_ratio” parameter in this call, depending on the “sender_reward_method” chosen.