> For the complete documentation index, see [llms.txt](https://docs.hos.accessacloud.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hos.accessacloud.com/atreemo-api/workflows/customer-and-loyalty.md).

# Customer and loyalty

Source-backed synthetic customer resolution and loyalty read workflow

{% hint style="warning" %}
**Illustrative workflow — not executed.** Use only an owner-approved instance, identities and synthetic records. This guide does not authorise customer-data access, loyalty changes or production calls.
{% endhint %}

## Goal

Resolve the intended customer in an authorised brand context, then retrieve loyalty information. Do not select the first match blindly or treat a valid token as access to every method, brand or customer.

### 1. Establish caller and brand

Obtain a native token using [Authentication](broken://pages/a92d1423ae54b22743d71e7ab5277f8258a1d52c). Where relevant, `GET /api/User/GetAllowedBrands` returns brands for the authenticated caller. A no-brand configuration is not necessarily a successful empty list; source can return a business error (`UserController.cs:1110–1135`).

Method permission and brand access are separate; see [Permissions](broken://pages/6069938d54cc2d7cacd1a7ecf3fef94e5360c6be).

### 2. Resolve a customer narrowly

`POST /api/Customer/FindCustomerDetails` requires `SearchFilters`.

```json
{
  "BrandID": 1,
  "SearchFilters": {
    "Email": "customer@example.com"
  }
}
```

This is synthetic. Source describes AND between criteria. The action checks brand permission and rejects more than 10 matches rather than returning the first page of an unlimited search. No matches and too many matches have distinct business errors. Optional `ResponseFilters` should be used to minimise collected data (`CustomerController.cs:125–219`).

Check `ResponseStatus` and `Errors` before consuming `ResponseData`. Choose the intended `CtcID` using agreed business identifiers; do not create or reuse a customer silently when the lookup is ambiguous. `CtcID` is a customer/contact identity and is not the authenticated `UserID`.

### 3. Read loyalty points

The following uses the Staging resource base:

```shell
curl "https://api-staging.hos.accessacloud.com/atreemo-api/api/LoyaltyPoint/Get?CtcID=1&BrandID=1" \
  -H "Authorization: Bearer <synthetic-access-token>" \
  -H "Accept: application/json"
```

```json
{
  "ResponseData": {
    "LoyaltyPointsBalance": 12.5,
    "CurrentTiersName": "Synthetic tier"
  },
  "ResponseStatus": true,
  "Errors": []
}
```

The balance is not assumed to be an integer or currency. Tier names are instance data. `CtcID` is required. Published material calls `BrandID` optional, but the nullable source parameter has no default; this conflict requires target validation (`LoyaltyPoint.cs:22–29`). The same caveat applies to related LoyaltyPoint and LoyaltyProgram calls.

### 4. Preserve identity and failure handling

Source warns that contacts can be merged (`Models/Customer.cs:642–647`). Agree how to re-resolve identity after merges rather than assuming a cached numeric ID permanently identifies the current record.

On failure, do not use a default, previous customer or brand. Check HTTP status and business errors separately. `ResponseStatus: false` is not a zero balance. Do not log full customer payloads or bearer tokens.

## Writes require separate approval

`Loyalty/EarnFromReceipt` can process receipts/transactions and `Visit/PostVisit` can apply loyalty rules and triggers. They are not connectivity checks and generic retries can duplicate business effects (`LoyaltyController.cs:1963–2104`, `VisitController.cs:80–258`). Agree fixtures, effects, duplicate handling, cleanup and rollback under [Testing and support](broken://pages/4ebb976c2c8353fb6080a8cf9f615312b52d4144).

All citations refer to source commit `ea9cb106e13aa4b9b92c01d090118742b44dd470`. The 1.34-derived contract remains unvalidated against the current non-production Release1.35 environment.


---

# 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://docs.hos.accessacloud.com/atreemo-api/workflows/customer-and-loyalty.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.