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

# Segments

Grouping members with dynamic and static segments, using them to target campaigns and rewards, and keeping audiences in step with CRM.

A segment is a group of members — "bought in the last 30 days", "VIP list from CRM", "lapsed members". Dynamic segments follow rules and update themselves; static segments are a fixed list you upload. Campaigns and rewards use segments to decide who sees and gets what; your CRM can use them as audiences.

For the Admin Panel side, see [Creating segments](https://help.openloyalty.io/members-and-activity/members/segments/creating-segments), [Segment conditions](https://help.openloyalty.io/members-and-activity/members/segments/segment-conditions) and [Managing segments](https://help.openloyalty.io/members-and-activity/members/segments/managing-segments).

## Who does what

| Area                           | Responsibility                                                                                                       |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Admin Panel**                | Dynamic segment conditions; static segment uploads; segment-based visibility and conditions on campaigns and rewards |
| **Integration layer**          | Sends the data conditions depend on; syncs segment members to CRM if needed                                          |
| **CRM / marketing automation** | Supplies lists for static segments; uses segments as audiences                                                       |

## Design decisions

| Decision                 | Options                                                     | Recommendation                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------ | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Who defines the audience | Open Loyalty (dynamic), or CRM (static upload)              | Dynamic for behaviour Open Loyalty sees (purchases, events, tier); static for decisions made elsewhere (a hand-picked VIP list, a CRM model's output).                                                                                                                                                                                                                                                                                                                                                                      |
| Segment, tier or label   | Segment, tier, or a member label                            | Tiers for the programme's levels; labels for flags your systems set directly (opt-ins, brand); segments for everything derived from behaviour.                                                                                                                                                                                                                                                                                                                                                                              |
| Freshness                | Real-time, or eventual                                      | Dynamic segments recalculate **every 10 minutes** and after editing. Segments built **only** from the custom attribute conditions (*Members with custom attribute*, *Members with custom attribute value*) are [live](https://help.openloyalty.io/members-and-activity/members/segments#how-segments-stay-up-to-date) and update within seconds — so a flag your systems set becomes an audience almost at once. A rule that must react instantly to a purchase belongs in the campaign's own conditions, not in a segment. |
| Conditions               | Many narrow segments, or a few broad ones combined in rules | A few reusable segments; combine them with campaign conditions.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Recommended flow

{% stepper %}
{% step %}

### Make sure the data is there

Segment conditions read the member profile, transactions, custom events, tier and custom attributes. Check the integration sends every field a condition needs (e.g. channel on transactions, country on the profile).
{% endstep %}

{% step %}

### Create the segments

Create dynamic segments with their conditions (AND or OR) and activate them. For static segments, export the list from your source system and upload it in the Admin Panel.
{% endstep %}

{% step %}

### Use them in rules

Set campaign and reward visibility or conditions to the segment. Remember the up-to-10-minute delay when a member's behaviour moves them into a segment; live segments (custom attribute conditions only) follow within seconds.
{% endstep %}

{% step %}

### Sync to CRM, if needed

Read members with `GET /api/{storeCode}/segment/{segment}/members` (paged) to build a CRM audience, and remove members on the `SegmentMembershipDropped` webhook. Before changing or deleting a segment, check what uses it with `GET /api/{storeCode}/segment/{segment}/association/{resourceName}`.
{% endstep %}
{% endstepper %}

## Sequence diagram

<figure><img src="https://226878483-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FZ4Fuoa1PTF0DrNTgjzJu%2Fuploads%2Fgit-blob-97ea8c244a550834cc454840efd6bbbb9d6720ae%2Fig-segments-flow.png?alt=media" alt="Dynamic segment: conditions on profile, purchases, events and tier, recalculated every 10 minutes and after editing, used directly by campaigns and rewards for visibility and conditions. Static segment: an admin uploads a member list exported from CRM as a CSV in the Admin Panel, and members stay fixed until the next upload. Using segments outside Open Loyalty: the integration layer reads the segment&#x27;s members page by page and syncs the audience to CRM, and removes a member when a SegmentMembershipDropped webhook arrives." width="686"><figcaption><p>Dynamic and static segments, and syncing to CRM</p></figcaption></figure>

## Go-live checklist

### Admin Panel

* [ ] Every segment used by a campaign or reward is active and has the expected member count.
* [ ] Static segments have been uploaded from the agreed source list.

### Integration layer

* [ ] Every field a segment condition uses is sent by the integration.
* [ ] CRM audiences built from segments are refreshed and shrink on `SegmentMembershipDropped`.

### Validation

* [ ] A test member who meets a dynamic segment's conditions appears in it within 10 minutes (within seconds for a live segment).
* [ ] A campaign limited to a segment rewards members inside it and ignores those outside.
* [ ] Changing a segment's conditions doesn't break the campaigns that use it.

## Key endpoints

* `GET /api/{storeCode}/segment` — [Get segments lists](https://help.openloyalty.io/api-reference/segment/get-segments-lists)
* `GET /api/{storeCode}/segment/{segment}/members` — [Get segment's members](https://help.openloyalty.io/api-reference/segment/get-segments-members)
* `GET /api/{storeCode}/segment/{segment}/association/{resourceName}` — [Get resources associated with segment](https://help.openloyalty.io/api-reference/segment/get-resources-associated-with-segment)

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

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

* Using a segment for a decision that must be instant — membership can lag by up to 10 minutes, unless the segment is live.
* Planning to tweak a live segment's conditions later — they can't be changed; create a new segment and repoint the campaigns and rewards that use it.
* A segment condition on a field the integration never sends: the segment stays empty.
* Deactivating or editing a segment that live campaigns depend on.
* Keeping a static segment that nobody refreshes.
  {% 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/segments.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.
