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. Pass customer.id to register an existing customer, or omit it 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:

{
  "campaignId": "14c5a0ed-537e-400c-8463-e72bf277f600",  // required — the campaign to register into
  "customer": {
    "id": "9b2f6c1e-3d4a-4f8b-9c0d-7e5a1b2c3d4e",       // optional — registers this EXISTING customer; other fields are ignored
    "data": {                                            // required when id is omitted — 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`	object	Required. The customer to register — two modes:
`customer.id`	string	Optional. Existing-customer mode: registers this customer into the campaign; all other `customer` fields are ignored (the profile is not modified). Returns `customer_not_found` (400) when the id does not match a customer of your organization.
`customer.data`	object	Required when `id` is omitted. New-customer mode: 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 new-customer mode, same as Create; ignored in existing-customer mode.

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
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": { "id": "9b2f6c1e-3d4a-4f8b-9c0d-7e5a1b2c3d4e" }
  }'

# Create + register in one step
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