> ## Documentation Index
> Fetch the complete documentation index at: https://docs.brand-wallet.com/llms.txt
> Use this file to discover all available pages before exploring further.

# The Customer Object

> The shape of a BrandWallet customer record as returned by the customer endpoints.

**A customer is an end consumer of a merchant organization — the person who shops at the brand, carries its wallet card (QR code), and collects loyalty rewards. Customers are not the organization's staff: the team members who operate the business (owners, managers, cashiers) are [Users](/api/user-object). All customer endpoints return the same core record; `cards` and `coupons` are attached only where noted.**

Object schema:

```json theme={null}
{
  "id": "9c2f1a34-6b8e-4f02-a1d3-5e7c90b4d812",
  "data": { "fullname": "…", "phone": "…", "email": "…" },   // free-form profile
  "collectables": {                                          // loyalty balances, keyed by collectable key
    "point_A1B2C": {
      "label": "Points",
      "value": 120,          // spendable balance
      "total": 350,          // lifetime collected
      "tierLevel": 1,        // tiered campaigns only
      "tierStartedAt": "…",  // tiered campaigns only
      "totalAmount": 3200    // tracked counter(s), when present
    }
  },
  "metaData": { },                                           // free-form metadata
  "consents": { "marketing": true | false },
  "cards": [ { "id": "…", "barcode": "…", "status": 1 } ],   // register/find only
  "tags": [ { "id": "…", "name": "…", "color": "…" } ],      // find only
  "categories": [ ],                                         // find only
  "coupons": [ ],                                            // find only
  "opaqueId": "ext-cust-10432" | null,
  "isVoided": true | false,                                  // present when the customer was ever voided
  "status": 1,
  "createdAt": "2026-08-25T14:03:11.000Z",
  "updatedAt": "2026-08-27T09:12:40.000Z"
}
```

### Fields

| Field | Type | Description |
| - | - | - |
| `id` | string | Unique customer id. Used on all customer, coupon, and transaction endpoints. |
| `data` | object | Free-form profile (`fullname`, `phone`, `email`, ...); keys depend on the organization's customer form. `phone` is always stored in E.164 form. |
| `collectables` | object | Loyalty balances keyed by collectable key. Each entry has `value` (spendable) and `total` (lifetime); on [find](/api/find-customer), also a `label`, plus tier state (`tierLevel`, `tierStartedAt`) and tracked counters (e.g. `totalAmount`) when the campaign is tiered. |
| `metaData` | object | Free-form metadata; replaced as a whole on [update](/api/update-customer). |
| `consents` | object | Consent flags; merged on [update](/api/update-customer). |
| `cards` | array | The customer's wallet cards — `{id, barcode, status}` on [register](/api/register-customer), enriched with `name` and `campaigns` (campaign configuration) on [find](/api/find-customer). Not included in [list](/api/list-customers) and update responses. |
| `coupons` / `tags` / `categories` | — | Returned by [find](/api/find-customer) only. |
| `opaqueId` | string \| null | Your own system's customer id; unique within the organization. `null` when not assigned. |
| `isVoided` | boolean | `true` while the customer is blocked from transactions — see [void / activate](/api/void-customer). Omitted when never voided. |
| `status` | number | Record status code (`1` = active). |
| `createdAt` / `updatedAt` | string | ISO 8601 timestamps. |

Notes:

* Optional fields that have no value are omitted from responses — you will not receive `null` (the single exception is `opaqueId`).
* Dynamic-keyed objects (`data`, `metaData`, `collectables` keys) pass through as-is; do not assume a fixed key set.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.