POST /v1/loyalty/memberships/{id}/ledger

Registrar un movimiento de puntos o sellos

curl --request POST \
  --url https://api.keebai.com/v1/loyalty/memberships/{id}/ledger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 120,
  "source": "pos-sucursal-centro",
  "ref": "boleta-99120",
  "note": "Compra de 12.000 en tienda"
}
'

import requests

url = "https://api.keebai.com/v1/loyalty/memberships/{id}/ledger"

payload = {
    "amount": 120,
    "source": "pos-sucursal-centro",
    "ref": "boleta-99120",
    "note": "Compra de 12.000 en tienda"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 120,
    source: 'pos-sucursal-centro',
    ref: 'boleta-99120',
    note: 'Compra de 12.000 en tienda'
  })
};

fetch('https://api.keebai.com/v1/loyalty/memberships/{id}/ledger', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/loyalty/memberships/{id}/ledger",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 120,
    'source' => 'pos-sucursal-centro',
    'ref' => 'boleta-99120',
    'note' => 'Compra de 12.000 en tienda'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/loyalty/memberships/{id}/ledger"

	payload := strings.NewReader("{\n  \"amount\": 120,\n  \"source\": \"pos-sucursal-centro\",\n  \"ref\": \"boleta-99120\",\n  \"note\": \"Compra de 12.000 en tienda\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/loyalty/memberships/{id}/ledger")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 120,\n  \"source\": \"pos-sucursal-centro\",\n  \"ref\": \"boleta-99120\",\n  \"note\": \"Compra de 12.000 en tienda\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/loyalty/memberships/{id}/ledger")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 120,\n  \"source\": \"pos-sucursal-centro\",\n  \"ref\": \"boleta-99120\",\n  \"note\": \"Compra de 12.000 en tienda\"\n}"

response = http.request(request)
puts response.read_body

{
  "entry": {
    "_id": "<string>",
    "membership_id": "<string>",
    "program_id": "<string>",
    "amount": -50,
    "balance_after": 1190,
    "source": "pos-sucursal-centro",
    "ref": "boleta-99120",
    "note": "<string>",
    "created_at": "<string>"
  }
}

POST

loyalty

memberships

{id}

ledger

Registrar un movimiento de puntos o sellos

curl --request POST \
  --url https://api.keebai.com/v1/loyalty/memberships/{id}/ledger \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "amount": 120,
  "source": "pos-sucursal-centro",
  "ref": "boleta-99120",
  "note": "Compra de 12.000 en tienda"
}
'

import requests

url = "https://api.keebai.com/v1/loyalty/memberships/{id}/ledger"

payload = {
    "amount": 120,
    "source": "pos-sucursal-centro",
    "ref": "boleta-99120",
    "note": "Compra de 12.000 en tienda"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    amount: 120,
    source: 'pos-sucursal-centro',
    ref: 'boleta-99120',
    note: 'Compra de 12.000 en tienda'
  })
};

fetch('https://api.keebai.com/v1/loyalty/memberships/{id}/ledger', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.keebai.com/v1/loyalty/memberships/{id}/ledger",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'amount' => 120,
    'source' => 'pos-sucursal-centro',
    'ref' => 'boleta-99120',
    'note' => 'Compra de 12.000 en tienda'
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.keebai.com/v1/loyalty/memberships/{id}/ledger"

	payload := strings.NewReader("{\n  \"amount\": 120,\n  \"source\": \"pos-sucursal-centro\",\n  \"ref\": \"boleta-99120\",\n  \"note\": \"Compra de 12.000 en tienda\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.keebai.com/v1/loyalty/memberships/{id}/ledger")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"amount\": 120,\n  \"source\": \"pos-sucursal-centro\",\n  \"ref\": \"boleta-99120\",\n  \"note\": \"Compra de 12.000 en tienda\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.keebai.com/v1/loyalty/memberships/{id}/ledger")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"amount\": 120,\n  \"source\": \"pos-sucursal-centro\",\n  \"ref\": \"boleta-99120\",\n  \"note\": \"Compra de 12.000 en tienda\"\n}"

response = http.request(request)
puts response.read_body

{
  "entry": {
    "_id": "<string>",
    "membership_id": "<string>",
    "program_id": "<string>",
    "amount": -50,
    "balance_after": 1190,
    "source": "pos-sucursal-centro",
    "ref": "boleta-99120",
    "note": "<string>",
    "created_at": "<string>"
  }
}

Records a movement against a membership. This is the endpoint your point of sale calls: it moves the balance, writes the audit entry, and pushes the new number to the card in the customer’s wallet. Whether the movement touches points or stamps is decided by the program, not by this call. You never pass a metric.

Endpoint

POST https://api.keebai.com/v1/loyalty/memberships/{id}/ledger

Required scope

loyalty:write

Headers

Header	Required	Value
`Authorization`	Yes	`Bearer kbai_pk_<token>`
`Content-Type`	Yes	`application/json`

Path parameters

Parameter	Type	Description
`id`	`string`	The membership `ObjectId`.

Body

Field	Type	Required	Description
`kind`	`string`	Yes	`earn`, `redeem`, or `adjust`.
`amount`	`number`	Yes	Magnitude. For `earn` and `redeem` the absolute value is used; for `adjust` the sign is respected.
`source`	`string`	No	Where the movement came from. Defaults to `manual`. Up to 60 characters.
`ref`	`string`	No	External reference — receipt or order number. Up to 120 characters.
`note`	`string`	No	Free text. Up to 300 characters.

