Campaign assignments

Campaign assignments allow you to control which products, stores, regions, channels, and currencies a campaign applies to. Assignments can be configured for two different contexts: earn (when rewards are issued) and spend (when vouchers are redeemed).

Contents

• Overview
• Earn vs Spend context
• Assignment types
  • Product assignments (barcodes)
  • Basket-level assignments
• Assignment matching logic
• Campaign type restrictions
• Assignment fields reference

Overview

Campaign assignments define the conditions under which a campaign applies. When a basket is processed, the system checks whether the basket items and context match the campaign’s assignments to determine if the campaign should be applied.

There are two main categories of assignments:

1. Product assignments - Control which products (by barcode) qualify for the campaign
2. Basket-level assignments - Control the context in which the campaign applies (store, region, format, channel, currency)

Earn vs Spend context

Assignments can be configured separately for two different contexts:

Earn context - Controls when rewards are issued to customers. When a customer makes a purchase, the earn assignments determine whether they qualify to receive a reward from the campaign.

Spend context - Controls when vouchers can be redeemed. When a customer attempts to redeem a voucher, the spend assignments determine whether the voucher can be applied to the current basket.

This separation allows for flexible campaign configurations. For example, you could create a campaign where customers earn rewards at any store, but can only redeem the resulting vouchers at specific stores.

Field naming conventions

The assignment fields follow these naming conventions:

• Barcode assignments: Use _earn and _spend suffixes explicitly (e.g., assigned_barcodes_earn, assigned_barcodes_spend)
• Basket-level assignments: The base field name (without suffix) represents the earn context, while the _spend suffix represents the spend context (e.g., assigned_business_ids for earn, assigned_business_ids_spend for spend)

Default behaviour

If no spend assignments are configured for a campaign, vouchers issued by that campaign can be redeemed in any context (no restrictions apply). This means spend assignments are optional and only need to be configured when you want to restrict where vouchers can be redeemed.

Assignment types

Product assignments (barcodes)

Product assignments control which products qualify for the campaign based on their barcodes.

Basket-level assignments

Basket-level assignments control the context in which the campaign applies, based on the store, region, format, channel, or currency of the transaction.

Assignment matching logic

The operator_type and excludes_assignment_matches fields control how multiple assignments are evaluated together.

operator_type

The operator_type field determines how different assignment types are combined:

• or (default) - The campaign applies if any of the assignment types match
• and - The campaign applies only if all of the assignment types match

For example, if a campaign has both assigned_business_ids and assigned_channels configured:

• With operator_type: "or" - The campaign applies if the basket is from a matching store OR uses a matching channel
• With operator_type: "and" - The campaign applies only if the basket is from a matching store AND uses a matching channel

excludes_assignment_matches

When excludes_assignment_matches is set to true, the assignment logic is inverted:

• Matches mean the campaign does not apply
• Non-matches mean the campaign does apply

This is useful for creating campaigns that apply to everything except specific products, stores, or channels.

Campaign type restrictions

Not all campaign types support spend basket-level assignments. The following campaign types do not support the _spend variants of basket-level assignment fields:

• Basket campaigns (type: basket) - These campaigns apply discounts directly during basket processing and do not issue vouchers that can be redeemed later
• Competition campaigns (type: competition) - These campaigns have their own redemption rules based on competition mechanics

Attempting to set assigned_business_ids_spend, assigned_business_formats_spend, assigned_business_regions_spend, or assigned_channels_spend on these campaign types will result in an error.

All other campaign types that issue vouchers (such as progress, cashback, item_purchase_count, matching_item, etc.) support spend basket-level assignments.

Assignment fields reference

For a complete list of all campaign fields including assignment fields, see the Campaign types and fields documentation.

Input format (API requests)

When creating or updating campaigns via the API, assignment fields accept comma-separated strings:

{
  "assigned_barcodes_earn": "barcode1,barcode2,barcode3",
  "assigned_business_ids": "123,456,789",
  "assigned_business_ids_spend": "456,789",
  "assigned_channels": "in_store,online",
  "assigned_channels_spend": "in_store"
}

Output format (API responses)

In API responses, assignment fields are returned as arrays:

{
  "assigned_barcodes_earn": ["barcode1", "barcode2", "barcode3"],
  "assigned_barcodes_spend": [],
  "assigned_business_ids": [
    {"id": 123, "name": "Store A"},
    {"id": 456, "name": "Store B"},
    {"id": 789, "name": "Store C"}
  ],
  "assigned_business_ids_spend": [
    {"id": 456, "name": "Store B"},
    {"id": 789, "name": "Store C"}
  ],
  "assigned_business_formats": [],
  "assigned_business_formats_spend": [],
  "assigned_business_regions": [],
  "assigned_business_regions_spend": [],
  "assigned_channels": ["in_store", "online"],
  "assigned_channels_spend": ["in_store"],
  "assigned_currencies": [],
  "assigned_groups": {}
}

Example: Campaign with different earn and spend locations

This example shows a campaign where customers can earn rewards at any store, but can only redeem vouchers at specific stores:

{
  "title": "Earn anywhere, redeem at flagship stores",
  "campaign_type": "progress",
  "assigned_barcodes_earn": "product1,product2,product3",
  "assigned_business_ids_spend": "100,101,102",
  "recipient_reward_method": "voucher",
  "recipient_reward_amount": 10.00,
  "goal_amount": 50.00
}

In this configuration:

• Customers can earn progress towards the reward by purchasing qualifying products at any store
• When the goal is reached and a voucher is issued, the voucher can only be redeemed at stores with IDs 100, 101, or 102