API reference

Base address https://api.tellfox.app. Send your key as Authorization: Bearer tfx_live_… (see The Tellfox API). The full machine-readable spec is the OpenAPI file.

Business

GET /v1/business

The business and the key The business this key belongs to, its branches, and what the key may do. A good first call to check a key works.

Scope: Any key

Answer: data

Name	About
id	A Tellfox ID ("biz_…").
name
name_en
timezone	Times are stored in UTC; this is the zone the business shows them in.
language
currency	Money is in satang (1 baht = 100 satang), whole numbers.
mode	`test`: a test copy of the business, where nothing is ever sent to anyone.
key
branches

GET /v1/branches

Branches The open and paused branches (the ones the key may use).

Scope: Any key · A list (paged)

Answer: data[]

Name	About
id	A Tellfox ID ("loc_…").
name
primary	The first branch.
status	A paused branch (free account) takes no new bookings.
address
phone

GET /v1/services

Services and classes The active services and classes, in the order the business shows them.

Scope: Any key · A list (paged)

Answer: data[]

Name	About
id	A Tellfox ID ("svc_…").
name
name_en
kind	`class`: booked as a place in a scheduled session.
unit	`day`: a stay booked by the night.
duration_minutes
price	Satang; null when the service has no price.
branch_ids	The branches that offer it.
bookable_online

GET /v1/team

The team The active team members: names and branches only, never their contact details.

Scope: Any key · A list (paged)

Answer: data[]

Name	About
id	A Tellfox ID ("mem_…").
name
name_en
bookable	Customers can book this person.
branch_ids

Customers

GET /v1/tags

Customer tags

Scope: customers:read · A list (paged)

Answer: data[]

Name	About
id	A Tellfox ID ("tag_…").
name

GET /v1/customers

List or find customers Oldest change first, so a sync reads every change: keep the last `updated_at` you saw and send it as `updated_since` next time. Find one customer with `phone`, `email` or `external_id`. Customers belong to the whole business (every branch).

Scope: customers:read · A list (paged)

Parameters

Name	In	About
limit	query	How many to answer, 1 to 200 (default 50).
cursor	query	`meta.next_cursor` of the page before, to read the next page.
updated_since	query	Only what changed at or after this time (UTC, as `updated_at` gives it). Send a minute before the last `updated_at` you saw.
q	query	Part of a name, phone number or email.
phone	query	An exact phone number (any format; Thai numbers may start with 0).
email	query	An exact email address.
external_id	query	This key's system's own ID.
tag	query	A tag ID.

Answer: data[]

Name	About
id	A Tellfox ID ("cus_…").
name
phones	E.164 ("+66812345678").
emails
on_line	The customer is reached on LINE (the LINE ID itself is never given).
language
birthday	YYYY-MM-DD.
tags
consent	Agreed to receive offers on that channel (PDPA). Service messages need none.
external_id	This key's system's own ID for the customer.
visits	Completed bookings and class places, and served queue tickets.
last_visit_at
next_booking_at
anonymised	Erased on request (PDPA): the name is a placeholder and contact details are gone.
created_from
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change to the customer, their contact details, tags, consent or IDs (not their visit numbers, which follow the bookings). Use it as `updated_since`.

GET /v1/customers/erased

Customers erased on request Customers the business erased (PDPA) by deleting them, oldest first, kept 180 days: delete your copy. A customer with bookings is anonymised instead and stays in the list of customers with `anonymised: true`.

Scope: customers:read · A list (paged)

Parameters

Name	In	About
limit	query	How many to answer, 1 to 200 (default 50).
cursor	query	`meta.next_cursor` of the page before, to read the next page.
updated_since	query	Only what changed at or after this time (UTC, as `updated_at` gives it). Send a minute before the last `updated_at` you saw.

Answer: data[]

Name	About
id
erased_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").

GET /v1/customers/{customer_id}

A customer

Scope: customers:read

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Answer: data

