Skip to main content
POST
Inscribir un cliente en un programa
Enrolls a customer into a program. The response carries the _id you will use for every subsequent movement and the serial_number their wallet card is keyed by. Enrollment is where you decide the identity of the customer, and that decision sticks. Read the customer identifier is yours before your first call.

Endpoint

Required scope

loyalty:write

Headers

Body

Example request

Response

201 Created

400 Bad Request

Missing program_id or customer.id, a malformed ObjectId, an invalid email, or a property the endpoint does not accept.

401 Unauthorized

Missing, invalid, revoked, or expired token.

403 Forbidden

The token does not have the loyalty:write scope.

409 Conflict

This customer.id is already enrolled in this program. Fetch the existing membership with GET /v1/loyalty/memberships filtered by customer_id and program_id.

502 Bad Gateway

The loyalty service is unreachable.

Operational notes

  • Enrollment is idempotent by customer.id + program_id. A repeat returns 409 rather than a second membership, so a retry after a timeout is safe: treat 409 as “already done” and read the existing row.
  • The customer details are a snapshot. They are copied at enrollment and never resolved again against your CRM or Keebai contacts. Updating the name afterwards is not possible through the API — the membership keeps what it was created with.
  • A new membership starts empty: zero points, zero stamps, no tier. Enrolling does not grant a welcome bonus; issue an earn movement if you want one.
  • The same customer can hold memberships in several programs. The uniqueness constraint is per program, not per company.
  • Enrolling does not issue a wallet card. Call the Google or Apple pass endpoint afterwards, and note that a published wallet template must exist first.

Authorizations

Authorization
string
header
required

Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.

Body

application/json
program_id
string
required

ObjectId del programa al que se inscribe

customer
object
required

Datos del cliente. Se copian tal cual al inscribir y no se vuelven a resolver contra el CRM

Response

201 - application/json
membership
object
required