Loyalty overview

Keebai Loyalty runs the reward program behind your counter: a customer enrolls, earns points or stamps, redeems them, and carries the card in Apple Wallet or Google Wallet — where you can update the balance and push a message without an app. The API covers the operational half of that. Your point of sale accrues, your backend redeems, and your automation issues the card. Designing the program and the card stays in the Keebai portal.

The data model

Program

The rules. One of three kinds — points, stamps, or tiers — and only the matching rule set is populated.

Membership

One customer inside one program. Carries the balance, the stamp count, the tier, and the serial number the wallet card is keyed by.

Ledger entry

One movement: an accrual, a redemption, or a correction. Records the balance it resulted in.

Wallet template

The card design for a program — colours, fields, barcode. Versioned, and one version is published.

A program has many memberships and many template versions. A membership has many ledger entries and up to two passes, one per wallet platform.

The three program types

Type	What accrues	Typical shape
`points`	`balance_points`, by an amount you choose per movement	Spend-based: your POS converts a purchase into points.
`stamps`	`stamps_count`, normally one at a time	Coffee-card: ten stamps, one free. `rules.stamps.reward` describes the prize.
`tiers`	`balance_points`, plus a `tier` recomputed against the thresholds	Loyalty levels: bronze, silver, gold.

The program decides which metric a movement touches. You never pass a metric — POST .../ledger on a stamps program moves stamps, on a points program moves points.

There is no reward or redemption entity. A reward is a free-text string in rules.stamps.reward, and a redemption is a ledger entry with kind: "redeem" — nothing links it to a specific item, and nothing checks that the balance covers it. A redemption larger than the balance clamps to zero rather than failing.If you need a prize catalogue, a redemption code, or a rule that blocks an unaffordable redemption, build it on your side and use the ledger as the accounting record.

What the API does and does not do

Available	Portal only
Read programs and wallet templates	Creating and editing programs
List, read and enroll memberships	Designing and publishing wallet templates
Read and record ledger movements	Bulk-importing memberships from a spreadsheet
Issue wallet passes, notify, read the history	Uploading card branding images

Writes are deliberately narrow. Everything the API can write is something a system does many times a day; everything it cannot is something a person configures once.

Endpoints

Programs and templates

Method	Path	Scope	Description
`GET`	`/v1/loyalty/programs`	`loyalty:read`	List programs, filterable by status and type.
`GET`	`/v1/loyalty/programs/{id}`	`loyalty:read`	Get one program with its rules.
`GET`	`/v1/loyalty/templates`	`loyalty:read`	List a program’s card designs.
`GET`	`/v1/loyalty/templates/{id}`	`loyalty:read`	Get one template.

Memberships and ledger

Method	Path	Scope	Description
`GET`	`/v1/loyalty/memberships`	`loyalty:read`	List memberships by program, customer, phone, name, or status.
`GET`	`/v1/loyalty/memberships/{id}`	`loyalty:read`	Get one membership with its balance.
`POST`	`/v1/loyalty/memberships`	`loyalty:write`	Enroll a customer.
`GET`	`/v1/loyalty/memberships/{id}/ledger`	`loyalty:read`	List movements.
`POST`	`/v1/loyalty/memberships/{id}/ledger`	`loyalty:write`	Record a movement.

Wallet passes

Method	Path	Scope	Description
`POST`	`/v1/loyalty/memberships/{id}/passes/google`	`loyalty:write`	Issue the Google Wallet pass.
`POST`	`/v1/loyalty/memberships/{id}/passes/apple/link`	`loyalty:write`	Issue the Apple Wallet download link.
`POST`	`/v1/loyalty/memberships/{id}/passes/notify`	`loyalty:write`	Push a message to the card.
`GET`	`/v1/loyalty/memberships/{id}/passes/notifications`	`loyalty:read`	Message history.

A full round trip

Enroll a customer, give them the card, and start accruing.

TOKEN="kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# 1. Find the program
curl -s "https://api.keebai.com/v1/loyalty/programs?status=active" \
  -H "Authorization: Bearer $TOKEN"

# 2. Enroll the customer — customer.id is YOUR identifier for them
curl -s -X POST https://api.keebai.com/v1/loyalty/memberships \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "program_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "customer": { "id": "pos-8842", "name": "Camila Rojas", "phone": "+56912345678" }
  }'

# 3. Give them the wallet card
curl -s -X POST https://api.keebai.com/v1/loyalty/memberships/6650aaaa1111bbbb2222cccc/passes/google \
  -H "Authorization: Bearer $TOKEN"

# 4. Accrue on every purchase
curl -s -X POST https://api.keebai.com/v1/loyalty/memberships/6650aaaa1111bbbb2222cccc/ledger \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "kind": "earn", "amount": 120, "source": "pos", "ref": "receipt-99120" }'

The card in the customer’s pocket updates on step 4 on its own. You do not push anything.

The customer identifier is yours