Name	About
id	A Tellfox ID ("cus_…").
name
phones	E.164 ("+66812345678").
emails
on_line	The customer is reached on LINE (the LINE ID itself is never given).
language
birthday	YYYY-MM-DD.
tags
consent	Agreed to receive offers on that channel (PDPA). Service messages need none.
external_id	This key's system's own ID for the customer.
visits	Completed bookings and class places, and served queue tickets.
last_visit_at
next_booking_at
anonymised	Erased on request (PDPA): the name is a placeholder and contact details are gone.
created_from
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change to the customer, their contact details, tags, consent or IDs (not their visit numbers, which follow the bookings). Use it as `updated_since`.

POST /v1/customers

Add a customer (or find the one the business has) Finds the customer by your `external_id`, then the email, then the phone (a phone a customer proved on their own sign-in is never handed to a new one). Answers 201 with a new customer, 200 with the one found, who keeps their own details (a birthday is added only when they have none; your `external_id` is attached; add contact details with PATCH). Refused before anything is written when the found customer has another `external_id` from your system. Shows in the activity feed under the key's name.

Scope: customers:write · A write: send an Idempotency-Key

Body (JSON)

Name	About
name (required)
phone
email	An email address.
language	The language messages go out in (default th).
birthday
external_id
tags

Answer: data

Name	About
id	A Tellfox ID ("cus_…").
name
phones	E.164 ("+66812345678").
emails
on_line	The customer is reached on LINE (the LINE ID itself is never given).
language
birthday	YYYY-MM-DD.
tags
consent	Agreed to receive offers on that channel (PDPA). Service messages need none.
external_id	This key's system's own ID for the customer.
visits	Completed bookings and class places, and served queue tickets.
last_visit_at
next_booking_at
anonymised	Erased on request (PDPA): the name is a placeholder and contact details are gone.
created_from
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change to the customer, their contact details, tags, consent or IDs (not their visit numbers, which follow the bookings). Use it as `updated_since`.

PATCH /v1/customers/{customer_id}

Change a customer Name, language, birthday, your `external_id`, and phones and emails to add or remove (at most 3 of each per customer).

Scope: customers:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
name
language
birthday	YYYY-MM-DD, or null to clear it.
external_id	Your system's own ID, or null to remove it.
add_phones
remove_phones	Only numbers the customer did not prove themselves.
add_emails
remove_emails	Only addresses the customer did not prove themselves.

Answer: data

Name	About
id	A Tellfox ID ("cus_…").
name
phones	E.164 ("+66812345678").
emails
on_line	The customer is reached on LINE (the LINE ID itself is never given).
language
birthday	YYYY-MM-DD.
tags
consent	Agreed to receive offers on that channel (PDPA). Service messages need none.
external_id	This key's system's own ID for the customer.
visits	Completed bookings and class places, and served queue tickets.
last_visit_at
next_booking_at
anonymised	Erased on request (PDPA): the name is a placeholder and contact details are gone.
created_from
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change to the customer, their contact details, tags, consent or IDs (not their visit numbers, which follow the bookings). Use it as `updated_since`.

POST /v1/customers/{customer_id}/tags

Add tags

Scope: customers:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
tags (required)	Tag names; a new name makes the tag (at most 100 per business, 20 per customer).

Answer: data

Name	About
id	A Tellfox ID ("cus_…").
name
phones	E.164 ("+66812345678").
emails
on_line	The customer is reached on LINE (the LINE ID itself is never given).
language
birthday	YYYY-MM-DD.
tags
consent	Agreed to receive offers on that channel (PDPA). Service messages need none.
external_id	This key's system's own ID for the customer.
visits	Completed bookings and class places, and served queue tickets.
last_visit_at
next_booking_at
anonymised	Erased on request (PDPA): the name is a placeholder and contact details are gone.
created_from
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change to the customer, their contact details, tags, consent or IDs (not their visit numbers, which follow the bookings). Use it as `updated_since`.

