Link Search Menu Expand Document

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

Parameter Description
active (boolean, mandatory) Boolean flag whether or not the campaign is currently active.
active_date_from (datetime) Date/time (in UTC) from which the campaign is active. If left empty, the “from” date will be assumed to be infinitely far in the past.
active_date_until (datetime) Date/time (in UTC) until which point in time the campaign is active. If left empty, the “to” date will be assumed to be infinitely far in the future.
active_time_from (HH:MM:SS) A time of the day when a campaign starts being valid.
active_time_until (time HH:MM:SS) A time of the day when a campaign stops being valid.
active_weekdays (string) A comma-separated list of day numbers of the week on which a campaign is valid. When left empty (null), the campaign is valid on any day of the week.
allows_end_user_to_claim_voucher (boolean, optional, default true) This parameter controls whether a user authenticated as an end user can claim or unclaim a voucher during their session. By default, it is set to true, allowing these operations. If set to false, the user will not be able to perform these actions when the claim-voucher or unclaim-voucher endpoint is called.
allows_unrecognised_items (boolean, optional, default true) (basket campaign only) Whether this campaign can apply to an unrecognized basket item.
assigned_barcodes (array) Barcodes for this campaign are checked against APIs like :ref:get-basket-price and :ref:add-basket.
assigned_business_ids (array) An array of Spaaza store IDs relevant to this campaign, linked to business object in Spaaza.
assigned_currencies (array) An array of Spaaza currency IDs for this campaign. Update to this array replaces the previous list.
created_voucher_claimed_by_default (boolean,optional, default false) If a campaign is used to create basket vouchers and this flag is set to true, the vouchers will be created with status “claimed” by default. If this parameter is unset or set to false, vouchers will be created with status “generated”. Note that this does not affect whether the status of the voucher can later be changed or not.
currency_code (string) a three character ISO 4217 currency code ie, USD, EUR GBP.
currency_id (integer) The id of the currency to use for this campaign. Defaults to the currency of the entity (business/chain) that this campaign belongs to. This value can be different for different campaigns, for example when running points wallets in conjunction with other monetary campaigns.
description (string) The description of the campaign. Will be visible to customers in the MyPrice user interface.
excluded_user_segment_id (string, optional) The segment_id of Segment you wish to exclude from a Campaigns reward.
excludes_assignment_matches (boolean, optional, default false) If true, matches mean actions are not applied; the assignment is excluded, and everything else is included.
max_earn_quantity (float, optional) The max_earn_quantity is the maximum quantity of articles which a user can earn a reward on for a campaign.
max_reward_quantity (integer, optional, default value is 1, except for a referral campaign where the default value is null) The max_reward_quantity is the maximum number of rewards that can be applied to a user.
max_reward_quantity_unit (string, optional) This parameter requires a max_reward_quantity to be set, when both values are set max_reward_quantity_unit indicates how many times a customer can earn from a campaign in a certain time period. If max_reward_quantity_unit is null and a max_reward_quantity is set then the max_reward_quantity value is considered to be absolute/not time-limited.
max_spend_quantity (float, optional) The max_spend_quantity field, which is optional and of type float, is used in conjunction with campaigns issuing a basket_percentage_voucher reward. It specifies the number of items to which a voucher can be applied. By default, this field is set to null, which means the voucher will be applied to all qualifying items in the basket. However, if a specific value is set, the voucher will be applied only to that number of items. The corresponding voucher amount is then calculated based on the sum of those item values, determined by item_price * item_quantity.
minimum_basket_total_value (float, optional) The minimum total value of the basket in order for a campaign to be applied in the case that the campaign depends upon a purchase basket. By default, this field is set to null, which means the campaign will be applied to any basket. However, if a specific value is set, the campaign will be applied only to purchase baskets with a total value greater than or equal to that value.
notes (string) Notes attached to the campaign. Only visible to users administering this campaign.
operator_type (string) A string, either “or” or “and”, which determines how the selection of the campaign assignments works. “or” is the default, and means that if any of the assigned_* matches, the campaign applies. When the operator is “and”, all of the different assignments must match.
recipient_message_text (string, optional) Every time a campaign activates and a reward is generated during basket processing, this message will be added to the generated reward output. Special placeholders in this message will be replaced with their corresponding values at time of basket processing. See Reward Messages for an overview of the placeholders and how to use them.
recipient_reward_amount (float, required) The reward value a customer will receive from the campaign.
recipient_reward_method (string, required) Method to bestow the reward to a new user who signed up using a referral code. Valid values include voucher, percentage_basket_voucher, wallet, or points.
return_reclaims_earned_rewards (boolean,optional, default true) If set to true, the rewards earned by a user will be reclaimed if the user returns the items they were earned on.
rounding_precision (integer) The number of decimal points to which a monetary or points number is rounded. For example, when a customer purchases a basket with a monetary value of 20.87 and a points wallet campaign is applied with a cashback contributor campaign, if the rounding_precision is set to 0 and the rounding_strategy is set to round_down, 20 points will be added to the customer’s points wallet.
rounding_strategy (string) When a campaign deals with a monetary or points amount, rounding is often used to. This parameter can be configured to round_up, round_down or neutral accordingly. See the rounding_precision parameter for further details.
spend_on_promotional_items (boolean) Indicates whether a customer can redeem vouchers issued directly as part of the loyalty campaign on items categorized as promotional.
subtext (string) A sub-description of the campaign showing details of lesser importance such as terms and conditions applicable.
subtitle (string, optional) The subtitle of the campaign. Will be visible to customers in the Spaaza embed.
title (string, mandatory) The title of the campaign. Will be visible to customers in the MyPrice user interface.
visible_to_all_user_segments (boolean, optional) The visible_to_all_user_segments flag is used to determine whether a campaign is visible to all users irrespective if they’re a member of the Segment associated with the campaigns user_segment_id. The flag is used by get-card and get-campaigns when generating the response object.
voucher_text (string) Text field for setting the content which will be displayed on vouchers issued directly as part of the loyalty campaign.

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"}}}

