The Customer Object

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. All customer endpoints return the same core record; cards and coupons are attached only where noted. Object schema:

{
  "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, 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.
`consents`	object	Consent flags; merged on update.
`cards`	array	The customer’s wallet cards — `{id, barcode, status}` on register, enriched with `name` and `campaigns` (campaign configuration) on find. Not included in list and update responses.
`coupons` / `tags` / `categories`	—	Returned by find 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. 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.

Getting started

Endpoints

Reference

Fields

​Fields

Fields