DELETE /v1/customers/{customer_id}/tags/{tag_id}

Take a tag off The tag stays in the business’s list.

Scope: customers:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").
tag_id (required)	path	A Tellfox ID ("tag_…").

Answer: data

Name	About
id	A Tellfox ID ("cus_…").
name
phones	E.164 ("+66812345678").
emails
on_line	The customer is reached on LINE (the LINE ID itself is never given).
language
birthday	YYYY-MM-DD.
tags
consent	Agreed to receive offers on that channel (PDPA). Service messages need none.
external_id	This key's system's own ID for the customer.
visits	Completed bookings and class places, and served queue tickets.
last_visit_at
next_booking_at
anonymised	Erased on request (PDPA): the name is a placeholder and contact details are gone.
created_from
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change to the customer, their contact details, tags, consent or IDs (not their visit numbers, which follow the bookings). Use it as `updated_since`.

POST /v1/customers/{customer_id}/notes

Add a note The team sees it on the customer’s page, under the key’s name.

Scope: customers:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
body (required)
booking_id	One of the customer’s bookings it is about.

Answer: data

Name	About
id
body
booking_id
author
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").

GET /v1/customers/{customer_id}/notes

A customer's notes Newest first.

Scope: customers:read · A list (paged)

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").
limit	query	How many to answer, 1 to 200 (default 50).
cursor	query	`meta.next_cursor` of the page before, to read the next page.

Answer: data[]

Name	About
id
body
booking_id
author
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").

Bookings

GET /v1/bookings

List bookings and class places By start time between `from` and `to` (at most 93 days), or, with `updated_since`, oldest change first for a sync. A key limited to some branches sees only theirs.

Scope: bookings:read · A list (paged)

Parameters

Name	In	About
limit	query	How many to answer, 1 to 200 (default 50).
cursor	query	`meta.next_cursor` of the page before, to read the next page.
from	query	Starts at or after (UTC). Default: now.
to	query	Starts before (UTC). Default: 31 days after `from`.
updated_since	query	Only what changed at or after this time (UTC, as `updated_at` gives it). Send a minute before the last `updated_at` you saw.
branch_id	query
customer_id	query
status	query

Answer: data[]

Name	About
id	A Tellfox ID ("bk_…").
reference	The code the customer sees ("TF-K7M2Q-9XD4P").
kind
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
branch_id
customer_id	Null for a walk-in seated without a name (Tables).
service
staff
room
session_id	The class session, for a class place.
party_size
price	Satang, worked out by Tellfox when booked (0 when a package pays).
customer_package_id	The package that pays for it.
source	Where it was made: liff, web, owner, chat, email.
customer_note
cancelled_at
cancelled_by
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change. Use it as `updated_since`.

GET /v1/availability

Free times The free start times of a service on a day (the business’s local day), as the business sees them: its own booking window does not apply. Table services are booked on the booking page.

Scope: bookings:read · A list (paged)

Parameters

Name	In	About
service_id (required)	query	A Tellfox ID ("svc_…").
date (required)	query	A local day, YYYY-MM-DD.
branch_id	query
staff_id	query	Only this person’s times.
nights	query	For a stay booked by the night.

Answer: data[]

Name	About
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
staff_ids	Who can do it then (any of them when you name none).
price	Satang at that time (a price by time of day applies).

POST /v1/bookings

Make a booking Through the same engine as the booking page, so two bookings can never take the same time. Made by the business: no deposit; the customer gets the usual confirmation and reminders. A time taken a moment ago answers 409 with the next free times in the message. A retry with the same Idempotency-Key answers the booking it made, as it is now.

Scope: bookings:write · A write: send an Idempotency-Key

Body (JSON)

Name	About
service_id (required)	A Tellfox ID ("svc_…").
start (required)	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
customer_id (required)	A Tellfox ID ("cus_…").
staff_id	A person; left out: anyone who is free.
branch_id
nights
use_package	Pay with one of the customer’s packages that covers it.
note

