Composable campaigns

Composable campaigns

Contents

• Overview
• Key concepts
  • Assigned groups
  • Restrictions
  • Reward methods
  • Reward method types
  • Reward method restrictions
• Rewards handling behaviour
• Configuration flow
• Complete example
• Competition draw example
• Distribution rules
• Value calculation rules
• Endpoints reference

Overview

Composable campaigns represent a modular approach to campaign configuration in Spaaza. Unlike traditional campaign types that bundle all configuration in a single entity, composable campaigns separate targeting, conditions, and rewards into independent, reusable components.

A fully configured composable campaign consists of:

1. Campaign - The base campaign entity with type: "composable"
2. Assigned Groups - Collections of product barcodes for targeting
3. Restrictions - Rules that determine when the campaign applies
4. Reward Methods - How rewards are calculated and distributed

This modular architecture provides several benefits: assigned groups can be reused across multiple campaigns, restrictions can be combined to create complex eligibility rules, and reward methods can be configured independently of the campaign's targeting logic.

Key concepts

Assigned groups

Assigned groups define collections of product barcodes that can be used for campaign targeting. They are chain-scoped entities that can be reused across multiple campaigns.

Field	Type	Description
name	string	Group name (max 255 characters, required for new groups)
type	string	qualify (for use in restrictions) or redeem (for use in reward methods)
required_matches	integer	Minimum number of matching items required in the basket (default 0)
barcodes	array	Array of product barcode strings (duplicates not allowed)
excludes_barcode_matches	boolean	When true, the group matches items that are NOT in the barcode list (default false)

The type field determines how the assigned group is used:

• qualify groups are used in restrictions to determine which baskets qualify for the campaign
• redeem groups are used in reward methods to determine which items receive the reward

Restrictions

Restrictions define conditions under which a campaign applies. Multiple restrictions can be added to a campaign, and all restrictions must be satisfied for the campaign to activate.

Type	Description	Configuration Fields
basket_item	Restrict by items in the basket	assigned_groups (array of IDs), max_basket_items_considered
basket_total_value	Restrict by basket total value	minimum_basket_total_value, maximum_basket_total_value
budget	Restrict by total campaign budget	budget (float)
budget_period	Restrict by budget within a time period	budget_period_campaign, budget_period_quantity, budget_period_quantity_unit
business	Restrict by business location	business_ids, business_formats, business_regions
currency	Restrict by transaction currency	currencies (array of 3-letter ISO codes)
reward_limit	Limit redemptions per user within a time period	reward_limit: {quantity, unit, scale}
segment	Restrict by user segment membership	user_segment_id, excluded_user_segment_id
usage_cost	Deduct wallet balance per campaign interaction	wallet_id (integer), cost (integer, >= 1)

When a campaign response includes a budget restriction, the restriction object also includes budget_balance, representing the current calculated spend against the configured budget.

Reward limit units: year, month, week, day, hour, calendar_day.

Reward limit scale: Optional positive integer multiplier for the unit. For example, unit: "month" with scale: 3 applies the limit over a rolling 3-month period. When omitted, scale defaults to 1.

Usage cost: The usage_cost restriction deducts the configured cost amount from the user's balance in the specified wallet each time a reward is issued. If the user does not have sufficient balance, the campaign will not activate. The wallet_id must reference a valid wallet belonging to the same chain as the campaign.

Restrictions can also be set inline when creating or updating a composable campaign via the add-campaign or alter-campaign endpoints. Pass a restrictions object keyed by restriction type:

{
    "campaign_id": 100,
    "restrictions": {
        "currency": {
            "currencies": ["EUR"]
        },
        "basket_item": {
            "assigned_groups": [1]
        }
    }
}

When restrictions are set inline, they replace all existing restrictions on the campaign.

Reward methods

Reward methods define how rewards are calculated and distributed to users.

Field	Type	Description
type	string	The reward method type (see Reward method types)
priority	integer	Processing order (lower numbers are processed first)
usage_limit	integer	Maximum number of times this reward method can issue rewards. null means no limit
value	float	The reward value. For percentage types, a decimal between 0 and 1 (e.g., 0.05 for 5%)
value_calculation_rule	string	items_value (matched items only) or basket_value (entire basket)
distribution_rule	string	all_items, cheapest_item, or most_expensive
selection	string	Item selection order: high_to_low or low_to_high
recipient_wallet_id	integer	The wallet ID to credit (required for wallet_contribution type)
honour_code	string	The code shown to the user or scanned by staff (for honour_voucher type)
restrictions	object	Optional spend-context restrictions (see Reward method restrictions)
metadata	object	Display information: title, subtitle, description, image_url, notes, log_message

