> For the complete documentation index, see [llms.txt](https://help.openloyalty.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://help.openloyalty.io/implementation-guide/module-checklists/campaigns.md).

# Campaigns

Designing the earning rules of a programme as campaigns — triggers, conditions, limits and effects — including welcome, birthday and other lifecycle rewards, and showing members how to earn.

Campaigns are the programme's rules: *when* something happens (a trigger), *if* it qualifies (conditions), *how often* (limits), *then* what the member gets (effects). The integration sends facts — transactions, custom events, profile changes — and campaigns turn them into points, rewards, badges and spins.

For the Admin Panel side, see [Campaigns](https://help.openloyalty.io/campaigns/campaigns), [Creating campaigns](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns) and [Automation campaigns](https://help.openloyalty.io/campaigns/campaigns/automation-campaigns). Multi-step goals are covered in [Challenges & missions](https://help.openloyalty.io/implementation-guide/module-checklists/challenges-and-missions.md); referral programmes in [Referrals](https://help.openloyalty.io/implementation-guide/module-checklists/referrals.md).

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-87cafbf76cf68776032fd54b5206da8f68a4630a%2Fig-campaigns-how-they-run.png?alt=media" alt="A trigger — a purchase or return transaction, a custom event, an internal event such as member activated or profile or tier updated, or time such as birthday, anniversary or a schedule — leads to conditions on the member, items, event attributes, labels, segment or tier. If the conditions are met and the limits per member, campaign or period aren&#x27;t reached, the effects run: add units to a wallet, issue a reward or coupon, grant a badge, or give a fortune wheel spin. Otherwise there is no effect." width="678"><figcaption><p>How a campaign runs</p></figcaption></figure>

## Who does what

| Area                           | Responsibility                                                                                                                       |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Programme / marketing team** | Defines the rules, rewards and budgets; configures and simulates campaigns in the Admin Panel                                        |
| **Integration layer**          | Sends the facts campaigns need (transactions, custom events with the right attributes, profile changes) — no reward logic of its own |
| **Website / app**              | Shows "ways to earn" from the campaign lists and the member's results from wallet and history                                        |
| **CRM / marketing automation** | Sends earn messages from `CampaignEffectWasApplied`                                                                                  |

## Design decisions

| Decision                          | Options                                                                                                            | Recommendation                                                                                                                                                                                                                                                                                                                                                                                          |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Where rules live                  | Campaigns in Open Loyalty, or code in the integration layer                                                        | Campaigns. Marketing can change them without a release, and simulation covers them.                                                                                                                                                                                                                                                                                                                     |
| Who a campaign applies to         | Conditions, [segments](https://help.openloyalty.io/members-and-activity/members/segments), tiers, or member labels | Segments and tiers for audiences that change over time; labels for flags your systems set (opt-ins, brand, migrated).                                                                                                                                                                                                                                                                                   |
| Trigger for lifecycle rewards     | Internal events, automation (time) campaigns, or custom events                                                     | Welcome on **Member Was Activated**; birthday and anniversary as automations; anything your systems decide (newsletter opt-in) as a custom event.                                                                                                                                                                                                                                                       |
| Automation budget                 | One automation per reward and brand                                                                                | Only **active** automation campaigns count towards the tenant's limit, and it's checked on activation. Combine rewards into fewer automations with several rules, rather than one automation per brand and reward.                                                                                                                                                                                      |
| Limits                            | None, per member, per campaign, per period                                                                         | Every campaign on a repeatable action has a per-member limit; costly campaigns also have a [global budget](https://help.openloyalty.io/campaigns/campaigns/campaign-limitation). Product promotions with a high reward get a [per-rule limit](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/rule-limits-and-rule-resolution) (e.g. 5 pieces of each SKU per member). |
| Overlapping rules in one campaign | Rewards add up (**Sum all**), or the first matching rule wins (**Priority wins**)                                  | Decide per transaction campaign. For "special price for one product inside a category offer", use **Priority wins** with the product rule above the category rule — see [Rule Limits and Rule Resolution](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/rule-limits-and-rule-resolution).                                                                            |
| Content for front ends            | Hard-coded in the channel, or stored on the campaign                                                               | Store display data (image URL, call to action) in campaign [custom attributes](https://help.openloyalty.io/campaigns/campaigns/custom-attributes-in-campaigns), so new campaigns need no release.                                                                                                                                                                                                       |

## Lifecycle rewards

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-dd10a7a97a279279afb8ac9c1b21e3590c866e24%2Fig-campaigns-lifecycle.png?alt=media" alt="Welcome: registration activates the member, and a Member Was Activated campaign gives welcome points and a badge to members who are not migrated and haven&#x27;t had it before; a CampaignEffectWasApplied webhook triggers the welcome message. Birthday and membership anniversary: automation campaigns run on birthDate and registeredAt, limited to once per member per calendar year. Later opt-in: the integration layer reads, merges and writes the profile with PUT to set the opt-in label, and a Member Profile Details Updated campaign rewards it once; PATCH doesn&#x27;t fire this trigger." width="475"><figcaption><p>Welcome, birthday, anniversary and later opt-in rewards</p></figcaption></figure>

| Reward                                         | Trigger                                                         | Conditions and limits                                                                                                                                                                                                                   |
| ---------------------------------------------- | --------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Welcome                                        | Internal event **Member Was Activated**                         | Not a migrated member (e.g. label `migrated` ≠ `true`); once per member                                                                                                                                                                 |
| Birthday                                       | Automation, birthday                                            | Once per member per calendar year; needs `birthDate` on the profile                                                                                                                                                                     |
| Membership anniversary                         | Automation, registration anniversary                            | Once per member per calendar year; uses `registeredAt` (keep the original date when migrating)                                                                                                                                          |
| Tenure milestone (30, 90, 365 days…)           | Daily automation with the **Days since registration** condition | Equals N days (0–7305); completions per member = 1. Forward-only — members past N at activation aren't rewarded. See [Creating automations](https://help.openloyalty.io/campaigns/campaigns/automation-campaigns/creating-automations). |
| Later opt-in (second brand, marketing consent) | Internal event **Member Profile Details Updated**               | Member has the opt-in label; reward not given before                                                                                                                                                                                    |
| Newsletter, app download, social connect       | Custom event                                                    | Once per member — see [Custom events](https://help.openloyalty.io/implementation-guide/module-checklists/custom-events.md)                                                                                                              |

{% hint style="warning" %}
**Member Profile Details Updated** fires on a full profile update (`PUT /member/{member}`), not on `PATCH`. If a later opt-in should be rewarded, set the opt-in with GET → merge → PUT — see [Member identity](https://help.openloyalty.io/implementation-guide/plan-and-foundations/member-identity.md).
{% endhint %}

## Recommended flow

{% stepper %}
{% step %}

### Write the rules down

For each earning rule: trigger, conditions, effect, limits, start and end dates, and who it's visible to. Agree budgets with finance.
{% endstep %}

{% step %}

### Make sure the facts arrive

Check that every attribute a condition needs is actually sent: item SKU or category on transactions, attributes on custom events, labels on the member.
{% endstep %}

{% step %}

### Configure and simulate

Build the campaigns on staging and run them through [campaign simulation](https://help.openloyalty.io/campaigns/campaigns/campaign-simulation) (Admin Panel, or `POST /api/{storeCode}/campaign/simulate`) with realistic baskets and members, before any test traffic.
{% endstep %}

{% step %}

### Show members how to earn

List campaigns for the member with `GET /api/{storeCode}/member/{member}/campaign/visible` (what the member may see) or `GET /api/{storeCode}/member/{member}/campaign` (active campaigns, with `limitReached` per campaign). Filter by label where several brands or sections share a tenant.
{% endstep %}

{% step %}

### Message the result

Subscribe to `CampaignEffectWasApplied` for earn messages. Show the balance from the wallet, not from the message.
{% endstep %}
{% endstepper %}

## Go-live checklist

### Admin Panel

* [ ] Every agreed rule exists as a campaign with the agreed dates, visibility and limits.
* [ ] Every campaign on a repeatable action has a per-member limit.
* [ ] Lifecycle rewards exclude migrated members where they shouldn't receive them again.
* [ ] The number of active automation campaigns fits the tenant's limit.
* [ ] Each campaign has been simulated with typical and edge-case inputs.

### Integration layer

* [ ] Transactions, custom events and profile updates carry every attribute the conditions use.
* [ ] Opt-ins that should be rewarded are written with PUT, not PATCH.

### Website / app and CRM

* [ ] "Ways to earn" are read from the campaign lists, not hard-coded.
* [ ] Earn messages come from `CampaignEffectWasApplied`.

### Validation

* [ ] Each campaign awards exactly what was agreed — no more after the limit.
* [ ] A new member gets the welcome reward once; a migrated member doesn't.
* [ ] A test member with today's birthday gets the birthday reward once.

## Key endpoints

* `GET /api/{storeCode}/member/{member}/campaign/visible` — [Get a list of visible campaigns for the member](https://help.openloyalty.io/api-reference/campaign/get-a-list-of-visible-campaigns-for-the-member)
* `GET /api/{storeCode}/member/{member}/campaign` — [Get a list of available campaigns for the member](https://help.openloyalty.io/api-reference/campaign/get-a-list-of-available-campaigns-for-the-member)
* `POST /api/{storeCode}/campaign/simulate` — [Simulate campaigns result](https://help.openloyalty.io/api-reference/campaign/simulate-campaigns-result)
* `GET /api/{storeCode}/campaign` — [Get campaigns list](https://help.openloyalty.io/api-reference/campaign/get-campaigns-list)

**Webhooks:** [CampaignEffectWasApplied](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignEffectWasApplied), [CampaignCreated](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignCreated), [CampaignUpdated](https://apidocs.openloyalty.io/#tag/Webhook-event/operation/CampaignUpdated)

{% hint style="warning" %}
**Common pitfalls**

* Computing points in the integration layer and sending them as manual adjustments: rules become invisible to marketing and untestable.
* Launching a campaign on an attribute the integration doesn't send yet.
* Hitting the active automation limit because each brand and reward got its own automation.
* Migrating members without a `migrated` label: everyone gets the welcome reward again.
* Writing an opt-in with PATCH and wondering why the opt-in campaign never fires.
* Leaving a product rule and its category rule on **Sum all** (the default), so the promoted product earns both rewards.
  {% endhint %}


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://help.openloyalty.io/implementation-guide/module-checklists/campaigns.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
