Create a customer - BrandWallet

POST $BASE_URL/v1/customers

Creates a bare customer — no card, barcode, or loyalty balances are created. To attach the customer to a campaign, use POST /v1/customers/register.

Auth: Authorization: Bearer <accessToken> — an organization-scoped token from Authentication. Missing or invalid token returns 401; an organization without an active subscription returns invalid_subscription (403).

Payload schema:

{
  "data": {                             // required — free-form customer profile
    "phone": "+905551234567",
    "email": "jane@example.com",
    "fullname": "Jane Doe"
  },
  "metaData": { "source": "pos" },      // optional
  "consents": { "marketing": true | false },  // optional
  "opaqueId": "ext-cust-10432"          // optional — your own customer id
}

Body

Field	Type	Description
`data`	object	Required. Free-form customer profile; stored as-is. `phone` and `email` are validated when present.
`data.phone`	string	Optional. Normalized to E.164 (`0555 123 45 67` → `+905551234567`); numbers without a country code default to TR, so send non-Turkish numbers with a leading `+`. Unparseable numbers return `invalid_phone` (400). Unique within the organization — `existing_customer_with_phone` (400) on conflict.
`data.email`	string	Optional. Unique within the organization — `existing_customer_with_email` (400) on conflict.
`metaData`	object	Optional. Free-form metadata; stored as-is.
`consents`	object	Optional. Consent flags; stored as-is.
`opaqueId`	string	Optional. Your own system’s customer id. Unique within the organization — `opaque_id_already_exists` (400) on conflict.

Uniqueness checks ignore deleted customers. When email or phone hits an existing customer, look the customer up with GET /v1/customers/find and pass their id to POST /v1/customers/register as customer.id.

Example

curl --request POST \
  --url "$BASE_URL/v1/customers" \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "data": { "phone": "+905551234567", "fullname": "Jane Doe" },
    "opaqueId": "ext-cust-10432"
  }'

Response

Returns 201 with the bare customer — cards is always empty and collectables is not present.

{
  "id": "9b2f6c1e-3d4a-4f8b-9c0d-7e5a1b2c3d4e",
  "data": {
    "phone": "+905551234567",
    "fullname": "Jane Doe"
  },
  "opaqueId": "ext-cust-10432",
  "status": 1,
  "createdAt": "2026-09-29T08:22:52.795Z",
  "updatedAt": "2026-09-29T08:22:52.795Z",
  "cards": []
}

Notes:

Optional fields that have no value are omitted from the response — you will not receive null. Exception: opaqueId is null when not assigned.
data.phone is always returned in its normalized (E.164) form — the raw format you sent is not stored.
A bare customer cannot take part in transactions (they have no card). Register them into a campaign first — the card, barcode, and loyalty balances are created at that step.

Last modified on September 29, 2026