Register a customer

POST $BASE_URL/v1/customers/register

Registers a customer into a campaign: opens a wallet card (with barcode) and initializes the campaign’s loyalty balances. customer takes two forms: pass a customer id as a string to register an existing customer, or pass an object to create the customer and register them in one step. The returned cards[].id is used directly as card on POST /v1/transactions/process.

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 — existing-customer mode (customer is the customer’s id):

{
  "campaignId": "14c5a0ed-537e-400c-8463-e72bf277f600",  // required — the campaign to register into
  "customer": "9b2f6c1e-3d4a-4f8b-9c0d-7e5a1b2c3d4e"     // the existing customer's id
}

New-customer mode (customer is a create model):

{
  "campaignId": "14c5a0ed-537e-400c-8463-e72bf277f600",
  "customer": {
    "data": {                                            // required — same model as Create
      "phone": "+905551234567",
      "email": "jane@example.com",
      "fullname": "Jane Doe"
    },
    "metaData": { "source": "pos" },                     // optional
    "consents": { "marketing": true | false },           // optional
    "opaqueId": "ext-cust-10432"                         // optional
  }
}

Body

Field	Type	Description
`campaignId`	string	Required. The campaign to register the customer into (provided during onboarding, or from your campaign setup). Returns `invalid_campaign` (400) when no published campaign matches.
`customer`	string \| object	Required. String: the id of an existing customer — the customer is registered into the campaign and their profile is not modified; returns `customer_not_found` (400) when the id does not match a customer of your organization. Object: a create model — a new customer is created and registered. Any other value returns `invalid_customer_payload` (400).
`customer.data`	object	Required in object mode (otherwise `customer_data_required`, 400). Same model and validations as Create — `invalid_phone`, `existing_customer_with_email`, `existing_customer_with_phone`, `opaque_id_already_exists` (all 400).
`customer.metaData` / `customer.consents` / `customer.opaqueId`	—	Optional in object mode, same as Create.

An id field inside the customer object is NOT accepted — it returns customer_id_must_be_string (400). To register an existing customer, send customer as a string.

Registering the same customer into the same campaign twice is idempotent: no error is returned, the customer’s existing card comes back, and nothing changes. Registration never resets existing loyalty balances — only missing balances are initialized at 0.

Example

# Register an existing customer — customer is an id (string)
curl --request POST \
  --url "$BASE_URL/v1/customers/register" \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignId": "14c5a0ed-537e-400c-8463-e72bf277f600",
    "customer": "9b2f6c1e-3d4a-4f8b-9c0d-7e5a1b2c3d4e"
  }'

# Create + register in one step — customer is an object
curl --request POST \
  --url "$BASE_URL/v1/customers/register" \
  --header 'Authorization: Bearer <accessToken>' \
  --header 'Content-Type: application/json' \
  --data '{
    "campaignId": "14c5a0ed-537e-400c-8463-e72bf277f600",
    "customer": {
      "data": { "phone": "+905551234567", "fullname": "Jane Doe" },
      "opaqueId": "ext-cust-10432"
    }
  }'

Response

Returns 201 with the registered customer. collectables comes initialized with the campaign’s loyalty balances; cards contains only the card of this registration (use GET /v1/customers/find for all of the customer’s cards).

{
  "id": "9b2f6c1e-3d4a-4f8b-9c0d-7e5a1b2c3d4e",
  "data": {
    "phone": "+905551234567",
    "fullname": "Jane Doe"
  },
  "collectables": {
    "stamp_K3M9A": { "value": 0, "total": 0 }
  },
  "opaqueId": "ext-cust-10432",
  "status": 1,
  "createdAt": "2026-09-29T08:22:52.795Z",
  "updatedAt": "2026-09-29T08:23:05.079Z",
  "cards": [
    {
      "id": "6f1d2c88-9a41-4b7e-8d02-3c5a71e9f604",
      "barcode": "681738",
      "status": 1
    }
  ]
}

Notes:

Optional fields that have no value are omitted from the response — you will not receive null. Exception: opaqueId is null when not assigned.
In new-customer mode, data.phone is returned in its normalized (E.164) form.
Every new card gets its own barcode — a customer’s cards from different campaigns have different barcodes. cards[].barcode (a string) can be used to look the customer up at checkout via GET /v1/customers/find.
In new-customer mode, if a validation error occurs before the card is opened, the customer is not created either — no partial records are left behind.

Getting started

Endpoints

Reference

Body

Example

Response

​Body

​Example

​Response

Body

Example

Response