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.

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.

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.

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:

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

Other types:

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:

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

Assigned group endpoints

Restriction endpoints

Reward method endpoints

Interaction endpoints

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