Answer: data

Name	About
id	A Tellfox ID ("bk_…").
reference	The code the customer sees ("TF-K7M2Q-9XD4P").
kind
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
branch_id
customer_id	Null for a walk-in seated without a name (Tables).
service
staff
room
session_id	The class session, for a class place.
party_size
price	Satang, worked out by Tellfox when booked (0 when a package pays).
customer_package_id	The package that pays for it.
source	Where it was made: liff, web, owner, chat, email.
customer_note
cancelled_at
cancelled_by
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change. Use it as `updated_since`.

POST /v1/bookings/{booking_id}/move

Move a booking To another free time (and person). The customer is told.

Scope: bookings:write · A write: send an Idempotency-Key

Parameters

Name	In	About
booking_id (required)	path	A Tellfox ID ("bk_…").

Body (JSON)

Name	About
start (required)	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
staff_id

Answer: data

Name	About
id	A Tellfox ID ("bk_…").
reference	The code the customer sees ("TF-K7M2Q-9XD4P").
kind
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
branch_id
customer_id	Null for a walk-in seated without a name (Tables).
service
staff
room
session_id	The class session, for a class place.
party_size
price	Satang, worked out by Tellfox when booked (0 when a package pays).
customer_package_id	The package that pays for it.
source	Where it was made: liff, web, owner, chat, email.
customer_note
cancelled_at
cancelled_by
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change. Use it as `updated_since`.

POST /v1/bookings/{booking_id}/cancel

Cancel a booking or class place Cancelled by the business (its cancellation policy does not hold the business back). The customer is told.

Scope: bookings:write · A write: send an Idempotency-Key

Parameters

Name	In	About
booking_id (required)	path	A Tellfox ID ("bk_…").

Body (JSON)

Name	About
reason

Answer: data

Name	About
id	A Tellfox ID ("bk_…").
reference	The code the customer sees ("TF-K7M2Q-9XD4P").
kind
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
branch_id
customer_id	Null for a walk-in seated without a name (Tables).
service
staff
room
session_id	The class session, for a class place.
party_size
price	Satang, worked out by Tellfox when booked (0 when a package pays).
customer_package_id	The package that pays for it.
source	Where it was made: liff, web, owner, chat, email.
customer_note
cancelled_at
cancelled_by
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change. Use it as `updated_since`.

GET /v1/bookings/{booking_id}

A booking

Scope: bookings:read

Parameters

Name	In	About
booking_id (required)	path	A Tellfox ID ("bk_…").

Answer: data

Name	About
id	A Tellfox ID ("bk_…").
reference	The code the customer sees ("TF-K7M2Q-9XD4P").
kind
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
branch_id
customer_id	Null for a walk-in seated without a name (Tables).
service
staff
room
session_id	The class session, for a class place.
party_size
price	Satang, worked out by Tellfox when booked (0 when a package pays).
customer_package_id	The package that pays for it.
source	Where it was made: liff, web, owner, chat, email.
customer_note
cancelled_at
cancelled_by
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change. Use it as `updated_since`.

Classes

GET /v1/sessions

Class sessions Sessions starting between `from` and `to` (at most 31 days; default the next 14), soonest first, with the places left.

Scope: bookings:read · A list (paged)

Parameters

Name	In	About
from	query	Default: now.
to	query
service_id	query
branch_id	query

Answer: data[]

Name	About
id
service
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
instructor
room
capacity
taken
spots_left

POST /v1/sessions/{session_id}/places

Give a customer a place in a class A place while there is one (two at once never pass the capacity). The customer is told. Answers the place as a booking, 201 for a new place or 200 when the customer had one already (cancel it with POST /v1/bookings/{id}/cancel).

Scope: bookings:write · A write: send an Idempotency-Key

Parameters

Name	In	About
session_id (required)	path

Body (JSON)

Name	About
customer_id (required)	A Tellfox ID ("cus_…").
use_package
note

