Inscribir un cliente en un programa
Memberships
POST /v1/loyalty/memberships
Enroll a customer into a loyalty program and get back their membership and wallet serial number.
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
Missingprogram_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 theloyalty:write scope.
409 Conflict
Thiscustomer.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 returns409rather than a second membership, so a retry after a timeout is safe: treat409as “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
earnmovement 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
Personal Access Token con prefijo kbai_pk_. Generar desde el portal con permiso developer.manage_tokens.
Body
application/json
Response
201 - application/json