> 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/custom-events.md).

# Custom Events

Rewarding what members do outside a purchase — reading content, entering codes, registering devices, opting in — with custom events, safely and only once.

A custom event is anything a member does that isn't a purchase: reading an article, answering a survey, entering a code from a pack, registering a device, subscribing to a newsletter, connecting a social account. Your systems send the event; campaigns and challenges in Open Loyalty decide what it's worth.

For purchases and returns, use [transactions](https://help.openloyalty.io/implementation-guide/module-checklists/transactions.md). For the Admin Panel side, see [Custom events](https://help.openloyalty.io/members-and-activity/custom-events), [Custom event schemas](https://help.openloyalty.io/members-and-activity/custom-events/custom-event-schemas) and the [custom event](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/trigger-types/custom-event) campaign trigger.

## Who does what

| Area                           | Responsibility                                                                                                                                                                                                                                                                                                                           |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Admin Panel**                | One schema per event type with the attributes rules need; custom event campaigns, [challenges](https://help.openloyalty.io/campaigns/challenges) and, for codes, [redemption code campaigns](https://help.openloyalty.io/campaigns/campaigns/campaigns-and-referral-campaigns/creating-campaigns/trigger-types/redemption-code-campaign) |
| **Integration layer**          | Sends one event per member action with a deterministic `eventId`; treats a duplicate as already processed                                                                                                                                                                                                                                |
| **Website / app**              | Reports the action; validates codes in real time if your system owns them                                                                                                                                                                                                                                                                |
| **CRM / marketing automation** | Receives campaign effects and balance changes through webhooks                                                                                                                                                                                                                                                                           |

## Design decisions

| Decision                         | Options                                                          | Recommendation                                                                                                                                                 |
| -------------------------------- | ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event types                      | One generic type with a `kind` attribute, or one type per action | One type per action (`article_read`, `device_registration`, `newsletter_opt_in`). Campaigns, challenges and reports stay readable.                             |
| Attributes                       | Only an ID, or everything a rule might use                       | Send what rules filter on (category, brand, product, channel). An attribute that isn't in the event can't be used later.                                       |
| `eventId`                        | Random, or derived from the action                               | Derived, so the same action always has the same ID — see below.                                                                                                |
| Who validates codes              | Your system, or an Open Loyalty redemption code campaign         | Your system if codes already live there or the member must see "used" or "invalid" immediately. Open Loyalty if you want it to generate or hold the code pool. |
| One reward per action, or limits | Per event, or capped per member and period                       | Use campaign limits for caps (e.g. one reward per article, five codes per month).                                                                              |

## Recommended flow

{% stepper %}
{% step %}

### Configure (Admin Panel)

Create a schema for each event type. Add custom event campaigns or challenges that react to the type and its attributes, with limits for anything that can be repeated.
{% endstep %}

{% step %}

### Send the event

`POST /api/{storeCode}/customEvent` with `type`, `eventDate`, the member identifier in `customerData` (e.g. `loyaltyCardNumber`), the attributes in `body`, and an `eventId`.
{% endstep %}

{% step %}

### Make it idempotent

`eventId` is optional in the API but unique per tenant when sent. Build it from the action itself, so a retry or a repeated click produces the same ID:

| Action              | `eventId`                             |
| ------------------- | ------------------------------------- |
| Article read        | `{customer ID}_ARTICLE_{article key}` |
| Newsletter opt-in   | `{customer ID}_NEWSLETTER_{list}`     |
| Device registration | `DEVREG_{device serial}`              |
| Code entry          | the code, or your system's scan ID    |

A second event with the same `eventId` is rejected with `400` "Custom Event with such event id already exists" — treat it as already processed, not as a failure.
{% endstep %}

{% step %}

### Handle codes

If your system owns the codes, validate them in real time, mark them used, and send events only for valid codes (with the code as `eventId`). If Open Loyalty owns them, send the entered code in the schema's code attribute and let a redemption code campaign check it against its pool.
{% endstep %}

{% step %}

### Tell the member

Subscribe to `CampaignEffectWasApplied` and `WalletBalanceUpdated` to message the member or update CRM. If an event awards a fortune wheel spin instead of points, it still has to be drawn — see [fortune wheels](https://help.openloyalty.io/gamification/fortune-wheels).
{% endstep %}
{% endstepper %}

## Sequence diagrams

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-a9ff5e254809383b7a02002ae1b389cf23e16c5e%2Fig-custom-events-engagement.png?alt=media" alt="The website or app reports a completed member action. The integration layer builds a deterministic eventId and sends a custom event with type, eventId, event date, loyalty card number and body. Open Loyalty matches the member and runs custom event campaigns and challenges, returns the customEventId and sends CampaignEffectWasApplied and WalletBalanceUpdated webhooks, passed on to CRM. Sending the same eventId again returns 400 because it was already processed." width="647"><figcaption><p>Member action</p></figcaption></figure>

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-3924703ffdf3faa00d07ccdb8e2f657ed364e892%2Fig-custom-events-codes.png?alt=media" alt="A member enters or scans a code. Either the integration layer validates the code in your system, shows valid, used or invalid at once, and sends a custom event only for valid codes with the code as eventId; or it sends the entered code to Open Loyalty, where a redemption code campaign checks it against its pool, marks it used and awards the member." width="643"><figcaption><p>Code entry: validated in your system or in Open Loyalty</p></figcaption></figure>

## Go-live checklist

### Admin Panel

* [ ] Every event type has a schema with the attributes its rules use.
* [ ] Every campaign or challenge on a repeatable action has a limit.
* [ ] For Open Loyalty-managed codes, the redemption code campaign has its code pool loaded.

### Integration layer

* [ ] Every event carries a deterministic `eventId`.
* [ ] A duplicate-`eventId` `400` is treated as already processed; other `400`s are logged and fixed.
* [ ] `eventDate` is the time of the action, with timezone — not the time it was sent.
* [ ] Failed events are logged with their payload and retried with backoff.

### Website / app

* [ ] Code entry tells the member immediately whether a code is valid, used or invalid.
* [ ] The member sees the reward through the balance, history or a message — not a guess made by the front end.

### Validation

* [ ] Each event type awards what its campaign says.
* [ ] Sending the same event twice rewards once.
* [ ] Limits stop rewards once reached.
* [ ] An event for an unknown member is logged and investigated.

## Key endpoints

* `POST /api/{storeCode}/customEvent` — [Add a custom event](https://help.openloyalty.io/api-reference/custom-event/add-a-custom-event)
* `GET /api/{storeCode}/customEvent` — [Get custom events list](https://help.openloyalty.io/api-reference/custom-event/get-custom-events-list), filtered e.g. by `customerData:loyaltyCardNumber`

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

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

* Sending events without `eventId`: a retry after a timeout rewards the member twice.
* A random `eventId` per attempt: same problem, with a different ID each time.
* One generic event type for everything: rules, challenges and reports become hard to read and change.
* Leaving out an attribute because no rule uses it yet: future campaigns can't target it for past events.
  {% 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/custom-events.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.