Answer: data

Name	About
id	A Tellfox ID ("bk_…").
reference	The code the customer sees ("TF-K7M2Q-9XD4P").
kind
status
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
branch_id
customer_id	Null for a walk-in seated without a name (Tables).
service
staff
room
session_id	The class session, for a class place.
party_size
price	Satang, worked out by Tellfox when booked (0 when a package pays).
customer_package_id	The package that pays for it.
source	Where it was made: liff, web, owner, chat, email.
customer_note
cancelled_at
cancelled_by
created_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
updated_at	The last change. Use it as `updated_since`.

Packages

GET /v1/packages

Packages on sale

Scope: packages:read · A list (paged)

Answer: data[]

Name	About
id	A Tellfox ID ("pkg_…").
name
name_en
price	Satang.
sessions
validity_days
covers	The services and classes it can be used for.
sold_online

POST /v1/customers/{customer_id}/packages

Sell a package A sale at the counter: the price comes from the package, paid by cash, transfer or card. The customer gets the usual "package bought" message; it earns on the loyalty card like a sale in the owner pages.

Scope: packages:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
package_id (required)	A Tellfox ID ("pkg_…").
payment_method (required)
note

Answer: data

Name	About
id	A Tellfox ID ("cpk_…").
package_id
name
sessions
reserved	Sessions held by bookings still to come.
used	Sessions taken by completed bookings and no-shows.
left
state	active, used_up, expired or void.
price_paid	Satang.
bought_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
last_day	The last day it can be used (YYYY-MM-DD, the business’s time zone).
covers

GET /v1/customers/{customer_id}/packages

A customer's packages Newest first (at most 50), with the sessions left.

Scope: packages:read · A list (paged)

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Answer: data[]

Name	About
id	A Tellfox ID ("cpk_…").
package_id
name
sessions
reserved	Sessions held by bookings still to come.
used	Sessions taken by completed bookings and no-shows.
left
state	active, used_up, expired or void.
price_paid	Satang.
bought_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
last_day	The last day it can be used (YYYY-MM-DD, the business’s time zone).
covers

Loyalty

GET /v1/coupons

Coupons to give The coupons the business set up and has switched on.

Scope: loyalty:read · A list (paged)

Answer: data[]

Name	About
id
name
gives
amount	Satang off, for `amount`.
percent
service_name
gift
note
valid_days
valid_until
branch_ids	Where it can be used; null: every branch.

GET /v1/rewards

Rewards for points

Scope: loyalty:read · A list (paged)

Answer: data[]

Name	About
id
name
points
coupon_name

POST /v1/customers/{customer_id}/rewards/{reward_id}/redeem

Trade points for a reward Takes the reward’s points and gives its coupon. Not enough points answers 409.

Scope: loyalty:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").
reward_id (required)	path

Answer: data

Name	About
coupon
card

GET /v1/customers/{customer_id}/loyalty

A customer's card Stamps, points and coupons. Empty when the business has no loyalty program.

Scope: loyalty:read

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Answer: data

Name	About
member	False until the customer first earns or is given something.
stamps_on
stamps
stamps_per_card
points_on
points
coupons	Active coupons first, then the latest used and expired ones.

POST /v1/customers/{customer_id}/stamps

Give stamps Stamps on the stamp card for a visit or a purchase (1 to 10 at a time). A full card gives its reward coupon, as in the owner pages. Answers the card.

Scope: loyalty:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
count
reason	What it was for; the team sees it. Default: the key’s name.
branch_id	The branch it happened at; a key limited to some branches must name one of its branches.

Answer: data

Name	About
member	False until the customer first earns or is given something.
stamps_on
stamps
stamps_per_card
points_on
points
coupons	Active coupons first, then the latest used and expired ones.

POST /v1/customers/{customer_id}/points

Points for a sale For a sale made in your system: the program’s rate turns the amount spent into whole points (for example one point per ฿10). Boosts in Tellfox apply to visits booked in Tellfox, not to these.