Parameter Description
background_colour (string, optional) Sets background_colour value. Must be rgb, rgba or hex.
custom_content (JSON string, max 2048 chars) A JSON string containing custom content of any sort. For example: {"game":{"title":"My Game","description":"My Game Description","image":"http:\/\/www.example.com\/mygame.png","url":"http:\/\/www.example.com\/mygame"}}.
element_styling (JSON string, max 2048 chars) A JSON string containing styling information for Spaaza Elements associated with the campaign. Example: {"topnav":{"a":{"background-color":"#420","overflow":"hidden"},"a.hover":{"float":"right","color":"#f2f2f2"}}}.
layout_style (string, optional) Set the layout_style.
primary_action_text_colour (string, optional) Sets primary_action_text_colour value. Must be rgb, rgba or hex.
primary_action_background_colour (string, optional) Sets primary_action_background_colour value. Must be rgb, rgba or hex.
secondary_action_text_colour (string, optional) Sets secondary_action_text_colour value. Must be rgb, rgba or hex.
secondary_action_background_colour (string, optional) Sets secondary_action_background_colour value. Must be rgb, rgba or hex.
text_colour (string, optional) Sets text_colour value. Must be rgb, rgba or hex.

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.

Parameter Description
field_localisations (JSON string, optional) A JSON string containing an object for each field in the campaign which is to be localised, with the key named the same as the field in the campaign parameters. The object for each field to be localised contains an object for each language to be localised, with the key named with an ISO 639 language tag (e.g. en or de). Each of these objects, in turn, contains a value with key default containing a default string for this language, and values for individual ISO 639 language tags with optional subtags, separated by hyphens (e.g. nl-NL, en-US or fr-CA).

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.

Parameter Description
imagefile (file) The parameter name of the image uploaded - no other parameter name is accepted for an image. The image file itself can have any name as long as the suffix is .jpg, .jpeg or .png.
image_dimension_x (integer, optional) The intended x-axis display size of the image in pixels.
image_dimension_y (integer, optional) The intended y-axis display size of the image in pixels.
image_link (string, optional) The URI or URL to be used should the image be used to link to an external resource.
is_contributor (boolean) A boolean value to denote whether the campaign is configured to contribute an amount to a wallet or points wallet when activated. This field can be applied to the following campaign types: cashback, progress or signup.

Contributor campaign fields

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

Parameter Description
is_contributor (boolean) A boolean value to denote whether the campaign is configured to contribute an amount to a wallet or points wallet when activated. This field can be applied to the following campaign types: cashback, progress or signup.
recipient_campaign_id (integer) The campaign_id ID of the wallet or points wallet campaign to which the contributor contributes.

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.

Placeholder Resulting Value API Version
{firstname} The first or given name of the customer. 1.5.0

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.

