> 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/plan-and-foundations/member-identity.md).

# Member Identity

Choosing how members are identified across your systems and Open Loyalty, and the rules for reading and updating member profiles safely.

Every transaction, custom event and redemption has to land on the right member. Decide early which identifier your systems share with Open Loyalty — changing it after go-live means migrating every integration.

## The identifiers

| Identifier          | Set by                                                                                           | Notes                                                     |
| ------------------- | ------------------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| `customerId`        | Open Loyalty                                                                                     | UUID generated when the member is created. Never changes. |
| `loyaltyCardNumber` | You (or [autogenerated](https://help.openloyalty.io/members-and-activity/members/configuration)) | Free-form text. Usually your own customer ID.             |
| `email`             | You                                                                                              | Can change over the member's lifetime.                    |
| `phone`             | You                                                                                              | Can change over the member's lifetime.                    |

In the Admin Panel's [member configuration](https://help.openloyalty.io/members-and-activity/members/configuration), each of `email`, `phone` and `loyaltyCardNumber` can be **required** at registration, **unique** in the tenant, and used for **event matching** (finding the member a transaction or custom event belongs to). Only unique identifiers can be used for matching, and an identifier set to non-unique can't be switched back. The configuration is per tenant.

## Recommendation: your customer ID as the loyalty card number

For most programmes, store the ID your own customer system already uses (e-commerce customer ID, CRM contact ID) as `loyaltyCardNumber`, and make it **required, unique and used for event matching**.

* Every system already knows it, so the integration layer doesn't need a lookup table.
* Unlike email or phone, it doesn't change when the member updates their profile.
* Member endpoints accept it directly in the path, so you rarely need the `customerId`.

If members join in several channels before they have a customer ID, make sure one system issues the ID at registration and the others receive it.

## Using the identifier in the API

Member endpoints take the member as `{member}` in the path, as the UUID or as `identifier=value`:

```
GET /api/{storeCode}/member/loyaltyCardNumber=100234567
GET /api/{storeCode}/member/loyaltyCardNumber=100234567/wallet
GET /api/{storeCode}/member/email=jane@example.com
GET /api/{storeCode}/member/3f1c8a52-…            (customerId)
```

* The `identifier=` prefix is required — a bare value in the path returns `404`, and so does an unknown member.
* List endpoints filter by the identifier instead, e.g. `customerData:loyaltyCardNumber=` on transactions, custom events and redemptions.
* A few calls take the `customerId` in the request body. Read it once from `GET /member/loyaltyCardNumber=…` and cache it with the member.

## Updating a profile: GET, merge, PUT

`PUT /member/{member}` replaces the whole profile, **including its labels**. A PUT built only from the fields your system knows removes everything else — for example the labels that make a member eligible for campaigns.

{% stepper %}
{% step %}

### Read

`GET /api/{storeCode}/member/{member}` to load the current profile.
{% endstep %}

{% step %}

### Merge

Apply your change to that profile in the integration layer. Remove read-only fields that the PUT doesn't accept.
{% endstep %}

{% step %}

### Write

`PUT /api/{storeCode}/member/{member}` with the full, merged profile.
{% endstep %}
{% endstepper %}

To change only labels or custom fields, use `PATCH /api/{storeCode}/member/{member}` instead — it updates just what you send.

{% hint style="warning" %}
If a change made in your system comes back to it through a webhook, mark where each update came from (e.g. a `source` custom field) so your integration doesn't send it back to Open Loyalty in a loop.
{% endhint %}

## Checklist

* [ ] One identifier is shared by every system and set as required, unique and used for event matching.
* [ ] The integration layer always addresses members as `identifier=value` or by `customerId`.
* [ ] Every profile update reads, merges and writes the full profile, or uses PATCH for labels and custom fields.
* [ ] Updates echoed back through webhooks are recognised and not re-sent.
* [ ] It's agreed what happens when a member deletes their account and later re-joins (same or new identifier).

## Key endpoints

* `POST /api/{storeCode}/member` — [Add a member](https://help.openloyalty.io/api-reference/member/add-a-member)
* `GET /api/{storeCode}/member/{member}` — [Get member's details](https://help.openloyalty.io/api-reference/member/get-members-details)
* `PUT /api/{storeCode}/member/{member}` — [Update member's details](https://help.openloyalty.io/api-reference/member/update-members-details)
* `PATCH /api/{storeCode}/member/{member}` — [Partially update member details](https://help.openloyalty.io/api-reference/member/partially-update-member-details)


---

# 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/plan-and-foundations/member-identity.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.
