Campaigns

A campaign is a time-bound change to what participants earn: double points for a month, a launch-week rate, a category push. In Scrip a campaign is a group of rules with an active_from and active_to window. The rules, budgets, windows, and configuration history you already use are the campaign. There is no separate resource to create. Writing rules covers the window fields on a single rule. Use this page when a promotion has to coexist with the rates you already pay, has a spend cap, or has to be launched and retired as a unit.

Choose a shape

The first decision is how the campaign relates to your base rules.

You want	Where the campaign rules go	Why
Bonus on top of the base rate (stack)	Their own set, positioned after your earning set	Every set with a matching rule runs, so the base rate and the bonus both pay
Replace the base rate for the window (override)	The same set as the base rate, positioned first, with `stop_after_match: true`	A match stops the rest of that set, so the base rule is skipped while the window is open
Reward a new behavior only during the window	Their own set	Nothing to interact with

Stacking is the safer default. Override only when the campaign rate is meant to be the whole rate.

Stack a bonus

Add a campaigns set after your earning set. Each campaign is one or more rules in that set with a window. This one adds 2% on dining for October:

POST /v1/programs/{programId}/rule-sets

{"key": "campaigns", "name": "Campaigns"}

POST /v1/rules

{
  "program_id": "{programId}",
  "rule_set_id": "{campaignsRuleSetId}",
  "name": "october_dining_bonus",
  "active_from": "2026-10-01T00:00:00Z",
  "active_to": "2026-11-01T00:00:00Z",
  "condition": "event.type == \"purchase\" && event.mcc in [\"5812\", \"5813\", \"5814\"]",
  "actions": [
    {
      "type": "CREDIT",
      "asset_id": "{assetId}",
      "amount": "${{ round(event.amount * 0.02, 2) }}",
      "description": "October dining bonus"
    }
  ]
}

A dining purchase stamped in October earns the base rate from the earning set plus 2% from this rule. Stamped in November, the rule is skipped and the base rate pays alone.

Override the base rate

To pay a flat 5% on everything during launch week instead of the usual rates, put the rule in the earning set, first, with stop_after_match:

POST /v1/rules

{
  "program_id": "{programId}",
  "rule_set_id": "{earningRuleSetId}",
  "position": {"placement": "first"},
  "stop_after_match": true,
  "name": "launch_week_5pct",
  "active_from": "2026-10-01T00:00:00Z",
  "active_to": "2026-10-08T00:00:00Z",
  "condition": "event.type == \"purchase\"",
  "actions": [
    {
      "type": "CREDIT",
      "asset_id": "{assetId}",
      "amount": "${{ round(event.amount * 0.05, 2) }}",
      "description": "Launch week 5%"
    }
  ]
}

Inside the window, a purchase matches this rule and the rest of the earning set is skipped. Outside the window, the rule is skipped and the earning set runs as before. Rules in other sets, such as tracking or the campaigns set, run either way. See Set-local stopping.

Windows

Field	Effect
`active_from`	Inclusive. Events stamped before it skip the rule.
`active_to`	Exclusive. Events stamped at or after it skip the rule.

Both are compared to the event’s event_timestamp, not the clock when Scrip processes it. That has three consequences:

You can create campaign rules weeks ahead. They start and stop on their own.
Retries and replays make the same decision as the original run.
A backdated event can land inside a window that has already closed. Historical imports fire past campaigns unless you suspend or archive the rules first.

A skipped evaluation is recorded on the event with reason OUTSIDE_TIME_WINDOW, so you can confirm a campaign is dormant by reading any event’s trace.

Cap the spend

A budget on the campaign rule caps what it issues across all participants. A lifetime budget is the right shape for a one-off campaign: once the pool is spent, the rule keeps matching but its actions are skipped with reason BUDGET_EXCEEDED, and the base rate still pays.

{
  "budgets": [
    {"asset_id": "{assetId}", "limit": "250000"}
  ]
}

To limit each participant instead, gate the rule on a tag or counter it sets. One bonus per participant for the whole campaign:

{
  "condition": "event.type == \"purchase\" && !(\"october_bonus_paid\" in participant.tags)",
  "actions": [
    {"type": "TAG", "tag": "october_bonus_paid"},
    {"type": "CREDIT", "asset_id": "{assetId}", "amount": "1000", "description": "October welcome bonus"}
  ]
}

A budget and a per-participant gate are independent. Use both to cap the pool and the individual at the same time. See Budgets. For a campaign paid in its own currency with a hard ceiling, link a PREFUNDED asset and fund the program wallet with the pool. Credits fail when the wallet is empty. See Asset configuration.

Test before launch

Send the campaign rules as a draft rule_configuration to POST /v1/test-runs with scenario events stamped inside and outside the window. Set options.compare_live to see what the current configuration would have paid on the same events. Test runs roll back, so nothing is credited. Check three things: an in-window event pays the campaign amount, an out-of-window event pays only the base rate, and for an override, the base rule is not reached inside the window. See Testing.

Launch as one change

When a campaign is more than one rule, publish them together with /rule-configuration/preview and /rule-configuration/apply so they go live in one version. The change is recorded as a revision you can diff or roll back later. See Managing rule configuration. Because windows do the scheduling, apply the change whenever it is convenient. The rules stay dormant until active_from.

During the campaign

You want	Do
Stop it early	Set the rule’s `status` to `SUSPENDED`. Events not yet processed skip it immediately.
Change the rate	`PATCH` the rule. Events already processed keep the old result; events not yet processed use the new one. See Updating rules under live traffic.
See how much has been paid	Read the rule. Its `budgets` array reports `consumed`.
See why an event did or did not get the bonus	Read the event. Its `rule_evaluations` show the campaign rule as matched, `OUTSIDE_TIME_WINDOW`, or `BUDGET_EXCEEDED`.

Name the campaign in each CREDIT’s description. It appears on participant statements and journal entries, which is how finance and support tell campaign credits from base earning.

After the campaign

The window closes on its own. The rules stay in the configuration as a record of what ran. Archive them once you no longer need them in the active list, or leave them; a rule outside its window costs one skipped evaluation per matching event. To run the same campaign again, PATCH the window on the existing rule or apply a new revision with fresh dates. To undo a campaign that was configured wrong, roll back to the revision before it was applied.

Time-windowed rules

The window fields and how they read the event timestamp.

Rule sets

Set order, positions, and set-local stopping.

Test a full configuration

Run the draft against in-window and out-of-window events.

Getting Started

Foundations

Earning

Participant State

Ledger & Balances

Spending

Operations

Advanced

Reference

Choose a shape

Stack a bonus

Override the base rate

Windows

Cap the spend

Test before launch

Launch as one change

During the campaign

After the campaign

Time-windowed rules

Rule sets

Test a full configuration

​Choose a shape

​Stack a bonus

​Override the base rate

​Windows

​Cap the spend

​Test before launch

​Launch as one change

​During the campaign

​After the campaign

Time-windowed rules

Rule sets

Test a full configuration

Choose a shape

Stack a bonus

Override the base rate

Windows

Cap the spend

Test before launch

Launch as one change

During the campaign

After the campaign