customer.id is a free-text string that you choose. It is not a Keebai contact id, not a CRM customer id, and nothing validates that it points at anything. Whatever you send at enrollment is copied into the membership and never resolved again. Rename the customer in your CRM and the membership keeps the old name until you enroll them somewhere new.

Pick something stable and reproducible — your POS customer id, your CRM primary key. It is the value you will pass to customer_id to find the membership again, and it is what makes enrollment idempotent: a second enrollment with the same customer.id in the same program returns 409 instead of creating a duplicate.

If you would rather look people up by phone, that works too: GET /v1/loyalty/memberships?phone=912345678 matches on a digit subsequence, so a stored +56 9 1234 5678 is found without you normalising anything.

Balances are a projection

The stored balance on a membership is maintained as movements happen; it is not summed from the ledger on read. Two consequences matter:

Serialise your movements per membership. Two accruals fired concurrently against the same membership can lose one of them. Queue them, or accrue once per transaction rather than once per line item.

Point expiry is a read-time view, not a movement. When a program sets rules.points.expiration_days and the window since enrolled_at has passed, GET on the membership reports balance_points: 0 — but no ledger entry is written and the stored balance is untouched. If that customer then earns points, the new balance continues from the old stored value, not from zero. The ledger’s balance_after is the honest number; the membership’s balance_points is the displayed one.

Scoping

Loyalty is company-wide. No loyalty record carries a project, so every read and write covers your whole company regardless of which project the token was minted for. Same behaviour as CRM reads, and unlike messaging, where writes stay inside the token’s project. The loyalty feature flag gates the portal, not the API. A company without loyalty enabled that calls with a scoped token gets empty lists, not a 403.

Identifiers

Three id spaces, only one of which is yours:

Id	Format	Owner
Program, template, membership `_id`	MongoDB `ObjectId`, 24 hex chars	Keebai
`customer.id` / `customer_id`	Any string you choose	You
Pass object / serial	Google or Apple’s own format	The wallet provider

company is derived from your token and must never be sent — it returns 400.

Errors

{
  "error": {
    "code": "INSUFFICIENT_SCOPE",
    "message": "Forbidden",
    "details": {
      "required": ["loyalty:write"],
      "missing": ["loyalty:write"]
    }
  }
}

Status	When
`400`	Invalid body, a movement that would drive the balance negative, or a property the endpoint does not accept.
`401`	Missing, invalid, revoked, or expired token.
`403`	The token lacks `loyalty:read` or `loyalty:write`.
`404`	The program, membership, or template does not exist, or belongs to another company.
`409`	The customer is already enrolled in that program.
`429`	You hit a rate limit.
`502`	The loyalty service is unreachable. Retry with backoff.

Branch on error.code, never on the message text.

409 on enroll is the happy path for a retry. It means the membership already exists, which is exactly what you wanted. Catch it, then GET /v1/loyalty/memberships?customer_id=<yours> to fetch the one that is already there rather than treating it as a failure.

Rate limits

Loyalty shares the per-project quota: 1,000 requests a day across the whole public API. A POS that accrues on every sale is the workload to size for. One sale is one POST .../ledger — a store doing 300 transactions a day spends a third of the quota on loyalty alone, before anything else your integration does.

Accrue once per transaction

Not once per line item. It is also the only way to stay safe against the concurrency caveat above.

Cache programs and templates

They are authored in the portal and change rarely. Fetch at boot, not per sale.

Skip the balance read

The response to a ledger write already carries balance_after. A follow-up GET on the membership is a wasted request.

Own project for the POS

The quota is per project, so a busy till cannot starve your transactional path if it lives in its own.

Next steps

Enroll a customer

The first write you will make.

Record a movement

Accrue, redeem, and correct.

Issue a wallet pass

Put the card on the customer’s phone.

Scopes

loyalty:read and loyalty:write.

Get started

Programs

Templates

Memberships

Ledger

Wallet passes

Loyalty overview

The data model

Program

Membership

Ledger entry

Wallet template

The three program types

What the API does and does not do

Endpoints

Programs and templates

Memberships and ledger

Wallet passes

A full round trip

The customer identifier is yours

Balances are a projection

Scoping

Identifiers

Errors

Rate limits

Accrue once per transaction

Cache programs and templates

Skip the balance read

Own project for the POS

Next steps

Enroll a customer

Record a movement

Issue a wallet pass

Scopes

​The data model

Program

Membership

Ledger entry

Wallet template

​The three program types

​What the API does and does not do

​Endpoints

​Programs and templates

​Memberships and ledger

​Wallet passes

​A full round trip

​The customer identifier is yours

​Balances are a projection

​Scoping

​Identifiers

​Errors

​Rate limits

Accrue once per transaction

Cache programs and templates

Skip the balance read

Own project for the POS

​Next steps

Enroll a customer

Record a movement

Issue a wallet pass

Scopes

The data model

The three program types

What the API does and does not do

Endpoints

Programs and templates

Memberships and ledger

Wallet passes

A full round trip

The customer identifier is yours

Balances are a projection

Scoping

Identifiers

Errors

Rate limits

Next steps