Scope: loyalty:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
amount (required)	What the customer spent, in satang.
reference (required)	Your sale’s number; the team sees it.
branch_id	The branch it happened at; a key limited to some branches must name one of its branches.

Answer: data

Name	About
points_added
card

POST /v1/customers/{customer_id}/coupons

Give a coupon One of the coupons the business set up (GET /v1/coupons). The customer gets the usual message on a channel they agreed to offers on. A key limited to some branches cannot give coupons (as in the owner pages).

Scope: loyalty:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").

Body (JSON)

Name	About
coupon_id (required)

Answer: data

Name	About
id	This given coupon (use it with POST …/coupons/{given_id}/use).
coupon_id
name
gives
amount
percent
service_name
gift
way	How it was given: gift, welcome, birthday, everyone, comeback, reward, card.
given_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
expires_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
status
used_at

POST /v1/customers/{customer_id}/coupons/{given_id}/use

Use a coupon Marks one of the customer’s active coupons used (`id` from their card). A coupon is used once; a used, expired or other branch’s coupon is refused with 409.

Scope: loyalty:write · A write: send an Idempotency-Key

Parameters

Name	In	About
customer_id (required)	path	A Tellfox ID ("cus_…").
given_id (required)	path

Body (JSON)

Name	About
branch_id	The branch it happened at; a key limited to some branches must name one of its branches.

Answer: data

Name	About
id	This given coupon (use it with POST …/coupons/{given_id}/use).
coupon_id
name
gives
amount
percent
service_name
gift
way	How it was given: gift, welcome, birthday, everyone, comeback, reward, card.
given_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
expires_at	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
status
used_at

Tickets

GET /v1/events

Events The business’s events with tickets (the Ticketing add-on): upcoming (default), past or drafts.

Scope: tickets:read · A list (paged)

Parameters

Name	In	About
tab	query
cursor	query	`meta.next_cursor` of the page before (30 a page).

Answer: data[]

Name	About
id
name
name_en
branch_id
start	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
end	A time in UTC, ISO 8601 ("2026-10-22T09:30:00Z").
status
sales_on
capacity
sold
link	The public event page.

GET /v1/events/{event_id}/tickets

Who bought tickets Every ticket of the event with its buyer and check-in, 50 orders a page.

Scope: tickets:read · A list (paged)

Parameters

Name	In	About
event_id (required)	path
cursor	query	`meta.next_cursor` of the page before (50 orders a page).

Answer: data[]

Name	About
id
order_id
order_reference
buyer_name
buyer_email
buyer_phone
type
status
checked_in_at

POST /v1/events/{event_id}/check-in

Check a ticket in at the door The code from the ticket’s QR (TF1.…), checked against Tellfox’s signature, for an event of today or tomorrow at a branch the key may use. Two doors scanning one ticket at once: one gets `ok`, the other `used`. Use a new Idempotency-Key for every scan.

Scope: tickets:write · A write: send an Idempotency-Key

Parameters

Name	In	About
event_id (required)	path

Body (JSON)

Name	About
code (required)

Answer: data

Name	About
state	`ok`: let them in. Anything else: do not.
ticket_id
name
type
checked_in_at	For `used`: when it was checked in before.
checked_in	Tickets checked in at this event so far.
sold

Payments

GET /v1/payments

Confirmed payments Payments customers made by PromptPay and the business confirmed (deposits, packages bought online, ticket orders), oldest first by `paid_at`. For accounting.

Scope: payments:read · A list (paged)

Parameters

Name	In	About
limit	query	How many to answer, 1 to 200 (default 50).
cursor	query	`meta.next_cursor` of the page before, to read the next page.
from	query	Confirmed at or after (UTC).
to	query	Confirmed before (UTC).

Answer: data[]

Name	About
id
kind
subject_id	The booking, package order or ticket order it paid for.
customer_id
title
amount	Satang.
paid_at	When the business confirmed it.