How `kind` maps to the balance

`kind`	`amount` sent	Stored `amount`	Effect
`earn`	`120`	`+120`	Adds.
`earn`	`-120`	`+120`	Adds — the sign is ignored.
`redeem`	`50`	`-50`	Subtracts.
`adjust`	`-30`	`-30`	Subtracts, for corrections.
`adjust`	`30`	`+30`	Adds, for corrections.

Example request

curl -X POST https://api.keebai.com/v1/loyalty/memberships/6650aaaa1111bbbb2222cccc/ledger \
  -H "Authorization: Bearer kbai_pk_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{
    "kind": "earn",
    "amount": 120,
    "source": "pos",
    "ref": "receipt-99120",
    "note": "Purchase of 12,000"
  }'

const response = await fetch(
  "https://api.keebai.com/v1/loyalty/memberships/6650aaaa1111bbbb2222cccc/ledger",
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.KEEBAI_API_TOKEN}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      kind: "earn",
      amount: 120,
      source: "pos",
      ref: "receipt-99120",
    }),
  },
);
const { entry } = await response.json();
console.log(`New balance: ${entry.balance_after}`);

import os, requests

resp = requests.post(
    "https://api.keebai.com/v1/loyalty/memberships/6650aaaa1111bbbb2222cccc/ledger",
    headers={"Authorization": f"Bearer {os.environ['KEEBAI_API_TOKEN']}"},
    json={"kind": "earn", "amount": 120, "source": "pos", "ref": "receipt-99120"},
    timeout=10,
)
resp.raise_for_status()
entry = resp.json()["entry"]

Response

201 Created

{
  "entry": {
    "_id": "6650dddd3333eeee4444fffe",
    "membership_id": "6650aaaa1111bbbb2222cccc",
    "program_id": "6650a1b2c3d4e5f6a7b8c9d0",
    "kind": "earn",
    "metric": "points",
    "amount": 120,
    "balance_after": 120,
    "source": "pos",
    "ref": "receipt-99120",
    "note": "Purchase of 12,000",
    "created_at": "2026-07-26T21:38:44.008Z"
  }
}

400 Bad Request

kind outside the allowed set, a non-numeric amount, a field over its length limit, 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.

404 Not Found

No membership with that id in your company.

502 Bad Gateway

The loyalty service is unreachable.

Operational notes

Do not fire concurrent movements against the same membership. The balance is read, modified, and written back rather than incremented atomically, so two simultaneous accruals can lose one of them. Serialise per membership — one call per transaction, not one per line item — or put them through a queue keyed by membership_id.

This call is not idempotent. There is no deduplication on ref. A retry after a network timeout may double-count, so record the returned entry _id and check the ledger before retrying.
The balance never goes below zero. Redeeming more than the customer has clamps to 0 and succeeds — it does not fail. If you need to reject an unaffordable redemption, check the balance first and decide on your side.
Nothing validates a redemption against a reward. Loyalty has no reward catalogue: redeem just subtracts. What the customer receives is your business logic.
The wallet card updates on its own. After the movement, the pass in Apple or Google Wallet is refreshed with the new balance. You do not need to call the notify endpoint for that — notify is for sending a message, not for syncing a number.
On a stamps program, amount is a stamp count. Sending amount: 1 adds one stamp. Sending 120 adds 120 stamps, which is almost certainly not what you meant — the program type is what you should branch on.
Tiers are recomputed on every movement, against the point balance and the program’s thresholds.

Authorizations

Authorization

string

header

required

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

Path Parameters

string

required

Body

application/json

kind

enum<string>

required

earn suma, redeem resta, adjust respeta el signo de amount para correcciones

Available options:

earn,

redeem,

adjust

amount

number

required

Magnitud del movimiento. En earn y redeem se toma el valor absoluto; en adjust se respeta el signo

Example:

120

source

string

De dónde vino el movimiento. Por defecto manual

Example:

"pos-sucursal-centro"

ref

string

Referencia externa, por ejemplo el número de boleta

Example:

"boleta-99120"

note

string

Example:

"Compra de 12.000 en tienda"

Response

201 - application/json

entry

object

required

Show child attributes

GET loyalty/.../ledger POST loyalty/.../passes/google

Get started

Programs

Templates

Memberships

Ledger

Wallet passes

POST /v1/loyalty/memberships/{id}/ledger

Endpoint

Required scope

Headers

Path parameters

Body

How `kind` maps to the balance

Example request

Response

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes

Authorizations

Path Parameters

Body

Response

​Endpoint

​Required scope

​Headers

​Path parameters

​Body

​How kind maps to the balance

​Example request

​Response

​201 Created

​400 Bad Request

​401 Unauthorized

​403 Forbidden

​404 Not Found

​502 Bad Gateway

​Operational notes

Authorizations

Path Parameters

Body

Response

Endpoint

Required scope

Headers

Path parameters

Body

How `kind` maps to the balance

Example request

Response

201 Created

400 Bad Request

401 Unauthorized

403 Forbidden

404 Not Found

502 Bad Gateway

Operational notes