Reward method types

The type field on a reward method determines how the reward is calculated and delivered:

Instant voucher types - Create a voucher that is applied immediately to the current basket:

Type	Description
instant_fixed_price	Applies a fixed price discount to matched items in the basket
instant_fixed_discount	Applies a fixed amount discount to the basket
instant_percentage	Applies a percentage discount to the basket

Deferred voucher types - Create a voucher that can be redeemed in a future transaction:

Type	Description
deferred_fixed_price	Creates a voucher with a fixed price discount for a future purchase
deferred_fixed_discount	Creates a voucher with a fixed amount discount for a future purchase
deferred_percentage	Creates a voucher with a percentage discount for a future purchase

Other types:

Type	Description
wallet_contribution	Credits a wallet or points wallet with the calculated reward value
honour_voucher	Creates a voucher with an honour code that can be validated externally (e.g., by staff)

Reward method restrictions

Reward methods can have their own restrictions that apply at redemption time. These are evaluated when a deferred voucher created by the reward method is being redeemed in a subsequent transaction.

The following restriction types are supported on reward methods:

Type	Description	Configuration Fields
basket_item	Restrict redemption by items in basket	assigned_groups (array of IDs with type redeem)
business	Restrict redemption by business location	business_ids, business_formats, business_regions
currency	Restrict redemption by currency	currencies (array of 3-letter ISO codes)

Reward method restrictions are set via the restrictions field when creating or updating a reward method:

{
    "campaign_id": 100,
    "type": "deferred_percentage",
    "priority": 1,
    "restrictions": {
        "currency": {
            "currencies": ["EUR"]
        },
        "business": {
            "business_ids": [10, 20]
        }
    },
    "configuration": {
        "value": 0.10,
        "value_calculation_rule": "items_value",
        "distribution_rule": "all_items"
    }
}

Rewards handling behaviour

The rewards_handling_behaviour field on a composable campaign controls how its reward methods are evaluated. This field is set when creating or updating the campaign.

independent (default)

Each reward method is evaluated independently. All eligible reward methods are processed in priority order, and each one that matches issues its own reward. This is the standard behaviour for campaigns that should issue multiple rewards per transaction (e.g., cashback on different product groups).

random_draw

A single reward method is randomly selected from the eligible candidates. This enables competition-style campaigns where each interaction results in one randomly chosen prize. The flow is:

1. Eligible reward methods are determined based on remaining capacity (usage_limit)
2. One reward method is randomly selected from the eligible candidates
3. The selected reward method issues its reward directly to the user
4. If a usage_cost restriction is configured, the cost is deducted from the user's wallet

Composable campaigns with random_draw behaviour can be triggered via the interact-campaign endpoint without requiring a basket. This is useful for scratch-card or prize-draw style interactions where the user does not need to make a purchase.

Configuration flow

The typical setup order for a composable campaign is:

1. Create a wallet (if one does not already exist) - This will be the destination for earned rewards
2. Create the base campaign with type: "composable"
3. Create assigned groups with the product barcodes that should qualify for or receive rewards
4. Add restrictions referencing the assigned groups to define eligibility rules
5. Configure the reward method to define how rewards are calculated and distributed

For competition draw campaigns, the setup order is:

1. Create a wallet (if one does not already exist) - For points-based entry costs and/or wallet rewards
2. Create the base campaign with type: "composable" and rewards_handling_behaviour: "random_draw"
3. Add a usage cost restriction (optional) to require points for each interaction
4. Configure reward methods with usage_limit set to define the prize pool

Complete example

This example creates a "5% cashback on premium products" campaign.

Step 1: Create an assigned group for qualifying products

POST /internal/alter-assigned-group

{
    "chain_id": 1,
    "name": "Premium Products Qualify",
    "type": "qualify",
    "required_matches": 1,
    "barcodes": ["PREMIUM_001", "PREMIUM_002", "PREMIUM_003"]
}

Response includes assigned_group_id (e.g., 1).

Step 2: Create the composable campaign with inline restrictions

POST /internal/add-campaign

{
    "chain_id": 1,
    "type": "composable",
    "title": "Premium Products 5% Cashback",
    "description": "Earn 5% cashback on all premium product purchases",
    "active": true,
    "is_contributor": true,
    "restrictions": {
        "basket_item": {
            "assigned_groups": [1]
        },
        "currency": {
            "currencies": ["EUR"]
        },
        "reward_limit": {
            "reward_limit": {
                "quantity": 10,
                "unit": "month",
                "scale": 1
            }
        }
    }
}

