Skip to content
TellfoxTellfox manual

Stamps and coupons from your POS

A till that is not Tellfox (your POS, a web shop, a gym’s door system) can do at the counter what the team does on the customer’s page. Make a key with the scopes customers:write, loyalty:write and, to sell packages, packages:write. Try it with a test key first. Every write needs an Idempotency-Key: make it unique for all time from your sale (for example the date and the sale number, 2026-10-22-1001-stamp), so a retried call never gives a stamp twice. Sale numbers that start again every day are not enough on their own.

1. Find the customer

Section titled “1. Find the customer”

By the phone number as the cashier types it:

Terminal window
curl "https://api.tellfox.app/v1/customers?phone=081-234-5678" -H "Authorization: Bearer $KEY"

No one found: add them. Adding someone the business already has (your external_id, then the same email, then the same phone) answers that customer instead (200), so it is safe to call every time. A customer found keeps their own details; add a phone or email with PATCH.

Terminal window
curl https://api.tellfox.app/v1/customers -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: new-cust-0812345678" \
  -d '{"name": "Somchai", "phone": "081-234-5678", "external_id": "POS-4471"}'

external_id is your POS’s own customer number; next time find them with ?external_id=POS-4471.

2. Show the card

Section titled “2. Show the card”
Terminal window
curl https://api.tellfox.app/v1/customers/cus_…/loyalty -H "Authorization: Bearer $KEY"

It answers the stamps, the points and the coupons. Active coupons come first; each has an id to use it.

3. Give stamps or points for the sale

Section titled “3. Give stamps or points for the sale”

A stamp for the visit:

Terminal window
curl https://api.tellfox.app/v1/customers/cus_…/stamps -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1001-stamp" \
  -d '{"count": 1, "reason": "Sale 1001"}'

A full card gives its reward coupon at once, as in the shop. Points for what was spent (in satang; the program’s rate makes the points):

Terminal window
curl https://api.tellfox.app/v1/customers/cus_…/points -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1001-points" \
  -d '{"amount": 125000, "reference": "Sale 1001"}'

4. Use a coupon

Section titled “4. Use a coupon”
Terminal window
curl https://api.tellfox.app/v1/customers/cus_…/coupons/gcp_…/use -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1001-coupon" -d '{}'

A coupon is used once: a used, expired or other branch’s coupon answers 409. The amount off comes from the coupon’s terms on the card; your POS takes it off the bill.

5. Sell a package

Section titled “5. Sell a package”
Terminal window
curl https://api.tellfox.app/v1/customers/cus_…/packages -X POST \
  -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" -H "Idempotency-Key: sale-1002-package" \
  -d '{"package_id": "pkg_…", "payment_method": "card"}'

The price is the package’s own (GET /v1/packages lists them). The customer gets the usual “package bought” message and can book with it at once.