Parameter Description
rules (array) An array of campaign rule objects. See :ref:add-campaign-rule or :ref:alter-campaign-rule.
basket_voucher_monetary_value (float) A field which, if supplied, will be used to set a fixed monetary value for the basket voucher issued instead of using the base_price_threshold value to calculate a percentage discount.
basket_minimum_total_value (float) A minimum total basket value below which the campaign does not apply.
product_promotion_type (string, optional) The type of product promotion campaign. Accepted values are product_combo_price, free_product, fixed_monetary_discount or meal_deal.

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.

Parameter Description
display_currency_code (string) These params are used to set the display_currency for a monetary wallet. The display_currency_code must be a valid ISO 4217 currency code.
display_currency_id (int) These params are used to set the display_currency for a monetary wallet. The display_currency_id is a Spaaza currency_id for a currency in the Spaaza DB.
display_currency_multiplication_factor (float) Sets the multiplication factor for a wallets display currency.

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’.

Parameter Description
is_redeemable (boolean) A value indicating whether an amount of the wallet balance can be converted into a voucher redeemable in subsequent purchases. Typically set to true for wallets and false for points.
max_manual_daily_amount (float) Represents the maximum daily balance change that can be configured in a wallet or points using :ref:add-user-purchase-progress. Designed to prevent fraudulent assignment of points or currency by employees to their accounts or those of their contacts.
balance_can_subzero (boolean) Denotes if a customer’s points or wallet balance can go below zero. Useful for scenarios like customer returns after already using the currency or points earned from the original purchase.
spend_on_promotional_items (boolean) Indicates if a customer can spend wallet balance on items categorized as promotional.
aggregate_wallet_balance_shown (boolean) Specifies if the total wallet contributions for the campaign should be showcased in the responses of the ‘get-campaigns’ or ‘get-card’ API.
is_default (bool, optional) The is_default flag is used to determine whether a campaign is a default Campaign. Typically, the concept of a default is used by points_wallet and wallet campaigns when running multiple wallet campaigns.

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.

Parameter Description
review_term_unit (string) The unit used for reviewing a user’s status in a particular campaign (for example a user’s loyalty status may be reviewed annually, or their wallet points balance may be zeroed every 2 years if they haven’t spent anything). Possible values are ‘year’, ‘month’, ‘week’, ‘day’, ‘hour’ and ‘minute’.
review_term_quantity (integer) The quantity of the unit used for reviewing a user’s status in a particular campaign (see review_term_unit). This must be an integer - e.g. 12 if a review term of 12 months is used.

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.

Parameter Description
start_amount (float) A value (in the campaign’s currency) indicating the starting amount of this progress campaign. Can provide customers some “free” progress towards the goal amount. Default value is 0.0.
goal_amount (float) Required field. A value greater than 0 that defines the goal amount of this campaign.
is_recurring (boolean) Indicates if this progress campaign can be utilized by a customer multiple times or just once. The default is set to true.
max_manual_daily_amount (float) Represents the maximum daily balance change that can be configured in a progress campaign using :ref:add-user-purchase-progress. Designed to prevent fraudulent assignment of progress by employees to their accounts or those of their contacts.
start_amount_allowed_channels (string) A list of channels, separated by commas, that are authorized to earn the start_amount for the campaign. Possible values might include “spaaza-native-app” and “spaaza-sales-associate-app”.

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.

Parameter Description
award_calculated_on_item_value (bool) Specifies if the reward should be derived from the combined value of matching items or their quantity. Default is false, meaning rewards are based on the quantity of items, each multiplied by the recipient_reward_amount.
award_calculated_on_basket_value (bool) A boolean value indicating whether the award should be calculated on the basket_total_value. Defaults to false (i.e. the award is calculated on the item quantity * recipient_reward_amount).
min_earn_quantity (int) The minimum quantity of items that must be purchased in order for a user to be considered for a reward. When award_calculated_on_item_value or award_calculated_on_basket_value are set true the indicates the minimum number of items that must be purchased in order for a user to be considered for a reward.

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.

Parameter Description
start_amount (float) Indicates the initial amount in the campaign’s currency. It can be used to offer some initial “free” progress towards the goal amount. Defaults to 0.0.
voucher_text (string) Configurable text displayed on the voucher earned upon completing the progress.
voucher_expiry_days (integer) Specifies the validity duration of a voucher in days from the time it’s generated. A default value of 0 implies the voucher doesn’t expire.
start_amount_allowed_channels (string) A comma-separated list detailing channels that can earn the start_amount for the campaign. Possible values include “spaaza-native-app” and “spaaza-sales-associate-app”.
earn_on_promotional_items (boolean) Indicates whether customers can earn points or balance when buying items designated as promotional.

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.