Response includes campaign_id (e.g., 100).

Step 3: Configure the reward method

POST /internal/alter-reward-method

{
    "campaign_id": 100,
    "type": "wallet_contribution",
    "priority": 1,
    "configuration": {
        "value": 0.05,
        "value_calculation_rule": "items_value",
        "distribution_rule": "all_items",
        "recipient_wallet_id": 42
    },
    "metadata": {
        "title": "5% Cashback",
        "description": "Earn 5% back on premium products"
    }
}

Competition draw example

This example creates a competition draw campaign where users spend 100 points per draw and can win one of several prizes.

Step 1: Create the composable campaign with random draw behaviour

POST /internal/add-campaign

{
    "chain_id": 1,
    "type": "composable",
    "title": "Summer Prize Draw",
    "description": "Spend 100 points for a chance to win prizes",
    "active": true,
    "rewards_handling_behaviour": "random_draw",
    "restrictions": {
        "usage_cost": {
            "wallet_id": 50,
            "cost": 100
        }
    }
}

Response includes campaign_id (e.g., 200).

Step 2: Add reward methods as prizes with usage limits

POST /internal/alter-reward-method

{
    "campaign_id": 200,
    "type": "honour_voucher",
    "priority": 1,
    "usage_limit": 5,
    "configuration": {
        "honour_code": "GRAND_PRIZE",
        "value": 0
    },
    "metadata": {
        "title": "Grand Prize",
        "description": "You won the grand prize!"
    }
}

POST /internal/alter-reward-method

{
    "campaign_id": 200,
    "type": "wallet_contribution",
    "priority": 2,
    "usage_limit": 100,
    "configuration": {
        "value": 50,
        "recipient_wallet_id": 50,
        "value_calculation_rule": "basket_value",
        "distribution_rule": "all_items"
    },
    "metadata": {
        "title": "50 Bonus Points",
        "description": "You won 50 bonus points!"
    }
}

Step 3: Trigger the draw for a user

GET /interact-campaign?campaign_id=200&user_id=12345

See the interact-campaign endpoint documentation for full details.

Distribution rules

The distribution_rule in a reward method determines how the reward is allocated across basket items:

all_items

Distributes the reward proportionally across all matched items based on their value.

Example: A 20 EUR reward on items worth 50, 30, and 20 EUR results in a distribution of 10, 6, and 4 EUR respectively.

cheapest_item

Applies the entire reward to the cheapest matched item per threshold.

Example: A 20 EUR reward is applied entirely to the 20 EUR item.

most_expensive

Applies the entire reward to the most expensive matched item per threshold.

Example: A 20 EUR reward is applied entirely to the 50 EUR item.

Value calculation rules

The value_calculation_rule determines what value is used for percentage calculations:

items_value (default)

Calculates the reward based only on the value of matched items.

Example: A basket has 100 EUR total, but only 60 EUR of matched items. A 5% reward equals 3 EUR (5% of 60).

basket_value

Calculates the reward based on the entire basket value.

Example: A basket has 100 EUR total, with 60 EUR of matched items. A 5% reward equals 5 EUR (5% of 100).

Endpoints reference

Campaign endpoints

Endpoint	Method	Description
/internal/add-campaign	POST	Create a new campaign (supports inline restrictions)
/internal/alter-campaign	POST	Update an existing campaign (supports inline restrictions)

Assigned group endpoints

Endpoint	Method	Description
/internal/alter-assigned-group	POST	Create or update assigned group
/internal/get-assigned-group	GET	Get single assigned group
/internal/get-assigned-groups	GET	List assigned groups (paginated)
/internal/delete-assigned-group	DELETE	Delete assigned group

Restriction endpoints

Endpoint	Method	Description
/internal/alter-restriction	POST	Create or update restriction
/internal/get-restriction	GET	Get single restriction
/internal/get-restrictions	GET	List restrictions (paginated)
/internal/delete-restriction	DELETE	Delete restriction

Reward method endpoints

Endpoint	Method	Description
/internal/alter-reward-method	POST	Create or update reward method
/internal/get-reward-method	GET	Get single reward method
/internal/get-reward-methods	GET	List reward methods (paginated)
/internal/delete-reward-method	DELETE	Delete reward method

Interaction endpoints

Endpoint	Method	Description
/interact-campaign	GET	Trigger a campaign interaction (for random_draw composable campaigns)

All internal endpoints require admin authentication with write access to the chain.