Parameter Description
field_mask (integer, required) A bit field mask that sets the boolean values for different fields. Users should use the bitwise-or operation (or simply add) the following values to specify which fields to consider: firstName (1), lastName (2), email (4), phone (8), gender (16), dateOfBirth (32), address (64), optedIn (128), registered (256), mailingListSubscribed (512), optInSecondary (1024).

Fields specific to type: interaction

Parameter Description
point_cost (int) (optional) Denotes the expense associated with interacting in a paid interaction campaign. This cost will be deducted from either the points_wallet or the wallet (i.e., monetary wallet).
point_cost_method (string) (required if point_cost is set) Helps identify the default monetary or points wallet to be charged, especially if a point_cost_method_wallet_campaign_id isn’t specified. Valid values are points or wallet.
point_cost_method_wallet_campaign_id (int) (optional) Refers to the campaign_id of a points or monetary wallet. This wallet gets charged if an interaction campaign has a specified points_cost.

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.

Parameter Description
target_count (integer) (required) The requisite number of transactions involving new purchases that a customer must achieve to qualify for the reward from this campaign.
include_old_baskets (boolean) Dictates if transactions executed prior to the campaign’s inception are considered in the campaign. The default value is true. Keep in mind that deactivating this option and setting a low target_count can also reward earlier customers on their subsequent Nth purchase.
voucher_expiry_days (integer) This indicates the lifespan of any voucher reward, measured in days, from the moment of its creation. A default value of 0 suggests that the voucher won’t expire. This parameter is disregarded when the awards aren’t categorized under voucher.

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.

Parameter Description
max_manual_daily_amount (float) Represents the maximum daily balance change that can be configured in an item purchase count campaign using :ref:add-user-purchase-progress. Designed to prevent fraudulent assignment of progress by employees to their accounts or those of their contacts.
target_count (int) The number of transactions with new purchases a customer has to complete to receive the reward of this campaign.

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.

Parameter Description
start_amount_allowed_channels (string) Comprised of a list separated by commas that details the channels permitted to accrue the start_amount associated with the campaign. Potential entries include “spaaza-native-app” and “spaaza-sales-associate-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.

Parameter Description
priority (integer, optional) Allows the assignment of a priority to a content campaign for the purpose of determining its order in relation to other campaigns. Primarily utilized in content campaigns, the sequence of campaigns in the response to :ref:get-campaigns can dictate the order in which the content appears.

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.

Parameter Description
user_channel (string, required) A comma-separated list of eligible user_channel channels for rewards from a campaign_type:login. Possible values include mobile:ios, mobile:android, and webshop.

Fields specific to type: subscription campaign

Parameter Description
stripe_price_id The ID corresponding to the price of a Stripe product linked with the integration.

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.

Parameter Description
requires_purchase_by_referred_user (boolean) Indicates if the referred user needs to make a purchase for the referring user to get their reward. By default, referral campaigns have this set as true. When false, the referring user gets their reward as soon as the referred user signs up successfully.
sender_voucher_title (string) The title of the voucher for the user making the referral (referring_user).
sender_voucher_description (string) A detailed description of the voucher for the referring_user.
sender_voucher_notes (string) Any additional notes or details associated with the voucher for the referring_user.
sender_voucher_image (string) A URL or identifier representing an image associated with the voucher for the referring_user.
sender_reward_amount (float, required under certain conditions) The numeric value that represents the reward amount given to the referral code owner when a new user, who signed up using their code, makes their first purchase.
sender_reward_discount_ratio (float, ≤ 1, up to 3 decimals, required under certain conditions) Represents a decimal discount provided by this reward. For instance, 0.25 signifies a 25% discount. This can only be used with sender_reward_method=percentage_basket_voucher.
sender_reward_method (string, required for referral) Describes the method for rewarding the referral code owner. Accepted values are voucher, percentage_basket_voucher, wallet, points, or none. A value of none disables the sender reward.
sender_reward_code An honor code employed when the sender’s reward method is voucher. If this field contains a value, an honor voucher will be created instead of a standard basket voucher.
recipient_voucher_title The title of the voucher intended for the user who was referred.
recipient_voucher_description A detailed description of the voucher for the referred user.
recipient_voucher_notes Any additional notes or details associated with the voucher for the referred user.
recipient_voucher_image A URL or identifier representing an image associated with the voucher for the referred user.