Base URL: https://api.sellersidekick.ai/v1/api. Send the shop's key on every request as Authorization: Bearer ssk_….
How to use this API (from the spec)
Read and update one SellerSideKick shop's products, stock, promotions, loyalty program and subscription plans. SellerSideKick is an AI chatbot and back office for online shops selling on LINE, Facebook, Instagram, Shopee, Lazada and TikTok.
The usual job: the shop owner gives you a spreadsheet (prices, stock counts, new products), and you apply it here.
Access#
- The shop owner creates a key under Settings → API keys in the SellerSideKick dashboard. Keys work on the monthly plans only.
- Send it on every request as
Authorization: Bearer ssk_.... - The key decides the shop: there is no shop id to pass. Never put the key in a URL, a file you share, or a reply to the owner.
- A key can be limited to some permissions and can expire.
GET /meshows both. The permissions arecatalog:read(always: shop, categories, products, promotions),catalog:write(create and update products; an openingstockon a new product also needsstock:write),stock:write,promotions:write,bot:write(the chat bot's Playbook, FAQ and greeting), and for the loyalty programloyalty:read(its settings, rewards, members and redemptions),loyalty:write(set up the program and its rewards),loyalty:points(change members' points),subscriptions:write(create subscription plans and put them on sale),connected_plans:write(report sign-ups and payments of plans your own system takes the payment for), andleads:write(how the bot sells a product or plan: its lead form, who fits, the brief and the promise). A call the key doesn't allow answers 403Y35naming the permission; tell the owner. - In an AI assistant app that supports connectors (MCP), the owner can connect the shop instead, with no key: the SellerSideKick connector at
https://mcp.sellersidekick.ai/mcp(sign in, pick the shop and permissions).
How to work#
- Call
GET /meto confirm which shop the key is for, and tell the owner the shop name. - Read before writing:
GET /categoriesfor the allowed category names;GET /products?sku=...for the current prices and stock.
- Send every write with
dry_run: truefirst. Show the owner the summary and every row with statuserror, and wait for a clear yes. - Send the same request with
dry_run: false. Report the summary and everyerrorrow.
Rules#
- At most 500 rows per request: split bigger sheets. Each row succeeds or fails on its own, so read
results. - A promotion's product list (
product_discounts,applies_to.skus) is the exception: up to 5,000 SKUs, always in one request. An update replaces the saved list, so a split list keeps only its last part. - Products are matched by SKU. Stock changes only through
POST /stock, never throughPOST /products/upsert. - Pictures: put links in a product's
images(each is copied onto SellerSideKick). Pictures the owner has as files go up first throughPOST /images, which answers their links. - For stock, give each new change its own
idempotency_key, and reuse it only to retry that same request. - Nothing can be deleted. To end a promotion, set its status to
archive.
What reaches the marketplaces#
- Stock changes reach the shop's linked Shopee, Lazada and TikTok listings, usually within about 10 minutes.
- Prices, names, descriptions and promotions change the SellerSideKick store and the shop's chat bot only, not the marketplace listings.
- The Playbook and FAQ (
/bot) change what the shop's chat bot says to customers on every channel it answers. The greeting (/bot/greeting) is what new conversations on LINE, Facebook and Instagram open with. - Only products on the SellerSideKick store can be changed. A SKU that exists only on a marketplace is an error row.
Loyalty program#
GET /loyalty/programfirst: whether the shop has a program, its settings and a summary. Only orders from LINE, Facebook, Instagram and direct orders earn; Shopee, Lazada and TikTok orders never do.- To set one up: pick a preset from
GET /loyalty/templates, create it (POST /loyalty/program, it starts as a draft that earns nothing), check typical orders withPOST /loyalty/program/simulate, add rewards, and switch it on withPOST /loyalty/program/statusonce the owner says yes. - Members are the shop's customers: their phone, platform id and staff notes are never shown here.
- Points writes (
/adjust,/redeem) take anidempotency_keyand adry_run: preview first, get the owner's yes, then send the same request withdry_run: false. - To check it works as the owner expects:
POST /loyalty/program/checksruns a ready-made check for each thing the settings promise and reviews them for mistakes;POST /loyalty/program/testreplays a customer's story you describe, with what should happen. Both save nothing, and both can test a preset or settings before they are saved.
Subscription plans#
- Plans the shop sells to its own customers, paid every period (Products › Subscription plans in the dashboard). Reading them takes
catalog:read; changing themsubscriptions:write. Subscribers are the shop's customers and are not in this API. GET /subscriptions/readinessfirst: a plan can be saved as a draft any time, but going on sale needs the shop's Stripe account connected and ready (ready: true). Otherwise the owner connects Stripe in the dashboard first.- Create plans as drafts (
POST /subscriptions/plans), show the owner the names, descriptions and prices, and put them on sale (PATCH /subscriptions/plans/{id}withstatus: "on_sale") only after their yes: customers can subscribe from then on. - Prices are in baht. SSK charges a price exactly as typed, so type it with any VAT the shop charges included (
vat: "included"tells buyers so).vat: "excluded"("plus 7% VAT") is only for a plan paid in the shop's own system. A price can't change once it is on sale: add a new price, then stop the old one for new sign-ups (its subscribers keep it). - Describe a plan for buyers and the chat bot:
tagline(one line under the name),highlights(what's included, one line each),audience(who it's for),not_included,badge,sort(its place in the list) andrules(cancelling, pausing, late payment, refunds, changing plan: amodethe sentence is written from, or the shop's owntext). A change replaces each of these whole. - Plan names are unique among the shop's plans that aren't archived, so a resent create is refused rather than made twice. Plans are never deleted, only archived.
Connected plans (payment events)#
- For plans the shop sells but its own system takes the payment for (Products › Subscription plans, "Who takes the payment?" → "Your own system"). SSK sends each customer a personal sign-up link carrying
ssk_ref; keep that code with the customer and send it back with every event. POST /connected-plans/eventswithconnected_plans:write:signed_up,paid,renewed,cancelled,payment_failed. The firstpaidwith an amount marks the customer's lead as won.- Every event needs your own
idempotency_key(e.g. your invoice or event id). Sending the same key again is safe: you get the first answer back (200,duplicate: true) and nothing changes. Retry on 5xx, 409 and 429 with the same key. - No
ssk_ref(the customer signed up without the link)? Sendemailorphone(andplan_code): SSK looks for the lead as a probable match for the team to confirm.
Lead capture (how the bot sells a product or plan)#
- For products and plans the shop sells through its sales team: with
enabled: truethe chat bot explains the item and quotes its price but never sells it; it fills the item's lead form in the chat and saves a lead for the team (Leads in the dashboard). Only for shops with lead capture switched on. GET /leads/items/{kind}/{id}(kindisproductorplan) reads the settings withcatalog:read;PATCHchanges them withleads:write. A change names only what it changes; the rest stays.- The form: up to 30
fields(name,descriptionin plain words the bot reads,kind,optionsfor a choice,required). A field'skeyis made from its name when you leave it out; rules name fields by key. Switching it on needs at least one required field. qualify.textsays who fits in plain words (the bot judges it);qualify.rulesare checks on number or choice fields.briefis anything else about how to talk about the item;promiseis the line the bot says once the lead is saved.meeting: a 30-minute phone call, Google Meet or meeting in person that the customer books on a page the bot sends. Who takes the meetings is chosen in the dashboard (the API showshosts_countonly); it can't be switched on before there is a host.
Limits and errors#
- 120 requests a minute per shop. On
429, wait theRetry-Afterseconds and retry. - Errors are
{ code, message, rcode }. - 400 means fix the field the message names. 401 and 403 mean the key can't be used; tell the owner, because retrying won't help.
Thai text is welcome everywhere (names, descriptions, promotion names). Prices are in THB.
Shop
Which shop the key belongs to, and its categories.
GET/me#
Which shop this key belongs to.
Use first, before any other call. It confirms the key works and names the shop so the owner can check it is the right one.
Changes nothing. Safe to call any time.
Response 200
The shop and the key's name.
ok
{
"code": 200,
"message": "OK",
"data": {
"shop": {
"id": "6650a1b2c3d4e5f607182930",
"uuid": "3833993e-2bcd-41e6-af1b-b8d115aafae0",
"name": "ร้านของเล่นนิชิ",
"currency": "THB"
},
"key": {
"name": "Catalogue update from sheet",
"prefix": "ssk_AbCdEfGh",
"scopes": [
"catalog:read",
"catalog:write",
"stock:write",
"promotions:write"
],
"expires_at": "2027-01-23T03:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/categories#
The category names a product may use.
Use before creating products or changing a category. Map the sheet's categories onto these names; matching ignores case. A name that isn't here is an error row.
Changes nothing.
Response 200
Category names.
ok
{
"code": 200,
"message": "OK",
"data": {
"categories": [
"Toys",
"Books",
"Clothing"
]
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Products
Read, create and update products by SKU. Prices and content stay on the SellerSideKick store.
GET/products#
The shop's products with price and stock, by SKU or page by page.
Use to read current prices, names and stock before you change them. Read before a stock count you plan to guard with expected_from, and to check which SKUs already exist.
- Lists only products on the shop's SellerSideKick store.
- Pass
sku(comma-separated) for specific products, or omit it to page through everything. Results are paged either way: setlimit(up to 500) when asking for many SKUs.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
sku (query) | string | no | Comma-separated SKUs, e.g. `TM-001,TM-002`. |
page (query) | integer | no | (min 1) (default 1) |
limit (query) | integer | no | (min 1) (max 500) (default 100) |
Response 200
A page of products.
ok
{
"code": 200,
"message": "OK",
"data": {
"products": [
{
"sku": "TM-001",
"name": {
"th": "รถเหล็กโทมิก้า รุ่นรถตำรวจ",
"en": "Tomica police car"
},
"description": {
"th": "รถเหล็กสเกล 1:64 ประตูเปิดได้",
"en": "1:64 die-cast car, opening doors"
},
"usage_information": {
"th": "เหมาะสำหรับเด็กอายุ 3 ปีขึ้นไป",
"en": "Ages 3 and up"
},
"price": 129,
"currency": "THB",
"category": "Toys",
"brand": "Tomica",
"images": [
"https://seller-side.sgp1.digitaloceanspaces.com/products/api-3f1c9a6b2d4e5f60718293a4b5c6d7e8f9a0b1c2.jpg"
],
"parent_sku": null,
"stock": {
"on_hand": 40,
"available": 37
},
"archived": false,
"updated_at": "2026-10-24T09:15:00.000Z"
}
],
"page": 1,
"limit": 100,
"total": 1,
"total_pages": 1
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/products/upsert#
Create new products and update existing ones by SKU (up to 500 rows).
Use when the owner wants prices, names, descriptions, categories or brands changed, or new products added.
Don't use for stock: an existing product's stock changes only through POST /stock. Sending stock for an existing SKU is an error row.
Before calling:
- Get category names from
GET /categories. - Send with
dry_run: true, show the owner the summary and the error rows, and only send it for real after they agree.
How rows are handled:
- A SKU the shop has is updated with only the fields you send; the rest stay.
- A new SKU is created. It needs
name,price,categoryandbrand, and may setstock(the opening count) andparent_sku(to make it a variant of a main product, which may be created in the same request). - Each row answers
created,updated(withchanged),unchangedorerror.
Pictures (images):
- Links to the pictures, 1 to 7, the first being the main one. They replace the product's pictures.
- Each picture is downloaded and copied onto SellerSideKick, as an Excel or marketplace import does, so the link must be a public http(s) address that answers with a JPEG, PNG or WebP picture of at most 15 MB.
- A picture that can't be fetched makes its row an error, and nothing in that row is saved. A dry run checks each address but doesn't download it.
- Sending the same links again changes nothing. Pictures you have as files: send them to
POST /imagesfirst and use the links it answers. - Rows with new pictures take a few seconds each, so send at most about 50 of them per request.
Effect: changes the SellerSideKick store and the shop's chat bot. Marketplace listings keep their own price and content.
Safe to retry: yes. Sending the same rows again leaves them unchanged.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
dry_run | boolean | no | true: check every row and report what would happen, changing nothing. (default false) |
products | array of object {sku, name, description, usage_information, price, category, brand, images, stock, parent_sku} | yes | (at least 1 items) (at most 500 items) |
products[].sku | string | yes | |
products[].name | string or object {th, en} | no | A string is the Thai text (the saved English text is kept), or send { th, en } to set either or both. |
products[].description | string or object {th, en} | no | A string is the Thai text (the saved English text is kept), or send { th, en } to set either or both. |
products[].usage_information | string or object {th, en} | no | How to use or care for the product. A string is the Thai text (the saved English text is kept), or send { th, en } to set either or both. |
products[].price | number | no | THB. (min 0) |
products[].category | string | no | A name from GET /categories. |
products[].brand | string | no | A new brand is added to the shop's brand list. |
products[].images | array of string | no | Picture links (http or https), first = the main picture. Replaces the product's pictures; each is copied onto SellerSideKick. (at least 1 items) (at most 7 items) |
products[].stock | integer | no | New products only: the opening count on the shelf. (min 0) |
products[].parent_sku | string | no | New products only: the main product this one is a variant of. A new variant that gives no category or brand takes the main product's. |
Request examples
Update two prices (dry run first) price_update
{
"dry_run": true,
"products": [
{
"sku": "TM-001",
"price": 139
},
{
"sku": "TM-002",
"price": 159
}
]
}Add a new product with Thai and English names new_product
{
"dry_run": true,
"products": [
{
"sku": "TM-010",
"name": {
"th": "รถดับเพลิงโทมิก้า",
"en": "Tomica fire engine"
},
"price": 189,
"category": "Toys",
"brand": "Tomica",
"stock": 12
}
]
}A new product with two pictures, and a new main picture for another with_pictures
{
"dry_run": true,
"products": [
{
"sku": "TM-011",
"name": {
"th": "รถตำรวจโทมิก้า",
"en": "Tomica police car"
},
"price": 129,
"category": "Toys",
"brand": "Tomica",
"images": [
"https://www.example.com/photos/tm-011-front.jpg",
"https://www.example.com/photos/tm-011-box.jpg"
]
},
{
"sku": "TM-001",
"images": [
"https://seller-side.sgp1.digitaloceanspaces.com/products/tm-001-new-Q8ZK3P.jpg"
]
}
]
}A main product and two variants in one request variants
{
"products": [
{
"sku": "SHIRT-01",
"name": "เสื้อยืดลายแมว",
"price": 290,
"category": "Clothing",
"brand": "Nichi"
},
{
"sku": "SHIRT-01-M",
"name": "เสื้อยืดลายแมว ไซซ์ M",
"price": 290,
"category": "Clothing",
"brand": "Nichi",
"parent_sku": "SHIRT-01",
"stock": 20
},
{
"sku": "SHIRT-01-L",
"name": "เสื้อยืดลายแมว ไซซ์ L",
"price": 290,
"category": "Clothing",
"brand": "Nichi",
"parent_sku": "SHIRT-01",
"stock": 15
}
]
}Response 200
Each row's result. Report the summary and every `error` row to the owner.
ok
{
"code": 200,
"message": "Dry run: nothing was changed",
"data": {
"dry_run": true,
"results": [
{
"sku": "TM-001",
"status": "updated",
"changed": [
"price"
]
},
{
"sku": "TM-002",
"status": "unchanged"
},
{
"sku": "TM-099",
"status": "error",
"error": "Unknown category \"Gadgets\". Use one of the shop's top-level categories (GET /v1/api/categories)."
}
],
"summary": {
"total": 3,
"updated": 1,
"unchanged": 1,
"error": 1
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/images#
Upload product pictures as files and get their links (up to 7 a request).
Use when the owner gives you pictures as files (photos, a folder) rather than links. Upload them here, then put the links this answers in the products' images with POST /products/upsert.
Don't use for pictures that are already online: put their links straight in images.
How: a multipart/form-data request with 1 to 7 files in the field images. Each must be a JPEG, PNG or WebP picture of at most 10 MB (WebP is saved as JPEG). Name each file after its product, e.g. TM-011-front.jpg, so you can match the links back.
Effect: stores the pictures on SellerSideKick. They show nowhere until a product's images names them.
Safe to retry: yes, but each upload stores new copies with new links; use the links from the one that succeeded.
Response 200
The stored pictures, in the order sent. `title` is the file's name; put each `url` in a product's `images`.
ok
{
"code": 200,
"message": "Pictures uploaded",
"data": {
"images": [
{
"title": "TM-011-front.jpg",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/products/TM-011-front-K2J9QX.jpg"
},
{
"title": "TM-011-box.jpg",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/products/TM-011-box-7HD2LM.jpg"
}
]
}
}Errors
- 400: No pictures, too many, too large, or not a JPEG, PNG or WebP picture. The message says which.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Stock
Count or adjust on-hand units. Reaches linked marketplace listings.
POST/stock#
Set counted stock or adjust it by SKU (up to 500 rows).
Use when the owner has counted stock (send value, the units now on the shelf) or wants to add or remove units (send delta, e.g. -3 for damaged goods). Never both.
Before calling:
- To be safe against changes made since you read, send
expected_from(the on-hand you read) withvalue. A row whose on-hand moved meanwhile is refused instead of overwritten. - Send
dry_run: truefirst and confirm with the owner. - A dry run doesn't check holds by open orders, a delta on a never-counted SKU, or a replay, so the real call can still answer some rows differently.
Effect:
- Recorded in the shop's stock history.
- Sent to the SKU's linked Shopee, Lazada and TikTok listings, usually within about 10 minutes.
- Only SKUs on the SellerSideKick store; a marketplace-only SKU is an error row.
- A
deltacan't take on-hand below what open orders hold. A countedvalueis recorded as counted, even below that.
Safe to retry: yes, with the same idempotency_key. A row already applied answers already_applied. Use a new key for each new change: a row with different numbers under a reused key is applied.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
dry_run | boolean | no | (default false) |
idempotency_key | string | no | Your id for this change, e.g. `count-2026-10-25-sheet1`. Resending with it never applies a row twice. (min length 8) (max length 100) (pattern `^[A-Za-z0-9._:-]+$`) |
items | array of object {sku, value, delta, expected_from, reason} | yes | (at least 1 items) (at most 500 items) |
items[].sku | string | yes | |
items[].value | integer | no | The units now on the shelf (a count). (min 0) |
items[].delta | integer | no | Units to add (positive) or remove (negative). Not 0. |
items[].expected_from | integer | no | With `value` only: the on-hand you read. If it has changed, the row is refused. (min 0) |
items[].reason | string | no | Shown in the stock history, e.g. 'monthly count'. (max length 200) |
Request examples
A stock count, guarded against changes since it was read count
{
"idempotency_key": "count-2026-10-25-sheet1",
"dry_run": true,
"items": [
{
"sku": "TM-001",
"value": 40,
"expected_from": 37,
"reason": "monthly count"
},
{
"sku": "TM-002",
"value": 0,
"reason": "monthly count"
}
]
}Remove 3 damaged units adjust
{
"idempotency_key": "damaged-2026-10-25",
"items": [
{
"sku": "TM-001",
"delta": -3,
"reason": "damaged in transit"
}
]
}Response 200
Each row's result. Report the summary and every `error` row to the owner.
ok
{
"code": 200,
"message": "Stock processed",
"data": {
"dry_run": false,
"results": [
{
"sku": "TM-001",
"status": "updated",
"from": 37,
"to": 40,
"available": 38
},
{
"sku": "TM-002",
"status": "already_applied"
},
{
"sku": "ZZ-9",
"status": "error",
"error": "This SKU is not a product on your SellerSideKick store (it may be only on a marketplace channel)."
}
],
"summary": {
"total": 3,
"updated": 1,
"already_applied": 1,
"error": 1
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Promotions
The shop's own coupons, discounts, bundles and buy-X-get-Y offers. Never deleted, only archived.
GET/promotions#
The shop's own promotions, optionally by type and status.
Use to find a promotion's id before updating or archiving it, and to check a code is free before creating one.
Marketplace promotions (Shopee, Lazada, TikTok) are not listed: they are managed in each Seller Center.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
type (query) | "coupon" | "discount" | "bundle" | "bogo" | no | Only this type. |
status (query) | "active" | "inactive" | "archive" | no | Only this status. |
Response 200
Promotions, newest first within each type.
ok
{
"code": 200,
"message": "OK",
"data": {
"promotions": [
{
"id": "6650f0c2a1b2c3d4e5f60718",
"type": "coupon",
"status": "active",
"times_used": 0,
"code": "WELCOME10",
"name": "ส่วนลด 10% สำหรับลูกค้าใหม่",
"discount_type": "percentage",
"value": 10,
"max_discount_amount": 100,
"applies_to": {
"all_products": true
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-30T23:59:59+07:00",
"max_uses_per_customer": 1
}
]
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/promotions/{type}#
Create a coupon, discount, bundle or BOGO promotion.
Use when the owner asks for a new promotion.
Before calling:
- Confirm the code, dates, amount and the products it covers with the owner.
- SKUs must be on the shop's SellerSideKick store; an unknown SKU is a 400.
- A code the shop already uses is refused (400).
Effect: live in the shop's SellerSideKick store and chat bot from starts_at (status active unless you send inactive). Not pushed to marketplaces.
Safe to retry: no. Check with GET /promotions whether it was created before sending again.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
type (path) | "coupon" | "discount" | "bundle" | "bogo" | yes | The promotion's type. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
code | string | no | Upper-case letters, digits, - and _; lower case is upper-cased. Unique in the shop. |
name | string | no | |
description | string | no | |
starts_at | string | no | (format date-time) |
ends_at | string | no | Must be after starts_at. (format date-time) |
status | "active" | "inactive" | no | Create only. Default active. |
max_uses | integer | null | no | Total uses allowed; null for no limit. |
max_uses_per_customer | integer | null | no | |
discount_type | "percentage" | "fixed" | no | |
value | number | no | Percent (at most 100) or THB, by discount_type. |
min_order_amount | number | no | THB. |
max_discount_amount | number | null | no | THB cap on a percentage discount. |
can_stack | boolean | no | Coupon only: usable together with other promotions. |
applies_to | object {all_products, categories, brands, skus} | no | Which products the discount covers: `all_products: true`, or any mix of categories, brands and SKUs (not both). |
applies_to.all_products | boolean | no | |
applies_to.categories | array of string | no | Category names from GET /categories. |
applies_to.brands | array of string | no | |
applies_to.skus | array of string | no | Must be SKUs on the shop's SellerSideKick store. Up to 5,000, sent whole: an update replaces the saved list. (at most 5000 items) |
product_discounts | array of object {sku, discount_type, value} | no | Discount only: a rate per SKU, off every unit of it, instead of one rate for the listed products. Leave out discount_type, value, max_discount_amount and applies_to. Up to 5,000 SKUs. On an update the list replaces the saved one, so always send the whole list in one request, never split it. (at most 5000 items) |
product_discounts[].sku | string | yes | |
product_discounts[].discount_type | "percentage" | "fixed" | yes | |
product_discounts[].value | number | yes | Percent (at most 100), or THB off every unit. |
bot_feature | object {enabled, announcement_th, announcement_en} | no | Discount, bundle or BOGO (never a coupon): feature this promotion in the shop's chat bot. While the promotion is active and inside its dates, the chat bot (on LINE, Facebook, Instagram and web chat; never on Shopee, Lazada or TikTok Shop) opens a conversation with the announcement, or with one built from the promotion's name and end date when it is empty; recommends this promotion's in-stock products first when they fit what the customer asks for; and ranks them a little higher among relevant search results. It starts and stops with the promotion's dates by itself. Optional on create (left out = off). On an update, sending it replaces the whole setting, so send all three keys (a missing one becomes false or empty); leave it out to keep the saved one. |
bot_feature.enabled | boolean | no | Feature it in the chat bot. (default false) |
bot_feature.announcement_th | string | no | The Thai message the chat bot opens a conversation with. Trimmed. Empty: built from the name and end date. Write {end_date} where the end date goes: the bot puts the promotion's end date there ("6 พ.ย. 2569"), so it stays right when the dates change. A date typed that is neither the start nor the end day comes back in the response's warnings. (max length 400) (default "") |
bot_feature.announcement_en | string | no | Optional English version of the announcement. Trimmed. {end_date} becomes the end date ("6 Nov 2026"). (max length 400) (default "") |
products | array of object {sku, quantity, role} | no | |
products[].sku | string | yes | |
products[].quantity | integer | yes | (min 1) |
products[].role | "buy" | "get" | no | BOGO only. |
choose_gift | boolean | no | BOGO only: Mix & Match, buy from the list, choose a gift. Every buy_quantity units bought of the products with role buy (added up) earn get_quantity gifts the customer picks from those with role get (the same gift as often as they like); gifts they don't pick are the first get products with stock. |
buy_quantity | integer | no | Mix & Match only: how many units of the buy products earn the gifts. Default 1. (min 1) (max 100) |
get_quantity | integer | no | Mix & Match only: how many gifts every buy_quantity units earn. Default 1. (min 1) (max 100) |
bundle_discount_type | "fixed_price" | "fixed" | "percentage" | no | fixed_price: one set costs bundle_price (what the dashboard sets). percentage: bundle_discount_percentage off the set. fixed: bundle_discount THB off the set. |
bundle_price | number | no | What the customer pays for one set, when bundle_discount_type is fixed_price. The discount is what the set's products cost above it, never below 0. |
bundle_discount | number | no | THB off the bundle, when bundle_discount_type is fixed. |
bundle_discount_percentage | number | no | Percent off, when bundle_discount_type is percentage. |
Request examples
Coupon: 10% off the whole shop, at most 100 THB coupon
{
"code": "WELCOME10",
"name": "ส่วนลด 10% สำหรับลูกค้าใหม่",
"discount_type": "percentage",
"value": 10,
"max_discount_amount": 100,
"applies_to": {
"all_products": true
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-30T23:59:59+07:00",
"max_uses_per_customer": 1
}Discount: a rate per SKU discount_per_sku
{
"code": "WHSALE",
"name": "Warehouse sale",
"product_discounts": [
{
"sku": "TM-001",
"discount_type": "fixed",
"value": 120
},
{
"sku": "TM-002",
"discount_type": "percentage",
"value": 25
}
],
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-15T23:59:59+07:00"
}Discount: 50 THB off two SKUs discount
{
"code": "TOMICA50",
"name": "Tomica ลด 50 บาท",
"discount_type": "fixed",
"value": 50,
"applies_to": {
"skus": [
"TM-001",
"TM-002"
]
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-15T23:59:59+07:00"
}Discount featured in the chat bot discount_featured
{
"code": "TOMICA15",
"name": "Tomica ลด 15%",
"discount_type": "percentage",
"value": 15,
"applies_to": {
"brands": [
"Tomica"
]
},
"bot_feature": {
"enabled": true,
"announcement_th": "รถเหล็กโทมิก้าทุกรุ่น ลด 15% ถึง 15 พ.ย. นี้เท่านั้น",
"announcement_en": "Every Tomica car is 15% off until 15 November."
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-15T23:59:59+07:00"
}Bundle: two cars for 399 THB bundle
{
"code": "PAIR399",
"name": "คู่ละ 399 บาท",
"products": [
{
"sku": "TM-001",
"quantity": 1
},
{
"sku": "TM-002",
"quantity": 1
}
],
"bundle_discount_type": "fixed_price",
"bundle_price": 399,
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-12-31T23:59:59+07:00"
}Bundle: two cars for 20% off bundle_percent
{
"code": "PAIR20",
"name": "ซื้อคู่ลด 20%",
"products": [
{
"sku": "TM-001",
"quantity": 1
},
{
"sku": "TM-002",
"quantity": 1
}
],
"bundle_discount_type": "percentage",
"bundle_discount_percentage": 20,
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-12-31T23:59:59+07:00"
}BOGO: buy 2 cars, get a track free bogo
{
"code": "B2G1TRACK",
"name": "ซื้อ 2 แถมราง 1",
"products": [
{
"sku": "TM-001",
"quantity": 2,
"role": "buy"
},
{
"sku": "TR-100",
"quantity": 1,
"role": "get"
}
],
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-30T23:59:59+07:00"
}Response 201
The new promotion.
ok
{
"code": 200,
"message": "Promotion created",
"data": {
"promotion": {
"id": "6650f0c2a1b2c3d4e5f60718",
"type": "coupon",
"status": "active",
"times_used": 0,
"code": "WELCOME10",
"name": "ส่วนลด 10% สำหรับลูกค้าใหม่",
"discount_type": "percentage",
"value": 10,
"max_discount_amount": 100,
"applies_to": {
"all_products": true
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-30T23:59:59+07:00",
"max_uses_per_customer": 1
}
}
}Errors
- 400: The request is invalid (the message names the field), a SKU isn't on the shop's store, or the code is already used. Fix it and send again.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
PATCH/promotions/{type}/{id}#
Change a promotion: send only the fields that change.
Use when the owner wants a promotion's dates, amount, products, limits, name or code changed.
Before calling: get the id from GET /promotions and confirm the change with the owner. The type in the path must match the promotion's own.
Checked as the promotion will be afterwards. For example, ends_at must stay after the saved starts_at, a percentage stays at 100 or below, and a BOGO keeps a buy and a get product.
Don't use to switch it on or off or end it: use POST /promotions/{type}/{id}/status. Marketplace promotions can't be changed here.
Safe to retry: yes. Sending the same fields again gives the same result.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
type (path) | "coupon" | "discount" | "bundle" | "bogo" | yes | The promotion's type. |
id (path) | string | yes | The promotion's id from GET /promotions. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
code | string | no | Upper-case letters, digits, - and _; lower case is upper-cased. Unique in the shop. |
name | string | no | |
description | string | no | |
starts_at | string | no | (format date-time) |
ends_at | string | no | Must be after starts_at. (format date-time) |
status | "active" | "inactive" | no | Create only. Default active. |
max_uses | integer | null | no | Total uses allowed; null for no limit. |
max_uses_per_customer | integer | null | no | |
discount_type | "percentage" | "fixed" | no | |
value | number | no | Percent (at most 100) or THB, by discount_type. |
min_order_amount | number | no | THB. |
max_discount_amount | number | null | no | THB cap on a percentage discount. |
can_stack | boolean | no | Coupon only: usable together with other promotions. |
applies_to | object {all_products, categories, brands, skus} | no | Which products the discount covers: `all_products: true`, or any mix of categories, brands and SKUs (not both). |
applies_to.all_products | boolean | no | |
applies_to.categories | array of string | no | Category names from GET /categories. |
applies_to.brands | array of string | no | |
applies_to.skus | array of string | no | Must be SKUs on the shop's SellerSideKick store. Up to 5,000, sent whole: an update replaces the saved list. (at most 5000 items) |
product_discounts | array of object {sku, discount_type, value} | no | Discount only: a rate per SKU, off every unit of it, instead of one rate for the listed products. Leave out discount_type, value, max_discount_amount and applies_to. Up to 5,000 SKUs. On an update the list replaces the saved one, so always send the whole list in one request, never split it. (at most 5000 items) |
product_discounts[].sku | string | yes | |
product_discounts[].discount_type | "percentage" | "fixed" | yes | |
product_discounts[].value | number | yes | Percent (at most 100), or THB off every unit. |
bot_feature | object {enabled, announcement_th, announcement_en} | no | Discount, bundle or BOGO (never a coupon): feature this promotion in the shop's chat bot. While the promotion is active and inside its dates, the chat bot (on LINE, Facebook, Instagram and web chat; never on Shopee, Lazada or TikTok Shop) opens a conversation with the announcement, or with one built from the promotion's name and end date when it is empty; recommends this promotion's in-stock products first when they fit what the customer asks for; and ranks them a little higher among relevant search results. It starts and stops with the promotion's dates by itself. Optional on create (left out = off). On an update, sending it replaces the whole setting, so send all three keys (a missing one becomes false or empty); leave it out to keep the saved one. |
bot_feature.enabled | boolean | no | Feature it in the chat bot. (default false) |
bot_feature.announcement_th | string | no | The Thai message the chat bot opens a conversation with. Trimmed. Empty: built from the name and end date. Write {end_date} where the end date goes: the bot puts the promotion's end date there ("6 พ.ย. 2569"), so it stays right when the dates change. A date typed that is neither the start nor the end day comes back in the response's warnings. (max length 400) (default "") |
bot_feature.announcement_en | string | no | Optional English version of the announcement. Trimmed. {end_date} becomes the end date ("6 Nov 2026"). (max length 400) (default "") |
products | array of object {sku, quantity, role} | no | |
products[].sku | string | yes | |
products[].quantity | integer | yes | (min 1) |
products[].role | "buy" | "get" | no | BOGO only. |
choose_gift | boolean | no | BOGO only: Mix & Match, buy from the list, choose a gift. Every buy_quantity units bought of the products with role buy (added up) earn get_quantity gifts the customer picks from those with role get (the same gift as often as they like); gifts they don't pick are the first get products with stock. |
buy_quantity | integer | no | Mix & Match only: how many units of the buy products earn the gifts. Default 1. (min 1) (max 100) |
get_quantity | integer | no | Mix & Match only: how many gifts every buy_quantity units earn. Default 1. (min 1) (max 100) |
bundle_discount_type | "fixed_price" | "fixed" | "percentage" | no | fixed_price: one set costs bundle_price (what the dashboard sets). percentage: bundle_discount_percentage off the set. fixed: bundle_discount THB off the set. |
bundle_price | number | no | What the customer pays for one set, when bundle_discount_type is fixed_price. The discount is what the set's products cost above it, never below 0. |
bundle_discount | number | no | THB off the bundle, when bundle_discount_type is fixed. |
bundle_discount_percentage | number | no | Percent off, when bundle_discount_type is percentage. |
Request examples
Extend the end date extend
{
"ends_at": "2026-12-15T23:59:59+07:00"
}Raise a discount to 15% raise
{
"value": 15
}Response 200
The promotion as saved.
ok
{
"code": 200,
"message": "Promotion updated",
"data": {
"promotion": {
"id": "6650f0c2a1b2c3d4e5f60718",
"type": "coupon",
"status": "active",
"times_used": 0,
"code": "WELCOME10",
"name": "ส่วนลด 10% สำหรับลูกค้าใหม่",
"discount_type": "percentage",
"value": 10,
"max_discount_amount": 100,
"applies_to": {
"all_products": true
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-30T23:59:59+07:00",
"max_uses_per_customer": 1
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No promotion with this id and type in this shop. List promotions to get a valid id.
- 409: The new code is already used by another promotion of this type in the shop. Pick another code.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/promotions/{type}/{id}/status#
Switch a promotion on or off, or end it (archive).
Use when the owner wants to pause a promotion (inactive), resume it (active) or end it for good (archive). Archive is how a promotion is removed: nothing is deleted, and it stays in the history.
Before calling: confirm with the owner, especially before archive.
Safe to retry: yes.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
type (path) | "coupon" | "discount" | "bundle" | "bogo" | yes | The promotion's type. |
id (path) | string | yes | The promotion's id from GET /promotions. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
status | "active" | "inactive" | "archive" | yes |
Request examples
pause
{
"status": "inactive"
} end
{
"status": "archive"
}Response 200
The promotion with its new status.
ok
{
"code": 200,
"message": "Promotion archive",
"data": {
"promotion": {
"id": "6650f0c2a1b2c3d4e5f60718",
"type": "coupon",
"status": "active",
"times_used": 0,
"code": "WELCOME10",
"name": "ส่วนลด 10% สำหรับลูกค้าใหม่",
"discount_type": "percentage",
"value": 10,
"max_discount_amount": 100,
"applies_to": {
"all_products": true
},
"starts_at": "2026-11-01T00:00:00+07:00",
"ends_at": "2026-11-30T23:59:59+07:00",
"max_uses_per_customer": 1
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No promotion with this id and type in this shop. List promotions to get a valid id.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Bot
The chat bot's Playbook (how it sells and talks), its FAQ and its greeting, as in the dashboard's Bot settings.
GET/bot#
The chat bot's Playbook, FAQ and greeting.
Use before changing the Playbook, the FAQ or the greeting: read what is there, so an update keeps what the owner wants kept.
playbook: the shop's own instructions to the bot (what to recommend, how to talk, what to say about delivery or promotions).faq: questions and answers the bot answers from.mediaare pictures or videos added in the dashboard; the API keeps them but can't add them.greeting: what a new conversation on LINE, Facebook or Instagram opens with: each channel's text, then up to 10 items (a video, a picture or product cards), each with an optional message sent right after it.
Changes nothing.
Response 200
The Playbook, the FAQ in the order the bot reads it, and the greeting.
ok
{
"code": 200,
"message": "OK",
"data": {
"playbook": "แนะนำสินค้าลดราคาก่อน ตอบสุภาพ ลงท้ายด้วยค่ะ",
"faq": [
{
"question": "ส่งของกี่วันถึง",
"answer": "ส่งภายใน 1-2 วันทำการค่ะ",
"media": []
},
{
"question": "มีหน้าร้านไหม",
"answer": "มีค่ะ ที่ซอยพัฒนาการ 51",
"media": [
{
"type": "image",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/faq/map-K2J9QX.jpg",
"description": "แผนที่ร้าน"
}
]
}
],
"greeting": {
"enabled": true,
"text": {
"line": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง หรือส่งรูปของเล่นที่ตามหามาได้เลยค่ะ",
"meta": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ",
"ig": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ"
},
"items": [
{
"type": "video",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-AB12CD.mp4",
"thumbnail_url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-frame-EF34GH.jpg",
"description": "How to chat with the bot and order in the LINE Mini App",
"message": "",
"show_message": false
},
{
"type": "image",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/sale-1free1-IJ56KL.jpg",
"description": "Buy 1 get 1 free on Tomica cars until 15 November",
"message": "🎁 Tomica ซื้อ 1 แถม 1 ถึง 15 พ.ย. นี้ค่ะ",
"show_message": true
},
{
"type": "products",
"products": [
"TM-001",
"TM-011"
],
"message": "",
"show_message": false
}
],
"marketplaces": {
"shopee": {
"enabled": true,
"text": "สวัสดีค่ะ ยินดีต้อนรับสู่ร้านของเล่นของเราบน Shopee ถามได้ทุกเรื่องเลยค่ะ",
"send_items": true
},
"lazada": {
"enabled": false,
"text": "",
"send_items": false
},
"tiktok": {
"enabled": false,
"text": "",
"send_items": false
}
}
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/bot/playbook#
Replace the chat bot's Playbook.
Use when the owner wants the bot to sell, recommend or talk differently: a new range to push, a delivery promise, a tone.
Before calling:
- Read the current Playbook with
GET /bot. The text you send replaces all of it, so start from the saved text and change only what the owner asked for. - Send with
dry_run: true, show the owner the new text, and only send it for real after they agree.
Effect: the bot's main prompt is rebuilt with the new Playbook, which takes about 20 seconds; the answer comes when the bot has it. Every channel the bot answers uses it from then on. "" clears the Playbook.
Safe to retry: yes. The same text again is unchanged. If the answer is 502, the text was saved but the bot didn't reload: send the same request with reload: true.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
playbook | string | yes | The whole Playbook. Thai or English. Replaces the saved text. (max length 20000) |
reload | boolean | no | Reload the bot even if the text is unchanged (after a 502). (default false) |
dry_run | boolean | no | true: say whether it would change, changing nothing. (default false) |
Request examples
Add a new range to push (dry run first) new_range
{
"dry_run": true,
"playbook": "แนะนำรถเหล็ก Majorette และฟิกเกอร์ Jada ที่มาใหม่ก่อน เมื่อลูกค้าถามหาของขวัญ\nตอบสุภาพ ลงท้ายด้วยค่ะ\nส่งของภายใน 1-2 วันทำการ"
}Response 200
`updated` (and `reloaded`: the bot uses it now) or `unchanged`.
ok
{
"code": 200,
"message": "Playbook updated and the bot reloaded",
"data": {
"dry_run": false,
"status": "updated",
"reloaded": true
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
- 502: The Playbook was saved but the bot couldn't reload it. Send the same request with `reload: true`; if it fails again, tell the owner.
POST/bot/faq#
Add, update or remove FAQ questions and answers (up to 200).
Use when the owner gives you questions and answers for the bot: delivery, payment, returns, opening hours, product care.
How questions are matched: by the question text, ignoring case and extra spaces. A matched question takes the answer you send (and your wording of the question). Its pictures and videos stay.
Modes:
merge(default): adds the new questions at the end and updates the ones that exist; every other question stays.replace: the FAQ becomes exactly the questions you send, in your order; the others areremoved. ReadGET /botfirst and only use it when the owner wants the others gone.
Before calling: send with dry_run: true, show the owner every created, updated and removed row, and only send it for real after they agree.
Effect: the bot answers from the new FAQ on the next message, on every channel it answers. No marketplace listing changes.
Safe to retry: yes. The same rows again are unchanged.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
mode | "merge" | "replace" | no | (default "merge") |
faq | array of object {question, answer} | yes | Each question once (case and spaces don't count). At least one, except with `replace`, where `[]` removes every question. (at most 200 items) |
faq[].question | string | yes | (min length 1) (max length 500) |
faq[].answer | string | yes | (min length 1) (max length 5000) |
dry_run | boolean | no | true: report what would happen, changing nothing. (default false) |
Request examples
Add one question and update another (dry run first) merge
{
"dry_run": true,
"faq": [
{
"question": "ส่งของกี่วันถึง",
"answer": "ส่งภายใน 1-2 วันทำการ ได้รับใน 2-3 วันค่ะ"
},
{
"question": "รับชำระเงินช่องทางไหนบ้าง",
"answer": "โอนผ่านพร้อมเพย์ หรือจ่ายด้วยบัตรผ่านลิงก์ชำระเงินในแชทค่ะ"
}
]
}Make the FAQ exactly these two questions replace
{
"mode": "replace",
"dry_run": true,
"faq": [
{
"question": "ส่งของกี่วันถึง",
"answer": "ส่งภายใน 1-2 วันทำการ ได้รับใน 2-3 วันค่ะ"
},
{
"question": "เปลี่ยนหรือคืนสินค้าได้ไหม",
"answer": "เปลี่ยนได้ภายใน 7 วัน หากสินค้าเสียหายจากการขนส่งค่ะ"
}
]
}Response 200
One row per question sent, plus one per question `removed`. Report every `created`, `updated` and `removed` row to the owner.
ok
{
"code": 200,
"message": "Dry run: nothing was changed",
"data": {
"dry_run": true,
"mode": "merge",
"results": [
{
"question": "ส่งของกี่วันถึง",
"status": "updated",
"changed": [
"answer"
]
},
{
"question": "รับชำระเงินช่องทางไหนบ้าง",
"status": "created"
}
],
"summary": {
"total": 2,
"updated": 1,
"created": 1
},
"faq_count": 5
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/bot/greeting#
Change the greeting new conversations open with (text, then up to 10 items, each with an optional message).
Use when the owner wants a new greeting: the text a customer gets when they start a new conversation on LINE, Facebook, Instagram or the website chat, and the videos, pictures or product cards after it (a sale, new arrivals, how to order). Shopee, Lazada and TikTok Shop each have their own greeting in marketplaces, off until the owner turns it on.
Before calling:
- Read the greeting with
GET /bot. Send only what changes: a field you leave out stays as it is. - New videos and pictures go up first through
POST /bot/greeting/media; send the links it answers. A link the greeting has now can be sent again as it is. - Send with
dry_run: true, show the owner the text and every item (the pictures themselves, not only their links), and only send it for real after they agree.
Fields:
-
enabled: whether the greeting is sent. -
text: a string for every channel, or{line, meta, ig, web}(metais Facebook Messenger,webthe website chat) for the channels named. Up to 1,000 characters each;""sends the shop's Welcome message instead. Facebook and Instagram customers aren't on LINE yet: say there how to add the shop's LINE. -
items: the whole list, in order, up to 10: it replaces the saved items ([]sends the text alone). Each is avideo(withthumbnail_url, its preview picture: LINE shows a video only with one), animage, orproducts(1 to 10 SKUs on the shop's SellerSideKick store, sent as one swipeable set of cards with price and an "Interested" button; a product sold out or without a picture or price is left out). Give each video and image adescriptionof what it shows: the bot reads it (customers don't) to answer questions about it. -
An item's
message(up to 1,000 characters) is sent word for word right after it, e.g. a product's name and sale price under its picture.show_message: falsekeeps the message without sending it; left out, it is on when there is a message. A video or picture a customer already got is skipped with its message. -
marketplaces:{shopee, lazada, tiktok}, each{enabled, text, send_items}: that marketplace's own greeting, off by default. Itstextcan't have links, @ids or other channels' names (the marketplace forbids them);""sends the shop's Welcome message when that has none.send_items: truealso sends the items' pictures and product cards (the marketplace's own cards, one message each, at most 4 per set, only products listed there); never videos or the Shop app card. TikTok Shop's waits for its chat to join SellerSideKick.
How often a customer gets it: the greeting goes with the first message of a new conversation, and again after 7 quiet days. Each video and picture goes to a customer once (sending the same link again keeps that); product cards go every time.
Effect: a LINE reply holds 5 messages (the text, each item and each item's message count one each). What doesn't fit, and the bot's own answer after it, goes out as LINE push messages, which count against the shop's LINE plan. The bot uses the new greeting within a minute.
Safe to retry: yes. The same greeting again is unchanged.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | Send the greeting or not. |
text | string or object {line, meta, ig, web} | no | A string for every channel, or the channels named. |
items | array of object {type, url, thumbnail_url, description, products, message, show_message} | no | The whole list, in order. Replaces the saved items. (at most 10 items) |
items[].type | "video" | "image" | "products" | yes | |
items[].url | string | no | Video or image: a link from POST /bot/greeting/media, or one the greeting has now. (format uri) |
items[].thumbnail_url | string | no | Video only: its preview picture, uploaded the same way. Kept from the greeting when it has this video. (format uri) |
items[].description | string | no | Video or image: what it shows, for the bot. Left out: kept from the greeting when it has this file. (max length 200) |
items[].products | array of string | no | products only: the SKUs, in card order. (at least 1 items) (at most 10 items) |
items[].message | string | no | Sent word for word right after this item. Left out or empty: none. (max length 1000) |
items[].show_message | boolean | no | false keeps `message` without sending it. Left out: true when there is a message. |
marketplaces | object {shopee, lazada, tiktok} | no | Each marketplace's own greeting, off by default. Send the fields that change; the rest stay. Its `text` (up to 1,000 characters) can't have links, @ids or other channels' names, which the marketplace forbids (400 naming them). |
marketplaces.shopee | object {enabled, text, send_items} | no | |
marketplaces.shopee.enabled | boolean | no | |
marketplaces.shopee.text | string | no | (max length 1000) |
marketplaces.shopee.send_items | boolean | no | |
marketplaces.lazada | object {enabled, text, send_items} | no | |
marketplaces.lazada.enabled | boolean | no | |
marketplaces.lazada.text | string | no | (max length 1000) |
marketplaces.lazada.send_items | boolean | no | |
marketplaces.tiktok | object {enabled, text, send_items} | no | |
marketplaces.tiktok.enabled | boolean | no | |
marketplaces.tiktok.text | string | no | (max length 1000) |
marketplaces.tiktok.send_items | boolean | no | |
dry_run | boolean | no | true: report what would change, changing nothing. (default false) |
Request examples
Turn Shopee's own greeting on, with its text and the greeting's pictures and product cards (dry run first) shopee_on
{
"dry_run": true,
"marketplaces": {
"shopee": {
"enabled": true,
"text": "สวัสดีค่ะ ยินดีต้อนรับสู่ร้านของเล่นของเราบน Shopee ถามได้ทุกเรื่องเลยค่ะ",
"send_items": true
}
}
}A new text and four items: the how-to video, a sale picture with a message after it, and two sets of cards (dry run first) new_greeting
{
"dry_run": true,
"text": {
"line": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง หรือส่งรูปของเล่นที่ตามหามาได้เลยค่ะ",
"meta": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ",
"ig": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ"
},
"items": [
{
"type": "video",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-AB12CD.mp4",
"thumbnail_url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-frame-EF34GH.jpg",
"description": "How to chat with the bot and order in the LINE Mini App",
"message": "",
"show_message": false
},
{
"type": "image",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/sale-1free1-IJ56KL.jpg",
"description": "Buy 1 get 1 free on Tomica cars until 15 November",
"message": "🎁 Tomica ซื้อ 1 แถม 1 ถึง 15 พ.ย. นี้ค่ะ",
"show_message": true
},
{
"type": "products",
"products": [
"TM-001",
"TM-011"
],
"message": "",
"show_message": false
},
{
"type": "products",
"products": [
"TM-021"
]
}
]
}Change only the Facebook text text_only
{
"dry_run": true,
"text": {
"meta": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ"
}
}Stop sending it (the text and items are kept) off
{
"enabled": false
}Response 200
`updated` with the fields that change, or `unchanged`, and the greeting as it is now (would be, on a dry run).
ok
{
"code": 200,
"message": "Dry run: nothing was changed",
"data": {
"dry_run": true,
"status": "updated",
"changed": [
"text.line",
"text.meta",
"text.ig",
"items"
],
"greeting": {
"enabled": true,
"text": {
"line": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง หรือส่งรูปของเล่นที่ตามหามาได้เลยค่ะ",
"meta": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ",
"ig": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ ถามได้ทุกเรื่อง แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ"
},
"items": [
{
"type": "video",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-AB12CD.mp4",
"thumbnail_url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/how-to-chat-frame-EF34GH.jpg",
"description": "How to chat with the bot and order in the LINE Mini App",
"message": "",
"show_message": false
},
{
"type": "image",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/sale-1free1-IJ56KL.jpg",
"description": "Buy 1 get 1 free on Tomica cars until 15 November",
"message": "🎁 Tomica ซื้อ 1 แถม 1 ถึง 15 พ.ย. นี้ค่ะ",
"show_message": true
},
{
"type": "products",
"products": [
"TM-001",
"TM-011"
],
"message": "",
"show_message": false
}
],
"marketplaces": {
"shopee": {
"enabled": true,
"text": "สวัสดีค่ะ ยินดีต้อนรับสู่ร้านของเล่นของเราบน Shopee ถามได้ทุกเรื่องเลยค่ะ",
"send_items": true
},
"lazada": {
"enabled": false,
"text": "",
"send_items": false
},
"tiktok": {
"enabled": false,
"text": "",
"send_items": false
}
}
}
}
}Errors
- 400: A field is wrong, a file isn't a greeting upload, or a SKU isn't the shop's. The message says which.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/bot/greeting/media#
Upload a video, its preview picture or a picture for the greeting, and get its link.
Use when the greeting needs a new video or picture: upload the file here, then put the link this answers in an item of POST /bot/greeting.
How: a multipart/form-data request with one file in the field file: an MP4 video of at most 25 MB, or a JPEG, PNG or WebP picture of at most 8 MB (the most Facebook and Instagram accept; WebP is saved as JPEG). A video also needs its preview picture: upload a frame of it the same way and send it as the item's thumbnail_url.
Effect: stores the file on SellerSideKick. It is sent to no one until the greeting names it.
Safe to retry: yes, but each upload stores a new copy with a new link; use the link from the one that succeeded.
Response 200
The stored file: put `url` in a greeting item (a picture as a video's `thumbnail_url`).
ok
{
"code": 200,
"message": "File uploaded",
"data": {
"type": "image",
"title": "sale-1free1.jpg",
"url": "https://seller-side.sgp1.digitaloceanspaces.com/welcome/sale-1free1-IJ56KL.jpg"
}
}Errors
- 400: No file, more than one, too large, or not an MP4, JPEG, PNG or WebP. The message says which.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Loyalty
The shop's loyalty program (points, stamps, store credit, tiers): its settings, rewards, members and redemptions.
GET/loyalty/templates#
The presets a loyalty program starts from.
Use before creating a program to pick the preset closest to what the owner describes: classic points, a stamp card, store credit (cashback), VIP tiers, visit rewards, or blank. Each shows the full settings it starts with, so you can change only what differs.
Changes nothing.
Response 200
Every preset with its settings and rewards.
ok
{
"code": 200,
"message": "OK",
"data": {
"templates": [
{
"key": "classic_points",
"name": {
"en": "Classic points",
"th": "สะสมแต้มคลาสสิก"
},
"description": {
"en": "Earn points on every purchase and convert them into discount vouchers.",
"th": "รับแต้มทุกยอดซื้อ แล้วแลกเป็นคูปองส่วนลด"
},
"best_for": [
"retail",
"ecommerce"
],
"program": {
"name": "Points",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"earning": {
"accrual_event": "order_paid",
"hold_days": 7,
"base_amount": "price_net",
"exclude_shipping": true,
"rounding": "floor",
"channels": [],
"min_order_amount": 0,
"max_units_per_order": null,
"backfill_from": null,
"rules": [
{
"id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"enabled": true,
"type": "per_spend",
"units": 1,
"per_amount": 20,
"factor": null,
"max_units": null,
"conditions": {}
}
]
},
"redemption": {
"enabled": true,
"exchange": {
"enabled": true,
"units": 100,
"value": 10,
"step_units": 100,
"min_units": 100,
"max_units_per_redemption": 2000,
"voucher_valid_days": 30,
"voucher_min_order_amount": 0
}
},
"tiers": {
"enabled": false,
"basis": "period_units",
"period_months": 12,
"downgrade": "on_period_end",
"levels": []
},
"expiry": {
"mode": "fixed_months",
"months": 12,
"year_offset": 1
},
"enrollment": {
"mode": "auto",
"welcome_units": 0,
"terms": ""
}
},
"rewards": []
}
]
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/loyalty/program#
The shop's loyalty program and how it is doing.
Use first for any loyalty task: it says whether the shop has a program (program: null if not), its settings and status, and a summary (members, units outstanding, the last 30 days).
Changes nothing.
Response 200
The program and its summary, or both null.
ok
{
"code": 200,
"message": "OK",
"data": {
"program": {
"id": "6650f0c2a1b2c3d4e5f60720",
"status": "active",
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"description": "สะสมแต้มทุกการสั่งซื้อทาง LINE และ Facebook",
"timezone": "Asia/Bangkok",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"earning": {
"accrual_event": "order_paid",
"hold_days": 7,
"base_amount": "price_net",
"exclude_shipping": true,
"rounding": "floor",
"channels": [],
"min_order_amount": 0,
"max_units_per_order": null,
"backfill_from": null,
"rules": [
{
"id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"enabled": true,
"type": "per_spend",
"units": 1,
"per_amount": 20,
"factor": null,
"max_units": null,
"conditions": {}
}
]
},
"redemption": {
"enabled": true,
"exchange": {
"enabled": true,
"units": 100,
"value": 10,
"step_units": 100,
"min_units": 100,
"max_units_per_redemption": 2000,
"voucher_valid_days": 30,
"voucher_min_order_amount": 0
}
},
"tiers": {
"enabled": false,
"basis": "period_units",
"period_months": 12,
"downgrade": "on_period_end",
"levels": []
},
"expiry": {
"mode": "fixed_months",
"months": 12,
"year_offset": 1
},
"enrollment": {
"mode": "auto",
"welcome_units": 0,
"terms": ""
},
"customer_access": {
"bot": false,
"mini_app": false
},
"activated_at": "2026-11-02T03:05:00.000Z",
"paused_at": null,
"created_at": "2026-11-02T03:00:00.000Z",
"updated_at": "2026-11-02T03:00:00.000Z"
},
"summary": {
"program": {
"_id": "6650f0c2a1b2c3d4e5f60720",
"name": "นิชิ พอยท์",
"status": "active",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"activated_at": "2026-11-02T03:05:00.000Z"
},
"members": {
"total": 128,
"active_30d": 41
},
"units": {
"balance_outstanding": 18240,
"pending_outstanding": 960,
"lifetime_earned": 21900,
"lifetime_redeemed": 3500,
"lifetime_expired": 160,
"liability_value": 1824
},
"last_30d": {
"earned": 7210,
"earn_events": 163,
"redeemed": 1500,
"redeem_events": 3,
"expired": 0,
"reversed": 90,
"adjusted": 100
},
"redemptions": {
"issued": 4,
"used": 9,
"fulfilled": 1,
"cancelled": 1,
"expired": 0
},
"rewards": {
"active": 3
},
"tiers": [],
"generated_at": "2026-11-20T10:00:00.000Z"
}
}
} none
{
"code": 200,
"message": "This shop has no loyalty program yet",
"data": {
"program": null,
"summary": null
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/program#
Create the shop's loyalty program from a preset.
Use when the shop has no program yet (GET /loyalty/program answers program: null). Name a preset in template_key and send only the sections that differ; a section you send replaces the preset's whole section, so send it complete (read it from GET /loyalty/templates).
- It starts as
draft(earning nothing) unless you sendstatus: "active". Switch it on withPOST /loyalty/program/statusonce the owner has checked it. seed_rewards(default true) adds the preset's rewards.- A shop has one program: a second is
409 LOYALTY_PROGRAM_EXISTS(archive the old one first).
Before calling: show the owner the settings and get a clear yes.
Safe to retry: yes — a repeat is refused with 409 and changes nothing.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
template_key | "classic_points" | "stamp_card" | "cashback_credit" | "vip_tiers" | "visit_rewards" | "blank" | no | |
seed_rewards | boolean | no | (default true) |
status | "draft" | "active" | no | (default "draft") |
name | string | no | The program's name, as the shop calls it (Thai is fine). (max length 80) |
description | string | no | (max length 1000) |
timezone | string | no | Where days and expiry dates are counted. Default Asia/Bangkok. |
currency | object {kind, name, singular_name, decimals, card_size} | no | What members collect. |
currency.kind | "points" | "stamps" | "credit" | no | |
currency.name | string | no | |
currency.singular_name | string | no | |
currency.decimals | integer | no | (min 0) (max 2) |
currency.card_size | integer | null | no | stamps only: stamps on a full card. |
earning | object {accrual_event, hold_days, base_amount, exclude_shipping, rounding, channels, min_order_amount, max_units_per_order, backfill_from, rules} | no | How orders earn. Rules add up; then the highest matching multiplier, then the tier's multiplier, then `max_units_per_order`. |
earning.accrual_event | "order_paid" | "order_fulfilled" | no | Earn when the order is paid, or only once it is fulfilled. |
earning.hold_days | integer | no | Earned units wait this many days (a return window) before they can be spent. (min 0) |
earning.base_amount | "price_net" | "price_total" | no | |
earning.exclude_shipping | boolean | no | |
earning.rounding | "floor" | "round" | "ceil" | no | |
earning.channels | array of "line" | "meta" | "facebook" | "ig" | "direct" | no | Only orders from these channels. Shopee, Lazada and TikTok orders never earn. |
earning.min_order_amount | number | no | (min 0) |
earning.max_units_per_order | number | null | no | |
earning.backfill_from | string | null | no | Orders from this date earn; default: from when the program is switched on. (format date-time) |
earning.rules | array of object {id, name, enabled, type, units, per_amount, factor, max_units, conditions} | no | |
earning.rules[].id | string | no | |
earning.rules[].name | string | yes | (max length 120) |
earning.rules[].enabled | boolean | no | (default true) |
earning.rules[].type | "per_spend" | "per_order" | "per_item" | "first_order" | "multiplier" | yes | per_spend: `units` for every `per_amount` THB · per_order: `units` per order · per_item: `units` per item · first_order: `units` on a member's first order · multiplier: × `factor` on the rest (the highest one that matches applies, then the tier's). |
earning.rules[].units | number | no | (min 0) |
earning.rules[].per_amount | number | null | no | per_spend only: the THB that earns `units`. |
earning.rules[].factor | number | null | no | multiplier only. (min 1) (max 100) |
earning.rules[].max_units | number | null | no | Most this rule gives on one order; null = no cap. |
earning.rules[].conditions | object {channels, product_uuids, categories, brands, min_order_amount, tiers, start_at, end_at, days_of_week} | no | When a rule applies. Every field is optional; empty means no limit. |
earning.rules[].conditions.channels | array of "line" | "meta" | "facebook" | "ig" | "direct" | no | Only orders from these channels. Shopee, Lazada and TikTok orders never earn. |
earning.rules[].conditions.product_uuids | array of string | no | |
earning.rules[].conditions.categories | array of string | no | |
earning.rules[].conditions.brands | array of string | no | |
earning.rules[].conditions.min_order_amount | number | null | no | |
earning.rules[].conditions.tiers | array of string | no | Only members holding one of these tier keys. |
earning.rules[].conditions.start_at | string | null | no | (format date-time) |
earning.rules[].conditions.end_at | string | null | no | (format date-time) |
earning.rules[].conditions.days_of_week | array of integer | no | 0 = Sunday, in the program's time zone. |
redemption | object {enabled, exchange} | no | Turning units into a voucher at a fixed rate (`exchange`), beside the reward catalogue. |
redemption.enabled | boolean | no | |
redemption.exchange | object {enabled, units, value, step_units, min_units, max_units_per_redemption, voucher_valid_days, voucher_min_order_amount} | no | |
redemption.exchange.enabled | boolean | no | |
redemption.exchange.units | number | no | `units` buy a voucher worth `value` THB. |
redemption.exchange.value | number | no | |
redemption.exchange.step_units | number | no | |
redemption.exchange.min_units | number | no | |
redemption.exchange.max_units_per_redemption | number | null | no | |
redemption.exchange.voucher_valid_days | integer | no | (min 1) (max 365) |
redemption.exchange.voucher_min_order_amount | number | no | (min 0) |
tiers | object {enabled, basis, period_months, downgrade, levels} | no | |
tiers.enabled | boolean | no | |
tiers.basis | "lifetime_units" | "period_units" | "period_spend" | "order_count" | no | |
tiers.period_months | integer | no | (min 1) (max 60) |
tiers.downgrade | "never" | "on_period_end" | no | |
tiers.levels | array of object {key, name, threshold, multiplier, benefits, color} | no | |
tiers.levels[].key | string | yes | (pattern `^[a-z0-9_-]+$`) |
tiers.levels[].name | string | yes | |
tiers.levels[].threshold | number | yes | |
tiers.levels[].multiplier | number | no | (min 1) (max 100) |
tiers.levels[].benefits | array of string | no | Words shown to members; only `multiplier`, tier-only rewards and rules act on them. |
tiers.levels[].color | string | no | |
expiry | object {mode, months, year_offset} | no | |
expiry.mode | "never" | "fixed_months" | "end_of_year" | "inactivity" | no | |
expiry.months | integer | no | (min 1) (max 120) |
expiry.year_offset | integer | no | (min 0) (max 5) |
enrollment | object {mode, welcome_units, terms} | no | |
enrollment.mode | "auto" | "explicit" | no | auto: a customer joins on their first paid order · explicit: staff enrol them. |
enrollment.welcome_units | number | no | (min 0) |
enrollment.terms | string | no | (max length 5000) |
Request examples
classic_points
{
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"description": "สะสมแต้มทุกการสั่งซื้อทาง LINE และ Facebook"
} stamp_card
{
"template_key": "stamp_card",
"name": "บัตรสะสมแสตมป์",
"status": "draft"
} custom_rate
{
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"earning": {
"accrual_event": "order_paid",
"hold_days": 7,
"base_amount": "price_net",
"exclude_shipping": true,
"rounding": "floor",
"channels": [],
"min_order_amount": 0,
"max_units_per_order": null,
"backfill_from": null,
"rules": [
{
"id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"enabled": true,
"type": "per_spend",
"units": 1,
"per_amount": 20,
"factor": null,
"max_units": null,
"conditions": {}
}
]
}
}Response 201
The new program.
created
{
"code": 201,
"message": "Loyalty program created",
"data": {
"program": {
"id": "6650f0c2a1b2c3d4e5f60720",
"status": "draft",
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"description": "สะสมแต้มทุกการสั่งซื้อทาง LINE และ Facebook",
"timezone": "Asia/Bangkok",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"earning": {
"accrual_event": "order_paid",
"hold_days": 7,
"base_amount": "price_net",
"exclude_shipping": true,
"rounding": "floor",
"channels": [],
"min_order_amount": 0,
"max_units_per_order": null,
"backfill_from": null,
"rules": [
{
"id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"enabled": true,
"type": "per_spend",
"units": 1,
"per_amount": 20,
"factor": null,
"max_units": null,
"conditions": {}
}
]
},
"redemption": {
"enabled": true,
"exchange": {
"enabled": true,
"units": 100,
"value": 10,
"step_units": 100,
"min_units": 100,
"max_units_per_redemption": 2000,
"voucher_valid_days": 30,
"voucher_min_order_amount": 0
}
},
"tiers": {
"enabled": false,
"basis": "period_units",
"period_months": 12,
"downgrade": "on_period_end",
"levels": []
},
"expiry": {
"mode": "fixed_months",
"months": 12,
"year_offset": 1
},
"enrollment": {
"mode": "auto",
"welcome_units": 0,
"terms": ""
},
"customer_access": {
"bot": false,
"mini_app": false
},
"activated_at": null,
"paused_at": null,
"created_at": "2026-11-02T03:00:00.000Z",
"updated_at": "2026-11-02T03:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 409: The shop already has a program. Read it with GET /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
PATCH/loyalty/program#
Change the program's settings, section by section.
Use to change how members earn, redeem, rank or lose units. Send only the sections that change (name, description, timezone, currency, earning, redemption, tiers, expiry, enrollment); each one you send replaces that whole section, so read it first from GET /loyalty/program and send it back complete with your change.
- A change applies to orders from now on; units already earned keep their own expiry.
- Check a new earning setup first with
POST /loyalty/program/simulate.
Before calling: show the owner what changes and get a clear yes.
Safe to retry: yes — the same body sets the same settings.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | The program's name, as the shop calls it (Thai is fine). (max length 80) |
description | string | no | (max length 1000) |
timezone | string | no | Where days and expiry dates are counted. Default Asia/Bangkok. |
currency | object {kind, name, singular_name, decimals, card_size} | no | What members collect. |
currency.kind | "points" | "stamps" | "credit" | no | |
currency.name | string | no | |
currency.singular_name | string | no | |
currency.decimals | integer | no | (min 0) (max 2) |
currency.card_size | integer | null | no | stamps only: stamps on a full card. |
earning | object {accrual_event, hold_days, base_amount, exclude_shipping, rounding, channels, min_order_amount, max_units_per_order, backfill_from, rules} | no | How orders earn. Rules add up; then the highest matching multiplier, then the tier's multiplier, then `max_units_per_order`. |
earning.accrual_event | "order_paid" | "order_fulfilled" | no | Earn when the order is paid, or only once it is fulfilled. |
earning.hold_days | integer | no | Earned units wait this many days (a return window) before they can be spent. (min 0) |
earning.base_amount | "price_net" | "price_total" | no | |
earning.exclude_shipping | boolean | no | |
earning.rounding | "floor" | "round" | "ceil" | no | |
earning.channels | array of "line" | "meta" | "facebook" | "ig" | "direct" | no | Only orders from these channels. Shopee, Lazada and TikTok orders never earn. |
earning.min_order_amount | number | no | (min 0) |
earning.max_units_per_order | number | null | no | |
earning.backfill_from | string | null | no | Orders from this date earn; default: from when the program is switched on. (format date-time) |
earning.rules | array of object {id, name, enabled, type, units, per_amount, factor, max_units, conditions} | no | |
earning.rules[].id | string | no | |
earning.rules[].name | string | yes | (max length 120) |
earning.rules[].enabled | boolean | no | (default true) |
earning.rules[].type | "per_spend" | "per_order" | "per_item" | "first_order" | "multiplier" | yes | per_spend: `units` for every `per_amount` THB · per_order: `units` per order · per_item: `units` per item · first_order: `units` on a member's first order · multiplier: × `factor` on the rest (the highest one that matches applies, then the tier's). |
earning.rules[].units | number | no | (min 0) |
earning.rules[].per_amount | number | null | no | per_spend only: the THB that earns `units`. |
earning.rules[].factor | number | null | no | multiplier only. (min 1) (max 100) |
earning.rules[].max_units | number | null | no | Most this rule gives on one order; null = no cap. |
earning.rules[].conditions | object {channels, product_uuids, categories, brands, min_order_amount, tiers, start_at, end_at, days_of_week} | no | When a rule applies. Every field is optional; empty means no limit. |
earning.rules[].conditions.channels | array of "line" | "meta" | "facebook" | "ig" | "direct" | no | Only orders from these channels. Shopee, Lazada and TikTok orders never earn. |
earning.rules[].conditions.product_uuids | array of string | no | |
earning.rules[].conditions.categories | array of string | no | |
earning.rules[].conditions.brands | array of string | no | |
earning.rules[].conditions.min_order_amount | number | null | no | |
earning.rules[].conditions.tiers | array of string | no | Only members holding one of these tier keys. |
earning.rules[].conditions.start_at | string | null | no | (format date-time) |
earning.rules[].conditions.end_at | string | null | no | (format date-time) |
earning.rules[].conditions.days_of_week | array of integer | no | 0 = Sunday, in the program's time zone. |
redemption | object {enabled, exchange} | no | Turning units into a voucher at a fixed rate (`exchange`), beside the reward catalogue. |
redemption.enabled | boolean | no | |
redemption.exchange | object {enabled, units, value, step_units, min_units, max_units_per_redemption, voucher_valid_days, voucher_min_order_amount} | no | |
redemption.exchange.enabled | boolean | no | |
redemption.exchange.units | number | no | `units` buy a voucher worth `value` THB. |
redemption.exchange.value | number | no | |
redemption.exchange.step_units | number | no | |
redemption.exchange.min_units | number | no | |
redemption.exchange.max_units_per_redemption | number | null | no | |
redemption.exchange.voucher_valid_days | integer | no | (min 1) (max 365) |
redemption.exchange.voucher_min_order_amount | number | no | (min 0) |
tiers | object {enabled, basis, period_months, downgrade, levels} | no | |
tiers.enabled | boolean | no | |
tiers.basis | "lifetime_units" | "period_units" | "period_spend" | "order_count" | no | |
tiers.period_months | integer | no | (min 1) (max 60) |
tiers.downgrade | "never" | "on_period_end" | no | |
tiers.levels | array of object {key, name, threshold, multiplier, benefits, color} | no | |
tiers.levels[].key | string | yes | (pattern `^[a-z0-9_-]+$`) |
tiers.levels[].name | string | yes | |
tiers.levels[].threshold | number | yes | |
tiers.levels[].multiplier | number | no | (min 1) (max 100) |
tiers.levels[].benefits | array of string | no | Words shown to members; only `multiplier`, tier-only rewards and rules act on them. |
tiers.levels[].color | string | no | |
expiry | object {mode, months, year_offset} | no | |
expiry.mode | "never" | "fixed_months" | "end_of_year" | "inactivity" | no | |
expiry.months | integer | no | (min 1) (max 120) |
expiry.year_offset | integer | no | (min 0) (max 5) |
enrollment | object {mode, welcome_units, terms} | no | |
enrollment.mode | "auto" | "explicit" | no | auto: a customer joins on their first paid order · explicit: staff enrol them. |
enrollment.welcome_units | number | no | (min 0) |
enrollment.terms | string | no | (max length 5000) |
Request examples
rename
{
"name": "นิชิ คลับ",
"description": "สะสมแต้ม แลกส่วนลด"
} expiry
{
"expiry": {
"mode": "end_of_year",
"months": 12,
"year_offset": 1
}
}Response 200
The program as saved.
ok
{
"code": 200,
"message": "Loyalty program updated",
"data": {
"program": {
"id": "6650f0c2a1b2c3d4e5f60720",
"status": "active",
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"description": "สะสมแต้มทุกการสั่งซื้อทาง LINE และ Facebook",
"timezone": "Asia/Bangkok",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"earning": {
"accrual_event": "order_paid",
"hold_days": 7,
"base_amount": "price_net",
"exclude_shipping": true,
"rounding": "floor",
"channels": [],
"min_order_amount": 0,
"max_units_per_order": null,
"backfill_from": null,
"rules": [
{
"id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"enabled": true,
"type": "per_spend",
"units": 1,
"per_amount": 20,
"factor": null,
"max_units": null,
"conditions": {}
}
]
},
"redemption": {
"enabled": true,
"exchange": {
"enabled": true,
"units": 100,
"value": 10,
"step_units": 100,
"min_units": 100,
"max_units_per_redemption": 2000,
"voucher_valid_days": 30,
"voucher_min_order_amount": 0
}
},
"tiers": {
"enabled": false,
"basis": "period_units",
"period_months": 12,
"downgrade": "on_period_end",
"levels": []
},
"expiry": {
"mode": "fixed_months",
"months": 12,
"year_offset": 1
},
"enrollment": {
"mode": "auto",
"welcome_units": 0,
"terms": ""
},
"customer_access": {
"bot": false,
"mini_app": false
},
"activated_at": null,
"paused_at": null,
"created_at": "2026-11-02T03:00:00.000Z",
"updated_at": "2026-11-02T03:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/program/status#
Switch the program on, pause it, or end it.
Use when the owner wants the program to start earning (active), stop for a while (paused: orders meanwhile earn nothing) or end for good (archived). From draft: active or archived; from active: paused or archived; from paused: active or archived; archived is final.
- Switching on starts earning on orders paid from then on (or from
earning.backfill_from). - Archiving keeps every member and their history; a new program can then be created.
Before calling: confirm with the owner, especially before archived.
Safe to retry: yes — the same status again is refused with 400 and changes nothing.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
status | "active" | "paused" | "archived" | yes |
Request examples
switch_on
{
"status": "active"
} pause
{
"status": "paused"
}Response 200
The program with its new status.
ok
{
"code": 200,
"message": "Loyalty program active",
"data": {
"program": {
"id": "6650f0c2a1b2c3d4e5f60720",
"status": "active",
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"description": "สะสมแต้มทุกการสั่งซื้อทาง LINE และ Facebook",
"timezone": "Asia/Bangkok",
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"earning": {
"accrual_event": "order_paid",
"hold_days": 7,
"base_amount": "price_net",
"exclude_shipping": true,
"rounding": "floor",
"channels": [],
"min_order_amount": 0,
"max_units_per_order": null,
"backfill_from": null,
"rules": [
{
"id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"enabled": true,
"type": "per_spend",
"units": 1,
"per_amount": 20,
"factor": null,
"max_units": null,
"conditions": {}
}
]
},
"redemption": {
"enabled": true,
"exchange": {
"enabled": true,
"units": 100,
"value": 10,
"step_units": 100,
"min_units": 100,
"max_units_per_redemption": 2000,
"voucher_valid_days": 30,
"voucher_min_order_amount": 0
}
},
"tiers": {
"enabled": false,
"basis": "period_units",
"period_months": 12,
"downgrade": "on_period_end",
"levels": []
},
"expiry": {
"mode": "fixed_months",
"months": 12,
"year_offset": 1
},
"enrollment": {
"mode": "auto",
"welcome_units": 0,
"terms": ""
},
"customer_access": {
"bot": false,
"mini_app": false
},
"activated_at": null,
"paused_at": null,
"created_at": "2026-11-02T03:00:00.000Z",
"updated_at": "2026-11-02T03:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/program/simulate#
What an order would earn under the program now.
Use before switching a program on or changing its earning, to show the owner what typical orders earn: send the lines of an example order. The answer lists each rule's units, the multiplier and the total.
Changes nothing. Safe to retry: yes.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
channel | "line" | "meta" | "facebook" | "ig" | "direct" | no | (default "line") |
price_delivery | number | no | (min 0) (default 0) |
discount | number | no | (min 0) (default 0) |
lines | array of object {uuid, name, category, brand, unit_price, qty} | yes | (at least 1 items) (at most 50 items) |
lines[].uuid | string | no | |
lines[].name | string | no | |
lines[].category | string or array of string | no | |
lines[].brand | string | no | |
lines[].unit_price | number | yes | (min 0) |
lines[].qty | integer | no | (min 1) (default 1) |
Request examples
toy_order
{
"channel": "line",
"price_delivery": 50,
"lines": [
{
"name": "รถเหล็กโทมิก้า",
"brand": "Tomica",
"category": "Toys",
"unit_price": 129,
"qty": 3
},
{
"name": "ฟิกเกอร์ Blokees",
"brand": "Blokees",
"unit_price": 590,
"qty": 1
}
]
}Response 200
The units the order would earn, and why.
ok
{
"code": 200,
"message": "Simulation: nothing was changed",
"data": {
"eligible": true,
"reason": null,
"units": 48,
"base_amount": 977,
"breakdown": [
{
"rule_id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"type": "per_spend",
"units": 48
}
],
"multiplier": {
"factor": 1,
"rule_id": null,
"tier_factor": 1,
"total": 1
},
"display": "48 แต้ม",
"order": {
"price_total": 977,
"price_discount": 0,
"price_delivery": 50,
"price_net": 1027,
"channel": "line"
},
"member": null
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/program/test#
Test the program with an imaginary customer's story.
Use to check the program works the way the owner expects, before switching it on or after a change: describe what a customer does (orders, waits, refunds, redemptions) and what should follow (expect). The answer replays each step through the program, with what was earned, held, released, taken back, expired, tier changes and vouchers, and passes or fails each expectation.
- Test the saved program, settings you're about to save (program, rewards), or a preset (template_key, no program needed).
- A program that isn't on is tested as if it were (tested.as_if_active).
- A step the program would refuse comes back with refused and changes nothing; the story goes on.
- Vouchers are TEST-nn: they exist only in the answer.
Changes nothing: no customer, member, unit or voucher is made. Safe to retry: yes.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
template_key | "classic_points" | "stamp_card" | "cashback_credit" | "vip_tiers" | "visit_rewards" | "blank" | no | Test a preset instead of the shop's program (no program needed). |
program | object {name, description, timezone, currency, earning, redemption, tiers, expiry, enrollment} | no | Settings to try in place of the saved ones, section by section as PATCH /loyalty/program takes them (each section whole). Not saved. |
program.name | string | no | The program's name, as the shop calls it (Thai is fine). (max length 80) |
program.description | string | no | (max length 1000) |
program.timezone | string | no | Where days and expiry dates are counted. Default Asia/Bangkok. |
program.currency | object {kind, name, singular_name, decimals, card_size} | no | What members collect. |
program.currency.kind | "points" | "stamps" | "credit" | no | |
program.currency.name | string | no | |
program.currency.singular_name | string | no | |
program.currency.decimals | integer | no | (min 0) (max 2) |
program.currency.card_size | integer | null | no | stamps only: stamps on a full card. |
program.earning | object {accrual_event, hold_days, base_amount, exclude_shipping, rounding, channels, min_order_amount, max_units_per_order, backfill_from, rules} | no | How orders earn. Rules add up; then the highest matching multiplier, then the tier's multiplier, then `max_units_per_order`. |
program.earning.accrual_event | "order_paid" | "order_fulfilled" | no | Earn when the order is paid, or only once it is fulfilled. |
program.earning.hold_days | integer | no | Earned units wait this many days (a return window) before they can be spent. (min 0) |
program.earning.base_amount | "price_net" | "price_total" | no | |
program.earning.exclude_shipping | boolean | no | |
program.earning.rounding | "floor" | "round" | "ceil" | no | |
program.earning.channels | array of "line" | "meta" | "facebook" | "ig" | "direct" | no | Only orders from these channels. Shopee, Lazada and TikTok orders never earn. |
program.earning.min_order_amount | number | no | (min 0) |
program.earning.max_units_per_order | number | null | no | |
program.earning.backfill_from | string | null | no | Orders from this date earn; default: from when the program is switched on. (format date-time) |
program.earning.rules | array of object {id, name, enabled, type, units, per_amount, factor, max_units, conditions} | no | |
program.earning.rules[].id | string | no | |
program.earning.rules[].name | string | yes | (max length 120) |
program.earning.rules[].enabled | boolean | no | (default true) |
program.earning.rules[].type | "per_spend" | "per_order" | "per_item" | "first_order" | "multiplier" | yes | per_spend: `units` for every `per_amount` THB · per_order: `units` per order · per_item: `units` per item · first_order: `units` on a member's first order · multiplier: × `factor` on the rest (the highest one that matches applies, then the tier's). |
program.earning.rules[].units | number | no | (min 0) |
program.earning.rules[].per_amount | number | null | no | per_spend only: the THB that earns `units`. |
program.earning.rules[].factor | number | null | no | multiplier only. (min 1) (max 100) |
program.earning.rules[].max_units | number | null | no | Most this rule gives on one order; null = no cap. |
program.earning.rules[].conditions | object {channels, product_uuids, categories, brands, min_order_amount, tiers, start_at, end_at, days_of_week} | no | When a rule applies. Every field is optional; empty means no limit. |
program.redemption | object {enabled, exchange} | no | Turning units into a voucher at a fixed rate (`exchange`), beside the reward catalogue. |
program.redemption.enabled | boolean | no | |
program.redemption.exchange | object {enabled, units, value, step_units, min_units, max_units_per_redemption, voucher_valid_days, voucher_min_order_amount} | no | |
program.redemption.exchange.enabled | boolean | no | |
program.redemption.exchange.units | number | no | `units` buy a voucher worth `value` THB. |
program.redemption.exchange.value | number | no | |
program.redemption.exchange.step_units | number | no | |
program.redemption.exchange.min_units | number | no | |
program.redemption.exchange.max_units_per_redemption | number | null | no | |
program.redemption.exchange.voucher_valid_days | integer | no | (min 1) (max 365) |
program.redemption.exchange.voucher_min_order_amount | number | no | (min 0) |
program.tiers | object {enabled, basis, period_months, downgrade, levels} | no | |
program.tiers.enabled | boolean | no | |
program.tiers.basis | "lifetime_units" | "period_units" | "period_spend" | "order_count" | no | |
program.tiers.period_months | integer | no | (min 1) (max 60) |
program.tiers.downgrade | "never" | "on_period_end" | no | |
program.tiers.levels | array of object {key, name, threshold, multiplier, benefits, color} | no | |
program.tiers.levels[].key | string | yes | (pattern `^[a-z0-9_-]+$`) |
program.tiers.levels[].name | string | yes | |
program.tiers.levels[].threshold | number | yes | |
program.tiers.levels[].multiplier | number | no | (min 1) (max 100) |
program.tiers.levels[].benefits | array of string | no | Words shown to members; only `multiplier`, tier-only rewards and rules act on them. |
program.tiers.levels[].color | string | no | |
program.expiry | object {mode, months, year_offset} | no | |
program.expiry.mode | "never" | "fixed_months" | "end_of_year" | "inactivity" | no | |
program.expiry.months | integer | no | (min 1) (max 120) |
program.expiry.year_offset | integer | no | (min 0) (max 5) |
program.enrollment | object {mode, welcome_units, terms} | no | |
program.enrollment.mode | "auto" | "explicit" | no | auto: a customer joins on their first paid order · explicit: staff enrol them. |
program.enrollment.welcome_units | number | no | (min 0) |
program.enrollment.terms | string | no | (max length 5000) |
rewards | array of object {id, name, description, type, value, max_discount_amount, product, cost_units, trigger, threshold_units, tier_required, stock, max_per_member, voucher_valid_days, min_order_amount, status} | no | Rewards to try in place of the saved ones. Not saved. (at most 30 items) |
rewards[].id | string | no | |
rewards[].name | string | no | (max length 120) |
rewards[].description | string | no | (max length 1000) |
rewards[].type | "discount_fixed" | "discount_percent" | "free_product" | "custom" | no | discount_fixed: `value` THB off · discount_percent: `value`% off (cap with `max_discount_amount`) · free_product: a voucher worth the product's price at redemption · custom: handed over by staff. |
rewards[].value | number | no | (min 0) |
rewards[].max_discount_amount | number | null | no | |
rewards[].product | object {uuid, name, price} | no | free_product only: one of the shop's own products (its uuid from GET /products); another shop's is refused with 400 LOYALTY_REWARD_PRODUCT_NOT_FOUND. |
rewards[].product.uuid | string | no | |
rewards[].product.name | string | no | |
rewards[].product.price | number | null | no | |
rewards[].cost_units | number | no | (min 0) |
rewards[].trigger | "redeem" | "threshold" | no | redeem: the member chooses it · threshold: issued by itself once the balance reaches `threshold_units` (a full stamp card). |
rewards[].threshold_units | number | null | no | |
rewards[].tier_required | string | null | no | A tier key, or null for every member. |
rewards[].stock | integer | null | no | How many are left; null = no limit. |
rewards[].max_per_member | integer | null | no | |
rewards[].voucher_valid_days | integer | no | (min 1) (max 365) |
rewards[].min_order_amount | number | no | (min 0) |
rewards[].status | "active" | "inactive" | "archived" | no | |
start_at | string | no | When the story starts; default now. Rule dates, weekdays and expiry follow it. (format date-time) |
customer | object {enrolled, tier, balance, order_count, status} | no | Who the story starts with. Omitted: someone who has never ordered. |
customer.enrolled | boolean | no | (default true) |
customer.tier | string | null | no | |
customer.balance | number | no | |
customer.order_count | integer | no | |
customer.status | "active" | "suspended" | no | |
steps | array of object {type, label, amount, lines, discount, delivery, channel, status, repeat, every_days, use_voucher_from_step, order_step, occurrence, days, months, until, reward, units, redemption_step, reason, expect} | yes | (at least 1 items) (at most 50 items) |
steps[].type | "order" | "order_status" | "wait" | "redeem" | "cancel_redemption" | "adjust" | "enroll" | "member_status" | yes | order: the customer orders · order_status: an earlier order is fulfilled, cancelled or refunded · wait: time passes (holds end, units expire, tier periods close, vouchers lapse) · redeem: a reward, or units turned into a voucher · cancel_redemption · adjust: staff add or take units · enroll: staff enrol the customer · member_status: suspend or reactivate. |
steps[].label | string | no | Your own name for the step. (max length 120) |
steps[].amount | number | no | order: the basket's total, as one line. Send this or `lines`. |
steps[].lines | array of object {uuid, name, category, brand, unit_price, qty} | no | order: the products, for rules about products, categories or brands. (at most 20 items) |
steps[].lines[].uuid | string | no | |
steps[].lines[].name | string | no | |
steps[].lines[].category | string | no | |
steps[].lines[].brand | string | no | |
steps[].lines[].unit_price | number | yes | |
steps[].lines[].qty | integer | no | |
steps[].discount | number | no | order: other discounts, THB. |
steps[].delivery | number | no | order: the delivery fee, THB. |
steps[].channel | "line" | "meta" | "facebook" | "ig" | "direct" | "shopee" | "tiktok" | "lazada" | no | order: where the order comes from. Shopee, Lazada and TikTok earn nothing. (default "line") |
steps[].status | string | no | order: paid (default) or fulfilled · order_status: fulfilled, cancelled or refund · member_status: active or suspended. |
steps[].repeat | integer | no | order: the same order this many times. (min 1) (max 100) |
steps[].every_days | number | no | order: days between the repeats; 0 = all at once. |
steps[].use_voucher_from_step | integer | no | order: pay with the voucher an earlier redeem step gave. |
steps[].order_step | integer | no | order_status: the earlier order step. |
steps[].occurrence | integer | no | order_status: which of that step's repeats (default: its last). |
steps[].days | number | no | wait: days to pass. |
steps[].months | integer | no | wait: months to pass. |
steps[].until | string | no | wait: pass until this moment. (format date-time) |
steps[].reward | string | no | redeem: a reward's id or name. Send this or units. |
steps[].units | number | no | redeem: units to turn into a voucher · adjust: + adds, − takes. |
steps[].redemption_step | integer | no | cancel_redemption: the earlier step that redeemed. |
steps[].reason | string | no | adjust: why. |
steps[].expect | object {balance, pending_balance, earned, order_count, lifetime_earned, lifetime_redeemed, lifetime_expired, rewards_issued, tier, refused, error} | no | What the step should leave. Each field you send becomes a check in the answer, passed or failed. |
steps[].expect.balance | number or object {at_least, at_most} | no | Exact, or a range: { at_least, at_most }. |
steps[].expect.pending_balance | number or object {at_least, at_most} | no | Exact, or a range: { at_least, at_most }. |
steps[].expect.earned | number or object {at_least, at_most} | no | Units this step's orders earned (held ones included). |
steps[].expect.order_count | number or object {at_least, at_most} | no | Exact, or a range: { at_least, at_most }. |
steps[].expect.lifetime_earned | number or object {at_least, at_most} | no | Exact, or a range: { at_least, at_most }. |
steps[].expect.lifetime_redeemed | number or object {at_least, at_most} | no | Exact, or a range: { at_least, at_most }. |
steps[].expect.lifetime_expired | number or object {at_least, at_most} | no | Exact, or a range: { at_least, at_most }. |
steps[].expect.rewards_issued | number or object {at_least, at_most} | no | Redemptions this step made, threshold rewards included. |
steps[].expect.tier | string | null | no | A tier key or name; null = no tier. |
steps[].expect.refused | boolean | no | true: the program should refuse this step. |
steps[].expect.error | string | no | The refusal's code, e.g. LOYALTY_INSUFFICIENT_BALANCE. |
Request examples
hold_redeem_refund
{
"steps": [
{
"type": "order",
"amount": 2000,
"channel": "line",
"expect": {
"earned": 100,
"pending_balance": 100
}
},
{
"type": "wait",
"days": 7,
"label": "the return window",
"expect": {
"balance": 100
}
},
{
"type": "redeem",
"units": 100,
"expect": {
"balance": 0
}
},
{
"type": "order",
"amount": 500,
"use_voucher_from_step": 3,
"expect": {
"earned": 24
}
},
{
"type": "order_status",
"order_step": 1,
"status": "refund",
"expect": {
"balance": 0
}
}
]
} stamp_card_preset
{
"template_key": "stamp_card",
"steps": [
{
"type": "order",
"amount": 150,
"repeat": 10,
"every_days": 3,
"expect": {
"rewards_issued": 1,
"balance": 0
}
}
]
} vip_member
{
"template_key": "vip_tiers",
"customer": {
"enrolled": true,
"tier": "gold",
"balance": 4500
},
"steps": [
{
"type": "order",
"amount": 1000,
"expect": {
"earned": 150,
"tier": "gold"
}
},
{
"type": "wait",
"months": 13,
"expect": {
"tier": "member"
}
}
]
}Response 200
Each step with what happened and its checks.
ok
{
"code": 200,
"message": "Test run: nothing was changed",
"data": {
"tested": {
"source": "saved",
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"status": "draft",
"as_if_active": true,
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"rewards": []
},
"start_at": "2026-11-20T03:00:00.000Z",
"end_at": "2026-11-27T03:00:00.000Z",
"steps": [
{
"step": 1,
"type": "order",
"label": "",
"at": "2026-11-20T03:00:00.000Z",
"refused": null,
"earned": 100,
"orders": [
{
"occurrence": 1,
"channel": "line",
"status": "paid",
"price_net": 2000,
"earned": 100,
"held": true,
"reason": null,
"base_amount": 2000,
"breakdown": [
{
"rule_id": "spend",
"name": "ทุก 20 บาทรับ 1 แต้ม",
"type": "per_spend",
"units": 100
}
]
}
],
"events": [
{
"at": "2026-11-20T03:00:00.000Z",
"kind": "enrolled",
"via": "order",
"tier": null
},
{
"at": "2026-11-20T03:00:00.000Z",
"kind": "earned",
"order": {
"step": 1,
"occurrence": 1
},
"units": 100,
"held": true,
"available_at": "2026-11-27T03:00:00.000Z"
}
],
"member": {
"enrolled": true,
"status": "active",
"balance": 0,
"pending_balance": 100,
"lifetime_earned": 0,
"lifetime_redeemed": 0,
"lifetime_expired": 0,
"order_count": 1,
"total_spend": 2000,
"tier": null,
"next_tier": null,
"period_ends_at": null,
"next_expiry": null
},
"checks": [
{
"field": "earned",
"expected": 100,
"actual": 100,
"pass": true
},
{
"field": "pending_balance",
"expected": 100,
"actual": 100,
"pass": true
}
]
},
{
"step": 2,
"type": "wait",
"label": "the return window",
"at": "2026-11-20T03:00:00.000Z",
"refused": null,
"events": [
{
"at": "2026-11-27T03:00:00.000Z",
"kind": "released",
"units": 100,
"order": {
"step": 1,
"occurrence": 1
},
"expires_at": "2027-11-27T03:00:00.000Z"
}
],
"member": {
"enrolled": true,
"status": "active",
"balance": 100,
"pending_balance": 0,
"lifetime_earned": 100,
"lifetime_redeemed": 0,
"lifetime_expired": 0,
"order_count": 1,
"total_spend": 2000,
"tier": null,
"next_tier": null,
"period_ends_at": null,
"next_expiry": {
"at": "2027-11-27T03:00:00.000Z",
"units": 100
}
},
"checks": [
{
"field": "balance",
"expected": 100,
"actual": 100,
"pass": true
}
]
}
],
"member": {
"enrolled": true,
"status": "active",
"balance": 0,
"pending_balance": 24,
"lifetime_earned": 0,
"lifetime_redeemed": 100,
"lifetime_expired": 0,
"order_count": 1,
"total_spend": 490,
"tier": null,
"next_tier": null,
"period_ends_at": null,
"next_expiry": null
},
"redemptions": [
{
"step": 3,
"kind": "exchange",
"auto": false,
"reward": null,
"units_spent": 100,
"status": "used",
"voucher": {
"code": "TEST-01",
"type": "fixed",
"value": 10,
"max_discount_amount": null,
"min_order_amount": 0,
"expires_at": "2026-12-27T03:00:00.000Z"
},
"used_on": {
"step": 4,
"occurrence": 1
},
"created_at": "2026-11-27T03:00:00.000Z"
}
],
"passed": 7,
"failed": 0,
"result": "passed"
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/program/checks#
Run the ready-made checks and review the settings.
Use before switching a program on, after changing it, or when the owner asks whether it works: one call runs a check for each thing the settings promise (an ordinary order, each rule, the welcome bonus, the minimum order, the hold, a refund, expiry, reaching the next tier, the exchange rate, each reward) and reviews the settings for mistakes (a rule that can never apply, a reward for a tier nobody can hold, a cap that cuts a bonus off).
- review: findings, problem first, then warning and info.
- checks: each with outcome (passed or failed), a plain summary to tell the owner, and the story it ran (input, run); POST /loyalty/program/test takes input back as it is.
- Like the test, it takes program, rewards or template_key to check settings before saving them.
Changes nothing. Safe to retry: yes.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
template_key | "classic_points" | "stamp_card" | "cashback_credit" | "vip_tiers" | "visit_rewards" | "blank" | no | Test a preset instead of the shop's program (no program needed). |
program | object {name, description, timezone, currency, earning, redemption, tiers, expiry, enrollment} | no | Settings to try in place of the saved ones, section by section as PATCH /loyalty/program takes them (each section whole). Not saved. |
program.name | string | no | The program's name, as the shop calls it (Thai is fine). (max length 80) |
program.description | string | no | (max length 1000) |
program.timezone | string | no | Where days and expiry dates are counted. Default Asia/Bangkok. |
program.currency | object {kind, name, singular_name, decimals, card_size} | no | What members collect. |
program.currency.kind | "points" | "stamps" | "credit" | no | |
program.currency.name | string | no | |
program.currency.singular_name | string | no | |
program.currency.decimals | integer | no | (min 0) (max 2) |
program.currency.card_size | integer | null | no | stamps only: stamps on a full card. |
program.earning | object {accrual_event, hold_days, base_amount, exclude_shipping, rounding, channels, min_order_amount, max_units_per_order, backfill_from, rules} | no | How orders earn. Rules add up; then the highest matching multiplier, then the tier's multiplier, then `max_units_per_order`. |
program.earning.accrual_event | "order_paid" | "order_fulfilled" | no | Earn when the order is paid, or only once it is fulfilled. |
program.earning.hold_days | integer | no | Earned units wait this many days (a return window) before they can be spent. (min 0) |
program.earning.base_amount | "price_net" | "price_total" | no | |
program.earning.exclude_shipping | boolean | no | |
program.earning.rounding | "floor" | "round" | "ceil" | no | |
program.earning.channels | array of "line" | "meta" | "facebook" | "ig" | "direct" | no | Only orders from these channels. Shopee, Lazada and TikTok orders never earn. |
program.earning.min_order_amount | number | no | (min 0) |
program.earning.max_units_per_order | number | null | no | |
program.earning.backfill_from | string | null | no | Orders from this date earn; default: from when the program is switched on. (format date-time) |
program.earning.rules | array of object {id, name, enabled, type, units, per_amount, factor, max_units, conditions} | no | |
program.earning.rules[].id | string | no | |
program.earning.rules[].name | string | yes | (max length 120) |
program.earning.rules[].enabled | boolean | no | (default true) |
program.earning.rules[].type | "per_spend" | "per_order" | "per_item" | "first_order" | "multiplier" | yes | per_spend: `units` for every `per_amount` THB · per_order: `units` per order · per_item: `units` per item · first_order: `units` on a member's first order · multiplier: × `factor` on the rest (the highest one that matches applies, then the tier's). |
program.earning.rules[].units | number | no | (min 0) |
program.earning.rules[].per_amount | number | null | no | per_spend only: the THB that earns `units`. |
program.earning.rules[].factor | number | null | no | multiplier only. (min 1) (max 100) |
program.earning.rules[].max_units | number | null | no | Most this rule gives on one order; null = no cap. |
program.earning.rules[].conditions | object {channels, product_uuids, categories, brands, min_order_amount, tiers, start_at, end_at, days_of_week} | no | When a rule applies. Every field is optional; empty means no limit. |
program.redemption | object {enabled, exchange} | no | Turning units into a voucher at a fixed rate (`exchange`), beside the reward catalogue. |
program.redemption.enabled | boolean | no | |
program.redemption.exchange | object {enabled, units, value, step_units, min_units, max_units_per_redemption, voucher_valid_days, voucher_min_order_amount} | no | |
program.redemption.exchange.enabled | boolean | no | |
program.redemption.exchange.units | number | no | `units` buy a voucher worth `value` THB. |
program.redemption.exchange.value | number | no | |
program.redemption.exchange.step_units | number | no | |
program.redemption.exchange.min_units | number | no | |
program.redemption.exchange.max_units_per_redemption | number | null | no | |
program.redemption.exchange.voucher_valid_days | integer | no | (min 1) (max 365) |
program.redemption.exchange.voucher_min_order_amount | number | no | (min 0) |
program.tiers | object {enabled, basis, period_months, downgrade, levels} | no | |
program.tiers.enabled | boolean | no | |
program.tiers.basis | "lifetime_units" | "period_units" | "period_spend" | "order_count" | no | |
program.tiers.period_months | integer | no | (min 1) (max 60) |
program.tiers.downgrade | "never" | "on_period_end" | no | |
program.tiers.levels | array of object {key, name, threshold, multiplier, benefits, color} | no | |
program.tiers.levels[].key | string | yes | (pattern `^[a-z0-9_-]+$`) |
program.tiers.levels[].name | string | yes | |
program.tiers.levels[].threshold | number | yes | |
program.tiers.levels[].multiplier | number | no | (min 1) (max 100) |
program.tiers.levels[].benefits | array of string | no | Words shown to members; only `multiplier`, tier-only rewards and rules act on them. |
program.tiers.levels[].color | string | no | |
program.expiry | object {mode, months, year_offset} | no | |
program.expiry.mode | "never" | "fixed_months" | "end_of_year" | "inactivity" | no | |
program.expiry.months | integer | no | (min 1) (max 120) |
program.expiry.year_offset | integer | no | (min 0) (max 5) |
program.enrollment | object {mode, welcome_units, terms} | no | |
program.enrollment.mode | "auto" | "explicit" | no | auto: a customer joins on their first paid order · explicit: staff enrol them. |
program.enrollment.welcome_units | number | no | (min 0) |
program.enrollment.terms | string | no | (max length 5000) |
rewards | array of object {id, name, description, type, value, max_discount_amount, product, cost_units, trigger, threshold_units, tier_required, stock, max_per_member, voucher_valid_days, min_order_amount, status} | no | Rewards to try in place of the saved ones. Not saved. (at most 30 items) |
rewards[].id | string | no | |
rewards[].name | string | no | (max length 120) |
rewards[].description | string | no | (max length 1000) |
rewards[].type | "discount_fixed" | "discount_percent" | "free_product" | "custom" | no | discount_fixed: `value` THB off · discount_percent: `value`% off (cap with `max_discount_amount`) · free_product: a voucher worth the product's price at redemption · custom: handed over by staff. |
rewards[].value | number | no | (min 0) |
rewards[].max_discount_amount | number | null | no | |
rewards[].product | object {uuid, name, price} | no | free_product only: one of the shop's own products (its uuid from GET /products); another shop's is refused with 400 LOYALTY_REWARD_PRODUCT_NOT_FOUND. |
rewards[].product.uuid | string | no | |
rewards[].product.name | string | no | |
rewards[].product.price | number | null | no | |
rewards[].cost_units | number | no | (min 0) |
rewards[].trigger | "redeem" | "threshold" | no | redeem: the member chooses it · threshold: issued by itself once the balance reaches `threshold_units` (a full stamp card). |
rewards[].threshold_units | number | null | no | |
rewards[].tier_required | string | null | no | A tier key, or null for every member. |
rewards[].stock | integer | null | no | How many are left; null = no limit. |
rewards[].max_per_member | integer | null | no | |
rewards[].voucher_valid_days | integer | no | (min 1) (max 365) |
rewards[].min_order_amount | number | no | (min 0) |
rewards[].status | "active" | "inactive" | "archived" | no | |
start_at | string | no | When the story starts; default now. Rule dates, weekdays and expiry follow it. (format date-time) |
Request examples
saved
{} preset
{
"template_key": "cashback_credit"
} before_saving
{
"program": {
"expiry": {
"mode": "fixed_months",
"months": 6,
"year_offset": 1
}
}
}Response 200
The settings review and every check's outcome.
ok
{
"code": 200,
"message": "Checks run: nothing was changed",
"data": {
"tested": {
"source": "saved",
"template_key": "classic_points",
"name": "นิชิ พอยท์",
"status": "draft",
"as_if_active": true,
"currency": {
"kind": "points",
"name": "แต้ม",
"singular_name": "แต้ม",
"decimals": 0,
"card_size": null
},
"rewards": []
},
"review": [
{
"code": "bonus_capped",
"severity": "warning",
"message": "The most per order (50) is less than rule \"โบนัสออเดอร์แรก\" gives (100): the rest is cut off.",
"params": {
"rule": "โบนัสออเดอร์แรก",
"cap": 50,
"units": 100
}
},
{
"code": "program_not_active",
"severity": "info",
"message": "The program is draft: no order earns until it is switched on.",
"params": {
"status": "draft"
}
}
],
"checks": [
{
"key": "earn",
"id": null,
"title": "An ordinary order earns",
"outcome": "passed",
"code": "earn.ok_value",
"summary": "A ฿500 order on LINE earns 25 แต้ม, worth ฿2.50 (0.5% back).",
"params": {
"amount": 500,
"channel": "line",
"units": 25,
"value": 2.5,
"percent_back": 0.5
},
"input": null,
"run": null
},
{
"key": "rule",
"id": "first",
"title": "Rule \"โบนัสออเดอร์แรก\" applies when it should",
"outcome": "failed",
"code": "rule.first_no_effect",
"summary": "The first order earned 50 and the second 25: the bonus added nothing. Check the most per order.",
"params": {
"rule": "โบนัสออเดอร์แรก",
"first": 50,
"second": 25
},
"input": null,
"run": null
},
{
"key": "hold",
"id": null,
"title": "Points wait out the hold before they can be spent",
"outcome": "passed",
"code": "hold.ok",
"summary": "25 wait 7 days, then can be spent.",
"params": {
"days": 7,
"units": 25
},
"input": null,
"run": null
}
],
"passed": 2,
"failed": 1
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/loyalty/rewards#
The rewards members can spend their units on.
Use to read the reward catalogue before adding or changing a reward, or to tell the owner what members can get. Archived rewards are left out unless you ask for status=archived.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
status (query) | "active" | "inactive" | "archived" | no |
Response 200
The rewards.
ok
{
"code": 200,
"message": "OK",
"data": {
"rewards": [
{
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"description": "ใช้กับคำสั่งซื้อขั้นต่ำ 300 บาท",
"type": "discount_fixed",
"value": 50,
"max_discount_amount": null,
"product": null,
"cost_units": 500,
"trigger": "redeem",
"threshold_units": null,
"tier_required": null,
"stock": null,
"max_per_member": null,
"voucher_valid_days": 30,
"min_order_amount": 300,
"status": "active",
"count_redeemed": 12
}
]
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/rewards#
Add a reward to the catalogue.
Use when the owner wants a new reward: a discount (fixed THB or %), a free product (a voucher worth the product's price when redeemed) or a custom reward staff hand over. threshold rewards are issued by themselves when a balance reaches threshold_units (a full stamp card).
Before calling: confirm the cost in units and the voucher's value with the owner, and check GET /loyalty/rewards that it isn't there already.
Safe to retry: no — a repeat adds a second reward. List the rewards before sending again.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | (max length 120) |
description | string | no | (max length 1000) |
type | "discount_fixed" | "discount_percent" | "free_product" | "custom" | yes | discount_fixed: `value` THB off · discount_percent: `value`% off (cap with `max_discount_amount`) · free_product: a voucher worth the product's price at redemption · custom: handed over by staff. |
value | number | no | (min 0) |
max_discount_amount | number | null | no | |
product | object {uuid, name, price} | no | free_product only: one of the shop's own products (its uuid from GET /products); another shop's is refused with 400 LOYALTY_REWARD_PRODUCT_NOT_FOUND. |
product.uuid | string | no | |
product.name | string | no | |
product.price | number | null | no | |
cost_units | number | yes | (min 0) |
trigger | "redeem" | "threshold" | no | redeem: the member chooses it · threshold: issued by itself once the balance reaches `threshold_units` (a full stamp card). |
threshold_units | number | null | no | |
tier_required | string | null | no | A tier key, or null for every member. |
stock | integer | null | no | How many are left; null = no limit. |
max_per_member | integer | null | no | |
voucher_valid_days | integer | no | (min 1) (max 365) |
min_order_amount | number | no | (min 0) |
status | "active" | "inactive" | "archived" | no |
Request examples
discount
{
"name": "ส่วนลด 50 บาท",
"description": "ใช้กับคำสั่งซื้อขั้นต่ำ 300 บาท",
"type": "discount_fixed",
"value": 50,
"cost_units": 500,
"min_order_amount": 300,
"voucher_valid_days": 30
} percent
{
"name": "ลด 10%",
"type": "discount_percent",
"value": 10,
"max_discount_amount": 200,
"cost_units": 800
} custom
{
"name": "กล่องสุ่มฟรี 1 กล่อง",
"type": "custom",
"cost_units": 1500,
"stock": 20,
"max_per_member": 1
}Response 201
The new reward.
ok
{
"code": 201,
"message": "Reward created",
"data": {
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"description": "ใช้กับคำสั่งซื้อขั้นต่ำ 300 บาท",
"type": "discount_fixed",
"value": 50,
"max_discount_amount": null,
"product": null,
"cost_units": 500,
"trigger": "redeem",
"threshold_units": null,
"tier_required": null,
"stock": null,
"max_per_member": null,
"voucher_valid_days": 30,
"min_order_amount": 300,
"status": "active",
"count_redeemed": 12
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
PATCH/loyalty/rewards/{id}#
Change a reward's details.
Use to change a reward's name, cost, value, stock or limits. Send only the fields that change. To switch it on or off use POST /loyalty/rewards/{id}/status. Vouchers already issued keep their value.
Before calling: get the id from GET /loyalty/rewards and confirm the change with the owner.
Safe to retry: yes.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The reward's id from GET /loyalty/rewards. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | (max length 120) |
description | string | no | (max length 1000) |
type | "discount_fixed" | "discount_percent" | "free_product" | "custom" | no | discount_fixed: `value` THB off · discount_percent: `value`% off (cap with `max_discount_amount`) · free_product: a voucher worth the product's price at redemption · custom: handed over by staff. |
value | number | no | (min 0) |
max_discount_amount | number | null | no | |
product | object {uuid, name, price} | no | free_product only: one of the shop's own products (its uuid from GET /products); another shop's is refused with 400 LOYALTY_REWARD_PRODUCT_NOT_FOUND. |
product.uuid | string | no | |
product.name | string | no | |
product.price | number | null | no | |
cost_units | number | no | (min 0) |
trigger | "redeem" | "threshold" | no | redeem: the member chooses it · threshold: issued by itself once the balance reaches `threshold_units` (a full stamp card). |
threshold_units | number | null | no | |
tier_required | string | null | no | A tier key, or null for every member. |
stock | integer | null | no | How many are left; null = no limit. |
max_per_member | integer | null | no | |
voucher_valid_days | integer | no | (min 1) (max 365) |
min_order_amount | number | no | (min 0) |
status | "active" | "inactive" | "archived" | no |
Request examples
cheaper
{
"cost_units": 400
} restock
{
"stock": 50
}Response 200
The reward as saved.
ok
{
"code": 200,
"message": "Reward updated",
"data": {
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"description": "ใช้กับคำสั่งซื้อขั้นต่ำ 300 บาท",
"type": "discount_fixed",
"value": 50,
"max_discount_amount": null,
"product": null,
"cost_units": 500,
"trigger": "redeem",
"threshold_units": null,
"tier_required": null,
"stock": null,
"max_per_member": null,
"voucher_valid_days": 30,
"min_order_amount": 300,
"status": "active",
"count_redeemed": 12
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No reward with this id in the shop's program. List them with GET /loyalty/rewards.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/rewards/{id}/status#
Switch a reward on or off, or archive it.
Use when the owner wants a reward offered (active), held back for now (inactive) or removed (archived; nothing is deleted).
Safe to retry: yes.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The reward's id from GET /loyalty/rewards. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
status | "active" | "inactive" | "archived" | yes |
Request examples
pause
{
"status": "inactive"
} remove
{
"status": "archived"
}Response 200
The reward with its new status.
ok
{
"code": 200,
"message": "Reward inactive",
"data": {
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"description": "ใช้กับคำสั่งซื้อขั้นต่ำ 300 บาท",
"type": "discount_fixed",
"value": 50,
"max_discount_amount": null,
"product": null,
"cost_units": 500,
"trigger": "redeem",
"threshold_units": null,
"tier_required": null,
"stock": null,
"max_per_member": null,
"voucher_valid_days": 30,
"min_order_amount": 300,
"status": "active",
"count_redeemed": 12
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No reward with this id in the shop's program. List them with GET /loyalty/rewards.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/loyalty/members#
The program's members with their balances, page by page.
Use to find a member (by member code or name in search) or to tell the owner who holds the most units. A member's phone, platform id and staff notes are never shown.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
search (query) | string | no | A member code or part of a name. |
tier (query) | string | no | A tier key. |
status (query) | "active" | "suspended" | no | |
page (query) | integer | no | (min 1) (default 1) |
limit (query) | integer | no | (min 1) (max 100) (default 10) |
Response 200
A page of members, most recently active first.
ok
{
"code": 200,
"message": "OK",
"data": {
"results": [
{
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "active",
"balance": 640,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
}
],
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/loyalty/members/{id}#
One member, their latest units history and redemptions.
Use to answer the owner about one member: their balance, units waiting in the hold, what they earned on which order, what they redeemed and their open vouchers. Shows the last 50 history lines and 20 redemptions.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The member's id from GET /loyalty/members. |
Response 200
The member with history.
ok
{
"code": 200,
"message": "OK",
"data": {
"member": {
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "active",
"balance": 640,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
},
"ledger": [
{
"id": "6650f0c2a1b2c3d4e5f60753",
"type": "earn",
"units": 45,
"status": "pending",
"balance_after": null,
"source": "order",
"receipt_id": "NW-20261120-0042",
"reason": "",
"available_at": "2026-11-27T09:40:00.000Z",
"expires_at": "2027-11-27T09:40:00.000Z",
"created_at": "2026-11-20T09:40:00.000Z"
}
],
"redemptions": [
{
"id": "6650f0c2a1b2c3d4e5f60764",
"member_id": "6650f0c2a1b2c3d4e5f60742",
"kind": "reward",
"status": "issued",
"units_spent": 500,
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"type": "discount_fixed"
},
"voucher": {
"code": "LY-K7M2PQ",
"type": "fixed",
"value": 50,
"expires_at": "2026-12-20T09:41:00.000Z"
},
"created_at": "2026-11-20T09:41:00.000Z",
"cancelled_at": null,
"fulfilled_at": null
}
]
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No member with this id in the shop's program. Find them with GET /loyalty/members.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/loyalty/members/{id}/ledger#
A member's whole units history, page by page.
Use to go further back than the 50 lines GET /loyalty/members/{id} shows: every unit earned, held, released, spent, taken back or expired, newest first, with the balance after each.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The member's id from GET /loyalty/members. |
page (query) | integer | no | (min 1) (default 1) |
limit (query) | integer | no | (min 1) (max 100) (default 10) |
Response 200
A page of history lines.
ok
{
"code": 200,
"message": "OK",
"data": {
"results": [
{
"id": "6650f0c2a1b2c3d4e5f60753",
"type": "earn",
"units": 45,
"status": "pending",
"balance_after": null,
"source": "order",
"receipt_id": "NW-20261120-0042",
"reason": "",
"available_at": "2026-11-27T09:40:00.000Z",
"expires_at": "2027-11-27T09:40:00.000Z",
"created_at": "2026-11-20T09:40:00.000Z"
}
],
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No member with this id in the shop's program. Find them with GET /loyalty/members.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/members/{id}/status#
Suspend a member, or make them active again.
Use when the owner wants a member to stop earning and redeeming for now (suspended; their units stay), or to let them again (active). Needs loyalty:points.
Before calling: confirm the member (code, name) with the owner.
Safe to retry: yes — the same status again changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The member's id from GET /loyalty/members. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
status | "active" | "suspended" | yes | |
reason | string | no | Kept in the API change log. (max length 300) |
Request examples
suspend
{
"status": "suspended",
"reason": "ตรวจสอบคำสั่งซื้อที่ผิดปกติ"
} reactivate
{
"status": "active"
}Response 200
The member with their status.
suspended
{
"code": 200,
"message": "Member suspended",
"data": {
"member": {
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "suspended",
"balance": 640,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No member with this id in the shop's program. Find them with GET /loyalty/members.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/members/{id}/adjust#
Add or take away a member's units by hand.
Use when the owner asks to give units as a goodwill gesture or correct a mistake: units positive adds (spendable at once), negative takes away (never below what the member holds). Needs loyalty:points.
- Send it with
dry_run: true: the answer shows the balance before and after, and nothing changes. - Tell the owner the member (code, name), the change and the reason; wait for a clear yes.
- Send the same request with
dry_run: false.
Safe to retry: yes, with the same idempotency_key: a repeat answers the first change (duplicate: true) and moves nothing. Use a new key for each new change; the same key with a different change is 409 LOYALTY_REQUEST_REUSED.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The member's id from GET /loyalty/members. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
units | number | yes | + adds, − takes away; not 0. |
reason | string | yes | Kept in the member's history. (min length 1) (max length 300) |
idempotency_key | string | yes | Your own id for this one change (a UUID). (max length 200) |
dry_run | boolean | no | (default false) |
Request examples
preview_gift
{
"units": 100,
"reason": "ของขวัญขอโทษที่ส่งช้า",
"idempotency_key": "8c6f2d0e-6a1b-4f3e-9d2a-1b7c5e4f3a21",
"dry_run": true
} take_back
{
"units": -50,
"reason": "แก้ไขแต้มที่ให้ซ้ำ",
"idempotency_key": "0b9e4a7c-2d3f-4e5a-8b6c-7d8e9f0a1b2c",
"dry_run": false
}Response 200
The member after the change (or, on a dry run, the balance it would leave).
dry_run
{
"code": 200,
"message": "Dry run: nothing was changed",
"data": {
"dry_run": true,
"member": {
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "active",
"balance": 640,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
},
"balance_before": 640,
"balance_after": 740
}
} applied
{
"code": 200,
"message": "Points changed",
"data": {
"dry_run": false,
"duplicate": false,
"member": {
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "active",
"balance": 740,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
},
"entry": {
"id": "6650f0c2a1b2c3d4e5f60753",
"type": "adjust",
"units": 100,
"status": "posted",
"balance_after": 740,
"source": "staff",
"receipt_id": null,
"reason": "API key \"Owner assistant\": ของขวัญขอโทษที่ส่งช้า",
"available_at": null,
"expires_at": "2027-11-27T09:40:00.000Z",
"created_at": "2026-11-20T09:40:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No member with this id in the shop's program. Find them with GET /loyalty/members.
- 409: The idempotency_key was used before for a different change. Use a new key.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/members/{id}/redeem#
Spend a member's units on a reward or a voucher.
Use when the owner asks to redeem for a member: a catalogue reward (reward_id) or units turned into a voucher at the program's rate (units). The voucher is bound to the member: only they can use it, once, as the coupon code at checkout. Needs loyalty:points.
- Send it with
dry_run: true: the answer shows the units it would spend, the voucher it would give and the balance after; nothing changes. - Tell the owner and wait for a clear yes.
- Send the same request with
dry_run: false, and give the owner the voucher code.
Safe to retry: yes, with the same idempotency_key: a repeat answers the first redemption and voucher (duplicate: true), never a second. A new key is a new redemption.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The member's id from GET /loyalty/members. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
reward_id | string | no | A reward from GET /loyalty/rewards. Send this or `units`, not both. |
units | number | no | Units to turn into a voucher at the program's exchange rate. |
idempotency_key | string | yes | (max length 200) |
dry_run | boolean | no | (default false) |
Request examples
preview_reward
{
"reward_id": "6650f0c2a1b2c3d4e5f60731",
"idempotency_key": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b",
"dry_run": true
} voucher
{
"units": 500,
"idempotency_key": "a9b8c7d6-e5f4-4321-9a8b-7c6d5e4f3a2b",
"dry_run": false
}Response 200
A dry run: what it would spend and give.
dry_run
{
"code": 200,
"message": "Dry run: nothing was changed",
"data": {
"dry_run": true,
"member": {
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "active",
"balance": 640,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
},
"units_spent": 500,
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"type": "discount_fixed"
},
"voucher": {
"type": "fixed",
"value": 50
},
"balance_after": 140
}
}Response 201
The redemption and the member after it.
redeemed
{
"code": 201,
"message": "Redeemed",
"data": {
"dry_run": false,
"duplicate": false,
"redemption": {
"id": "6650f0c2a1b2c3d4e5f60764",
"member_id": "6650f0c2a1b2c3d4e5f60742",
"kind": "reward",
"status": "issued",
"units_spent": 500,
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"type": "discount_fixed"
},
"voucher": {
"code": "LY-K7M2PQ",
"type": "fixed",
"value": 50,
"expires_at": "2026-12-20T09:41:00.000Z"
},
"created_at": "2026-11-20T09:41:00.000Z",
"cancelled_at": null,
"fulfilled_at": null
},
"member": {
"id": "6650f0c2a1b2c3d4e5f60742",
"member_code": "M7K3D9Q",
"name": "Nok",
"channel": "line",
"status": "active",
"balance": 140,
"pending_balance": 45,
"lifetime_earned": 1140,
"lifetime_redeemed": 500,
"lifetime_expired": 0,
"order_count": 9,
"total_spend": 22850,
"tier": null,
"enrolled_at": "2026-11-02T05:12:00.000Z",
"enrolled_via": "order",
"last_activity_at": "2026-11-20T09:40:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No member with this id in the shop's program. Find them with GET /loyalty/members.
- 409: The idempotency_key was used before for a different redemption. Use a new key.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/loyalty/redemptions#
Redemptions across the program, newest first.
Use to see what members redeemed, which vouchers are still open (status=issued) or which custom rewards wait to be handed over.
Changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
status (query) | "issued" | "used" | "fulfilled" | "cancelled" | "expired" | no | |
member_id (query) | string | no | Only this member's (an id from GET /loyalty/members). |
page (query) | integer | no | (min 1) (default 1) |
limit (query) | integer | no | (min 1) (max 100) (default 10) |
Response 200
A page of redemptions.
ok
{
"code": 200,
"message": "OK",
"data": {
"results": [
{
"id": "6650f0c2a1b2c3d4e5f60764",
"member_id": "6650f0c2a1b2c3d4e5f60742",
"kind": "reward",
"status": "issued",
"units_spent": 500,
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"type": "discount_fixed"
},
"voucher": {
"code": "LY-K7M2PQ",
"type": "fixed",
"value": 50,
"expires_at": "2026-12-20T09:41:00.000Z"
},
"created_at": "2026-11-20T09:41:00.000Z",
"cancelled_at": null,
"fulfilled_at": null
}
],
"page": 1,
"limit": 10,
"total": 1,
"total_pages": 1
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The shop has no loyalty program yet (or only an archived one). Create one with POST /loyalty/program.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/loyalty/redemptions/{id}#
Hand over a custom reward, or cancel a redemption.
Use when staff handed a custom reward over (fulfill), or the owner wants an issued redemption undone (cancel): its voucher stops working and the units go back to the member, with their own expiry dates. Only issued redemptions can change. Needs loyalty:points.
Before calling: confirm with the owner.
Safe to retry: yes — a second time is refused with 400 (no longer issued) and changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The redemption's id from GET /loyalty/redemptions. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
action | "fulfill" | "cancel" | yes | |
note | string | no | (max length 500) |
reason | string | no | (max length 500) |
Request examples
handed_over
{
"action": "fulfill",
"note": "รับที่หน้าร้าน"
} undo
{
"action": "cancel",
"reason": "ลูกค้าเปลี่ยนใจ"
}Response 200
The redemption with its new status.
cancelled
{
"code": 200,
"message": "Redemption cancelled",
"data": {
"redemption": {
"id": "6650f0c2a1b2c3d4e5f60764",
"member_id": "6650f0c2a1b2c3d4e5f60742",
"kind": "reward",
"status": "cancelled",
"units_spent": 500,
"reward": {
"id": "6650f0c2a1b2c3d4e5f60731",
"name": "ส่วนลด 50 บาท",
"type": "discount_fixed"
},
"voucher": {
"code": "LY-K7M2PQ",
"type": "fixed",
"value": 50,
"expires_at": "2026-12-20T09:41:00.000Z"
},
"created_at": "2026-11-20T09:41:00.000Z",
"cancelled_at": "2026-11-21T02:00:00.000Z",
"fulfilled_at": null
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No redemption with this id in the shop's program. List them with GET /loyalty/redemptions.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Subscriptions
Subscription plans the shop sells to its customers, paid every period. Plans only; subscribers stay in the dashboard.
GET/subscriptions/readiness#
Can the shop sell subscriptions yet (Stripe connected and ready)?
Use first, before putting a plan on sale: plans go on sale only when ready is true. Drafts can be made either way.
Response 200
The shop's Stripe account, as far as subscriptions need it.
ready
{
"code": 200,
"message": "OK",
"data": {
"ready": true,
"stripe_connected": true,
"charges_enabled": true,
"card": true,
"promptpay": true,
"requirement": null
}
} not_connected
{
"code": 200,
"message": "OK",
"data": {
"ready": false,
"stripe_connected": false,
"charges_enabled": false,
"card": false,
"promptpay": false,
"requirement": null
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/subscriptions/plans#
List the shop's subscription plans with their prices.
Use first to see what plans exist before creating one (names are unique). Archived plans are left out unless status=archived or all.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
status (query) | "draft" | "on_sale" | "archived" | "all" | no |
Response 200
The plans, newest first.
ok
{
"code": 200,
"message": "OK",
"data": {
"plans": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f0",
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"images": [],
"gives": "membership",
"renewal_modes": [
"auto",
"link"
],
"tagline": "An AI sales assistant for your LINE, Facebook and Instagram chats",
"highlights": [
"The bot answers LINE, Facebook and Instagram chats, 24/7",
"One inbox for every chat, with handover to your team"
],
"audience": "Shops that sell through LINE, Facebook or Instagram and get customer chats every day",
"not_included": [
"Shopee and Lazada chats"
],
"badge": "",
"sort": 1,
"rules": {
"cancel": {
"mode": "any_time",
"count": null,
"text": ""
},
"pause": {
"mode": "no",
"count": null,
"text": ""
},
"late": {
"mode": "",
"count": null,
"text": ""
},
"refund": {
"mode": "none",
"count": null,
"text": ""
},
"change": {
"mode": "now",
"count": null,
"text": ""
},
"terms_url": ""
},
"status": "draft",
"prices": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f1",
"label": "Monthly",
"amount": 2621.5,
"currency": "thb",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"setup_fee": 0,
"total_payments": null,
"vat": "included",
"vat_rate": 7,
"active": true
}
],
"created_at": "2026-11-12T08:00:00.000Z",
"updated_at": "2026-11-12T08:00:00.000Z"
}
]
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/subscriptions/plans#
Create a subscription plan with at least one price.
Use to add a plan. Leave status out to save a draft, show the owner, and put it on sale later with PATCH. status: "on_sale" needs a ready Stripe account (GET /subscriptions/readiness).
Safe to retry: yes. A plan with the same name is refused (409) instead of made twice.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | yes | (min length 1) (max length 120) |
description | string | no | What the buyer gets, as the chat bot and the sign-up page show it. (max length 2000) |
images | array of string | no | (at most 8 items) |
gives | "membership" | "service" | no | membership: the buyer is a member until a date. service: the shop does something by hand each period. (default "membership") |
renewal_modes | array of "auto" | "link" | no | auto: a card charged each period. link: a payment link (PromptPay or card) sent into the buyer's chat each period. Default both. |
tagline | string | no | One line under the name, e.g. "For shops on Shopee and Lazada too". (max length 120) |
highlights | array of string | no | What's included, one short line each. The bot quotes them. (at most 12 items) |
audience | string | no | Who it's for, in one line. The bot uses it to suggest the right plan. (max length 300) |
not_included | array of string | no | What it doesn't include, so the bot never promises it. (at most 12 items) |
badge | "" | "popular" | "best_value" | no | "Most popular" or "Best value". |
sort | integer | no | Its place in the plan list: lowest first, then oldest. (min 0) (max 999) |
rules | object {cancel, pause, late, refund, change, terms_url} | no | Rules for members, which buyers are told (the bot quotes them). Each is a `mode` the sentence is written from, a `count` where the mode needs one, and the shop's own `text`, which replaces the sentence. An empty mode says nothing. |
rules.cancel | object {mode, count, text} | no | min_payments: after the first `count` payments. notice: `count` days' notice. |
rules.cancel.mode | "" | "any_time" | "min_payments" | "notice" | yes | |
rules.cancel.count | integer | null | no | (min 0) (max 3650) |
rules.cancel.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.pause | object {mode, count, text} | no | days: up to `count` days a year. |
rules.pause.mode | "" | "no" | "days" | yes | |
rules.pause.count | integer | null | no | (min 0) (max 3650) |
rules.pause.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.late | object {mode, count, text} | no | grace: the member keeps the plan `count` days after a missed payment. |
rules.late.mode | "" | "stop" | "grace" | yes | |
rules.late.count | integer | null | no | (min 0) (max 3650) |
rules.late.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.refund | object {mode, count, text} | no | days: a full refund within `count` days of the first payment. |
rules.refund.mode | "" | "none" | "days" | "pro_rata" | yes | |
rules.refund.count | integer | null | no | (min 0) (max 3650) |
rules.refund.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.change | object {mode, count, text} | no | now: upgrade and pay the difference now. |
rules.change.mode | "" | "now" | "next_renewal" | yes | |
rules.change.count | integer | null | no | (min 0) (max 3650) |
rules.change.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.terms_url | string | no | A link to the shop's full terms. (max length 500) |
status | "draft" | "on_sale" | no | (default "draft") |
prices | array of object {label, amount, interval, interval_count, trial_days, setup_fee, total_payments, vat, vat_rate} | yes | (at least 1 items) (at most 10 items) |
prices[].label | string | no | Shown to buyers when a plan has more than one price, e.g. "Monthly" or "Yearly". (max length 60) |
prices[].amount | number | yes | Baht charged each period, VAT included. At least ฿10 (Stripe's smallest charge). (min 10) (max 999999) |
prices[].interval | "day" | "week" | "month" | "year" | yes | |
prices[].interval_count | integer | no | Every how many intervals: 3 with month = every 3 months. (min 1) (max 12) (default 1) |
prices[].trial_days | integer | no | Free days before the first charge. (min 0) (max 730) (default 0) |
prices[].setup_fee | number | no | A one-off joining fee on the first payment: 0 (none) or at least ฿10. (default 0) |
prices[].total_payments | integer | null | no | Stop after this many payments (a course paid in 4), or null: until cancelled. (min 1) (max 120) (default null) |
prices[].vat | "none" | "excluded" | "included" | no | How the price reads to buyers: included = "includes 7% VAT"; excluded = "plus 7% VAT" (only on a plan paid in the shop's own system: SSK charges `amount` as typed). Never changes what is charged. (default "none") |
prices[].vat_rate | number | no | (min 0) (max 30) (default 7) |
Request examples
monthly_draft
{
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"prices": [
{
"label": "Monthly",
"amount": 2621.5,
"interval": "month"
}
]
} monthly_and_yearly
{
"name": "ชมรมคนรักของเล่น",
"gives": "membership",
"renewal_modes": [
"link"
],
"prices": [
{
"label": "รายเดือน",
"amount": 199,
"interval": "month"
},
{
"label": "รายปี",
"amount": 1990,
"interval": "year"
}
]
}Response 201
The new plan.
ok
{
"code": 200,
"message": "Plan created as a draft",
"data": {
"plan": {
"id": "6730c1d2e3f4a5b6c7d8e9f0",
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"images": [],
"gives": "membership",
"renewal_modes": [
"auto",
"link"
],
"tagline": "An AI sales assistant for your LINE, Facebook and Instagram chats",
"highlights": [
"The bot answers LINE, Facebook and Instagram chats, 24/7",
"One inbox for every chat, with handover to your team"
],
"audience": "Shops that sell through LINE, Facebook or Instagram and get customer chats every day",
"not_included": [
"Shopee and Lazada chats"
],
"badge": "",
"sort": 1,
"rules": {
"cancel": {
"mode": "any_time",
"count": null,
"text": ""
},
"pause": {
"mode": "no",
"count": null,
"text": ""
},
"late": {
"mode": "",
"count": null,
"text": ""
},
"refund": {
"mode": "none",
"count": null,
"text": ""
},
"change": {
"mode": "now",
"count": null,
"text": ""
},
"terms_url": ""
},
"status": "draft",
"prices": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f1",
"label": "Monthly",
"amount": 2621.5,
"currency": "thb",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"setup_fee": 0,
"total_payments": null,
"vat": "included",
"vat_rate": 7,
"active": true
}
],
"created_at": "2026-11-12T08:00:00.000Z",
"updated_at": "2026-11-12T08:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 409: Refused as things stand. The message says what to do first; tell the owner.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
GET/subscriptions/plans/{id}#
One subscription plan with its prices.
Use when you need a plan's prices' ids, to stop or restart a price.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The plan's id from GET /subscriptions/plans. |
Response 200
The plan.
ok
{
"code": 200,
"message": "OK",
"data": {
"plan": {
"id": "6730c1d2e3f4a5b6c7d8e9f0",
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"images": [],
"gives": "membership",
"renewal_modes": [
"auto",
"link"
],
"tagline": "An AI sales assistant for your LINE, Facebook and Instagram chats",
"highlights": [
"The bot answers LINE, Facebook and Instagram chats, 24/7",
"One inbox for every chat, with handover to your team"
],
"audience": "Shops that sell through LINE, Facebook or Instagram and get customer chats every day",
"not_included": [
"Shopee and Lazada chats"
],
"badge": "",
"sort": 1,
"rules": {
"cancel": {
"mode": "any_time",
"count": null,
"text": ""
},
"pause": {
"mode": "no",
"count": null,
"text": ""
},
"late": {
"mode": "",
"count": null,
"text": ""
},
"refund": {
"mode": "none",
"count": null,
"text": ""
},
"change": {
"mode": "now",
"count": null,
"text": ""
},
"terms_url": ""
},
"status": "draft",
"prices": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f1",
"label": "Monthly",
"amount": 2621.5,
"currency": "thb",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"setup_fee": 0,
"total_payments": null,
"vat": "included",
"vat_rate": 7,
"active": true
}
],
"created_at": "2026-11-12T08:00:00.000Z",
"updated_at": "2026-11-12T08:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No plan (or price) with this id in the shop. List them with GET /subscriptions/plans.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
PATCH/subscriptions/plans/{id}#
Change a plan's text, or put it on sale, back to draft, or archive it.
Use to rename or describe a plan, or change its status: on_sale (customers can subscribe; needs the owner's yes and a ready Stripe account), draft (no new sign-ups, subscribers keep it) or archived (closed for good). Prices change with the price routes.
Safe to retry: yes. Sending the same values again changes nothing.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The plan's id from GET /subscriptions/plans. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
name | string | no | (min length 1) (max length 120) |
description | string | no | What the buyer gets, as the chat bot and the sign-up page show it. (max length 2000) |
images | array of string | no | (at most 8 items) |
gives | "membership" | "service" | no | membership: the buyer is a member until a date. service: the shop does something by hand each period. (default "membership") |
renewal_modes | array of "auto" | "link" | no | auto: a card charged each period. link: a payment link (PromptPay or card) sent into the buyer's chat each period. Default both. |
tagline | string | no | One line under the name, e.g. "For shops on Shopee and Lazada too". (max length 120) |
highlights | array of string | no | What's included, one short line each. The bot quotes them. (at most 12 items) |
audience | string | no | Who it's for, in one line. The bot uses it to suggest the right plan. (max length 300) |
not_included | array of string | no | What it doesn't include, so the bot never promises it. (at most 12 items) |
badge | "" | "popular" | "best_value" | no | "Most popular" or "Best value". |
sort | integer | no | Its place in the plan list: lowest first, then oldest. (min 0) (max 999) |
rules | object {cancel, pause, late, refund, change, terms_url} | no | Rules for members, which buyers are told (the bot quotes them). Each is a `mode` the sentence is written from, a `count` where the mode needs one, and the shop's own `text`, which replaces the sentence. An empty mode says nothing. |
rules.cancel | object {mode, count, text} | no | min_payments: after the first `count` payments. notice: `count` days' notice. |
rules.cancel.mode | "" | "any_time" | "min_payments" | "notice" | yes | |
rules.cancel.count | integer | null | no | (min 0) (max 3650) |
rules.cancel.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.pause | object {mode, count, text} | no | days: up to `count` days a year. |
rules.pause.mode | "" | "no" | "days" | yes | |
rules.pause.count | integer | null | no | (min 0) (max 3650) |
rules.pause.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.late | object {mode, count, text} | no | grace: the member keeps the plan `count` days after a missed payment. |
rules.late.mode | "" | "stop" | "grace" | yes | |
rules.late.count | integer | null | no | (min 0) (max 3650) |
rules.late.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.refund | object {mode, count, text} | no | days: a full refund within `count` days of the first payment. |
rules.refund.mode | "" | "none" | "days" | "pro_rata" | yes | |
rules.refund.count | integer | null | no | (min 0) (max 3650) |
rules.refund.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.change | object {mode, count, text} | no | now: upgrade and pay the difference now. |
rules.change.mode | "" | "now" | "next_renewal" | yes | |
rules.change.count | integer | null | no | (min 0) (max 3650) |
rules.change.text | string | no | The shop's own sentence; replaces the one written from `mode`. (max length 300) |
rules.terms_url | string | no | A link to the shop's full terms. (max length 500) |
status | "draft" | "on_sale" | "archived" | no |
Request examples
on_sale
{
"status": "on_sale"
} describe
{
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App. Cancel any time."
} details
{
"tagline": "For shops on Shopee and Lazada too",
"highlights": [
"Everything in Basic",
"The bot answers Shopee and Lazada chats"
],
"audience": "Shops that sell on Shopee or Lazada as well as chat",
"badge": "popular",
"sort": 2
} rules
{
"rules": {
"cancel": {
"mode": "any_time"
},
"pause": {
"mode": "no"
},
"refund": {
"mode": "none"
},
"change": {
"mode": "now"
}
}
}Response 200
The plan as saved.
ok
{
"code": 200,
"message": "Plan updated",
"data": {
"plan": {
"id": "6730c1d2e3f4a5b6c7d8e9f0",
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"images": [],
"gives": "membership",
"renewal_modes": [
"auto",
"link"
],
"tagline": "An AI sales assistant for your LINE, Facebook and Instagram chats",
"highlights": [
"The bot answers LINE, Facebook and Instagram chats, 24/7",
"One inbox for every chat, with handover to your team"
],
"audience": "Shops that sell through LINE, Facebook or Instagram and get customer chats every day",
"not_included": [
"Shopee and Lazada chats"
],
"badge": "",
"sort": 1,
"rules": {
"cancel": {
"mode": "any_time",
"count": null,
"text": ""
},
"pause": {
"mode": "no",
"count": null,
"text": ""
},
"late": {
"mode": "",
"count": null,
"text": ""
},
"refund": {
"mode": "none",
"count": null,
"text": ""
},
"change": {
"mode": "now",
"count": null,
"text": ""
},
"terms_url": ""
},
"status": "on_sale",
"prices": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f1",
"label": "Monthly",
"amount": 2621.5,
"currency": "thb",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"setup_fee": 0,
"total_payments": null,
"vat": "included",
"vat_rate": 7,
"active": true
}
],
"created_at": "2026-11-12T08:00:00.000Z",
"updated_at": "2026-11-12T08:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No plan (or price) with this id in the shop. List them with GET /subscriptions/plans.
- 409: Refused as things stand. The message says what to do first; tell the owner.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
POST/subscriptions/plans/{id}/prices#
Add a price to a plan (a new amount or period).
Use to offer another period (yearly beside monthly) or change an amount: add the new price, then stop the old one with PATCH .../prices/{priceId}.
Safe to retry: no. Each call adds a price; check the plan's prices before sending again.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The plan's id from GET /subscriptions/plans. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
label | string | no | Shown to buyers when a plan has more than one price, e.g. "Monthly" or "Yearly". (max length 60) |
amount | number | yes | Baht charged each period, VAT included. At least ฿10 (Stripe's smallest charge). (min 10) (max 999999) |
interval | "day" | "week" | "month" | "year" | yes | |
interval_count | integer | no | Every how many intervals: 3 with month = every 3 months. (min 1) (max 12) (default 1) |
trial_days | integer | no | Free days before the first charge. (min 0) (max 730) (default 0) |
setup_fee | number | no | A one-off joining fee on the first payment: 0 (none) or at least ฿10. (default 0) |
total_payments | integer | null | no | Stop after this many payments (a course paid in 4), or null: until cancelled. (min 1) (max 120) (default null) |
vat | "none" | "excluded" | "included" | no | How the price reads to buyers: included = "includes 7% VAT"; excluded = "plus 7% VAT" (only on a plan paid in the shop's own system: SSK charges `amount` as typed). Never changes what is charged. (default "none") |
vat_rate | number | no | (min 0) (max 30) (default 7) |
Request examples
yearly
{
"label": "Yearly",
"amount": 26215,
"interval": "year"
} with_trial
{
"label": "Monthly, 7 days free",
"amount": 2621.5,
"interval": "month",
"trial_days": 7
}Response 201
The plan with its new price.
ok
{
"code": 200,
"message": "Price added",
"data": {
"plan": {
"id": "6730c1d2e3f4a5b6c7d8e9f0",
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"images": [],
"gives": "membership",
"renewal_modes": [
"auto",
"link"
],
"tagline": "An AI sales assistant for your LINE, Facebook and Instagram chats",
"highlights": [
"The bot answers LINE, Facebook and Instagram chats, 24/7",
"One inbox for every chat, with handover to your team"
],
"audience": "Shops that sell through LINE, Facebook or Instagram and get customer chats every day",
"not_included": [
"Shopee and Lazada chats"
],
"badge": "",
"sort": 1,
"rules": {
"cancel": {
"mode": "any_time",
"count": null,
"text": ""
},
"pause": {
"mode": "no",
"count": null,
"text": ""
},
"late": {
"mode": "",
"count": null,
"text": ""
},
"refund": {
"mode": "none",
"count": null,
"text": ""
},
"change": {
"mode": "now",
"count": null,
"text": ""
},
"terms_url": ""
},
"status": "draft",
"prices": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f1",
"label": "Monthly",
"amount": 2621.5,
"currency": "thb",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"setup_fee": 0,
"total_payments": null,
"vat": "included",
"vat_rate": 7,
"active": true
}
],
"created_at": "2026-11-12T08:00:00.000Z",
"updated_at": "2026-11-12T08:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No plan (or price) with this id in the shop. List them with GET /subscriptions/plans.
- 409: Refused as things stand. The message says what to do first; tell the owner.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
PATCH/subscriptions/plans/{id}/prices/{priceId}#
Stop a price for new sign-ups, take sign-ups on it again, or set how its VAT reads.
Use when a price is replaced: active: false stops new sign-ups on it; its subscribers keep paying it. A plan on sale keeps at least one active price. vat / vat_rate change only how the price reads to buyers.
Safe to retry: yes.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
id (path) | string | yes | The plan's id from GET /subscriptions/plans. |
priceId (path) | string | yes | The price's id, from the plan's `prices`. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
active | boolean | no | |
vat | "none" | "excluded" | "included" | no | How the price reads to buyers: included = "includes 7% VAT"; excluded = "plus 7% VAT" (only on a plan paid in the shop's own system: SSK charges `amount` as typed). Never changes what is charged. (default "none") |
vat_rate | number | no | (min 0) (max 30) (default 7) |
Request examples
stop
{
"active": false
} restart
{
"active": true
} vat_included
{
"vat": "included"
}Response 200
The plan as saved.
ok
{
"code": 200,
"message": "Price stopped for new sign-ups",
"data": {
"plan": {
"id": "6730c1d2e3f4a5b6c7d8e9f0",
"name": "SellerSidekick Basic",
"description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App.",
"images": [],
"gives": "membership",
"renewal_modes": [
"auto",
"link"
],
"tagline": "An AI sales assistant for your LINE, Facebook and Instagram chats",
"highlights": [
"The bot answers LINE, Facebook and Instagram chats, 24/7",
"One inbox for every chat, with handover to your team"
],
"audience": "Shops that sell through LINE, Facebook or Instagram and get customer chats every day",
"not_included": [
"Shopee and Lazada chats"
],
"badge": "",
"sort": 1,
"rules": {
"cancel": {
"mode": "any_time",
"count": null,
"text": ""
},
"pause": {
"mode": "no",
"count": null,
"text": ""
},
"late": {
"mode": "",
"count": null,
"text": ""
},
"refund": {
"mode": "none",
"count": null,
"text": ""
},
"change": {
"mode": "now",
"count": null,
"text": ""
},
"terms_url": ""
},
"status": "draft",
"prices": [
{
"id": "6730c1d2e3f4a5b6c7d8e9f1",
"label": "Monthly",
"amount": 2621.5,
"currency": "thb",
"interval": "month",
"interval_count": 1,
"trial_days": 0,
"setup_fee": 0,
"total_payments": null,
"vat": "included",
"vat_rate": 7,
"active": true
}
],
"created_at": "2026-11-12T08:00:00.000Z",
"updated_at": "2026-11-12T08:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No plan (or price) with this id in the shop. List them with GET /subscriptions/plans.
- 409: Refused as things stand. The message says what to do first; tell the owner.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Connected plans
Report what happened to customers of plans your own system takes the payment for.
POST/connected-plans/events#
Report a sign-up, payment, renewal, cancellation or failed payment from your own system.
Use when your system signs up or charges a customer who came through SSK's sign-up link (ssk_ref).
Safe to retry: yes, with the same idempotency_key.
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
idempotency_key | string | yes | Your own unique id for this event (an invoice id, a webhook event id). The same key is never recorded twice. (max length 120) |
event | "signed_up" | "paid" | "renewed" | "cancelled" | "payment_failed" | yes | |
ref | string | no | The `ssk_ref` from the customer's sign-up link. (max length 64) |
plan_code | string | no | The price's code in your system (the plan's prices in SSK carry the same `plan_code`). (max length 60) |
amount | number | no | What the customer paid, in the currency's units (baht). 0 for a free plan: never counts as a sale. (min 0) |
currency | string | no | (min length 3) (max length 3) (default "thb") |
period_end | string | no | Until when this payment covers the customer; for `cancelled`, when it ends. (format date-time) |
occurred_at | string | no | (format date-time) |
external_customer_id | string | no | Your own id for the customer. (max length 120) |
email | string | no | (max length 200) (format email) |
phone | string | no | (max length 30) |
Request examples
paid
{
"idempotency_key": "inv_2026_11_0042",
"event": "paid",
"ref": "q3Xn0d8kZ1bWcA2e",
"plan_code": "pro_monthly",
"amount": 3690,
"period_end": "2026-12-12T00:00:00Z"
} no_link
{
"idempotency_key": "evt_88",
"event": "signed_up",
"plan_code": "pro_monthly",
"email": "owner@example.com"
} cancelled
{
"idempotency_key": "sub_1_cancel",
"event": "cancelled",
"ref": "q3Xn0d8kZ1bWcA2e",
"period_end": "2027-01-12T00:00:00Z"
}Response 200
This idempotency_key was recorded before: the first answer, nothing changed.
again
{
"code": 200,
"message": "Already recorded",
"data": {
"event_id": "6735f0c2a1b2c3d4e5f60789",
"duplicate": true,
"match": "ref",
"lead_id": "6735e1aa0b1c2d3e4f506172",
"lead_status": "won",
"subscription": {
"id": "6735f0c2a1b2c3d4e5f6078a",
"status": "active",
"paid_until": "2026-12-12T00:00:00.000Z"
}
}
}Response 201
Recorded.
recorded
{
"code": 201,
"message": "Event recorded",
"data": {
"event_id": "6735f0c2a1b2c3d4e5f60789",
"duplicate": false,
"match": "ref",
"lead_id": "6735e1aa0b1c2d3e4f506172",
"lead_status": "won",
"subscription": {
"id": "6735f0c2a1b2c3d4e5f6078a",
"status": "active",
"paid_until": "2026-12-12T00:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: The `ref` isn't a sign-up link of this shop. Check you send the code from the link exactly.
- 409: The same event is being recorded right now. Send it again in a few seconds with the same key.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
Lead capture
How the chat bot sells a product or plan through the shop's sales team: the lead form, who fits, the brief and the promise.
GET/leads/items/{kind}/{id}#
Read how the bot sells a product or plan: its lead form, who fits, the brief and the promise.
Use before changing them, to see what is saved (saved: false shows SSK's starter form).
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
kind (path) | "product" | "plan" | yes | |
id (path) | string | yes | The product's or plan's id. |
Response 200
The settings.
saved
{
"code": 200,
"message": "Lead settings retrieved",
"data": {
"kind": "plan",
"id": "6af558ef1b05a7659e658089",
"name": "Pro",
"saved": true,
"lead": {
"enabled": true,
"fields": [
{
"key": "name",
"description": "The person's name",
"required": true,
"name": "Name",
"kind": "text"
},
{
"key": "phone",
"description": "A phone number our team can call",
"required": true,
"name": "Phone",
"kind": "phone"
},
{
"key": "chats_a_day",
"description": "Roughly how many customer chats they get a day",
"required": false,
"name": "Chats a day",
"kind": "number"
},
{
"key": "when_to_start",
"description": "",
"required": false,
"name": "When to start",
"kind": "choice",
"options": [
"This week",
"This month",
"Later, just looking"
]
}
],
"qualify": {
"text": "Sells on Shopee or Lazada and gets customer chats every day.",
"rules": [
{
"field": "chats_a_day",
"op": ">=",
"value": 20,
"then": "fit"
}
]
},
"brief": "Ask a few details at a time, in plain words.",
"promise": "Our team will contact you within 1 working day.",
"meeting": {
"enabled": false,
"kind": "phone",
"length_minutes": 30,
"hours": [
{
"day": 1,
"from": "10:00",
"to": "17:00"
}
],
"gap_minutes": 15,
"notice_hours": 2,
"ahead_days": 14,
"timezone": "Asia/Bangkok",
"address": "",
"map_url": "",
"hosts_count": 0
},
"updated_at": "2026-11-14T03:00:00.000Z"
}
}
}Errors
- 400: The request is invalid. The message names the field; fix it and send again. Unknown fields are refused by name.
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No product or plan with this id in this shop.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
PATCH/leads/items/{kind}/{id}#
Change how the bot sells a product or plan: switch lead capture on or off, set the form, who fits, the brief and the promise.
Use to have the bot collect leads for an item instead of selling it, or to change its form. Send only what changes; fields replaces the whole form.
Safe to retry: yes, the same change twice saves the same settings.
Parameters
| Field | Type | Required | Description |
|---|---|---|---|
kind (path) | "product" | "plan" | yes | |
id (path) | string | yes | The product's or plan's id. |
Request body (required)
| Field | Type | Required | Description |
|---|---|---|---|
enabled | boolean | no | true: the bot collects a lead instead of selling the item. |
fields | array of object {key, name, description, kind, options, required} | no | The whole form: replaces the saved fields. (at most 30 items) |
fields[].key | string | no | Stable id (a-z, 0-9, _). Made from the name when left out. (max length 40) |
fields[].name | string | yes | (max length 80) |
fields[].description | string | no | What it means and how to ask, in plain words. The bot reads it. (max length 500) |
fields[].kind | "text" | "number" | "phone" | "email" | "choice" | "yes_no" | "date" | no | (default "text") |
fields[].options | array of string | no | The choices, for `kind: choice`. (at most 30 items) |
fields[].required | boolean | no | (default false) |
qualify | object {text, rules} | no | |
qualify.text | string | no | (max length 2000) |
qualify.rules | array of object {field, op, value, then} | no | (at most 20 items) |
qualify.rules[].field | string | yes | A field's key. |
qualify.rules[].op | ">=" | "<=" | "=" | "!=" | "in" | yes | |
qualify.rules[].value | any | yes | A number, a text, or a list of texts for `in`. |
qualify.rules[].then | "fit" | "not_fit" | no | (default "fit") |
brief | string | no | (max length 2000) |
promise | string | no | (max length 300) |
meeting | object {enabled, kind, address, map_url, length_minutes, hours, gap_minutes, notice_hours, ahead_days, timezone} | no | Changes only what it names. Hosts are chosen in the dashboard. |
meeting.enabled | boolean | no | |
meeting.kind | "phone" | "meet" | "in_person" | no | |
meeting.address | string | no | For a meeting in person. (max length 300) |
meeting.map_url | string | no | (max length 500) |
meeting.length_minutes | 30 | no | |
meeting.hours | array of object {day, from, to} | no | (at most 21 items) |
meeting.hours[].day | integer | no | 0 = Sunday. (min 0) (max 6) |
meeting.hours[].from | string | no | |
meeting.hours[].to | string | no | |
meeting.gap_minutes | integer | no | (min 0) (max 60) |
meeting.notice_hours | integer | no | (min 0) (max 72) |
meeting.ahead_days | integer | no | (min 1) (max 60) |
meeting.timezone | string | no |
Request examples
switch_on
{
"enabled": true,
"fields": [
{
"name": "Name",
"description": "The person's name",
"kind": "text",
"required": true
},
{
"name": "Phone",
"description": "A phone number our team can call",
"kind": "phone",
"required": true
},
{
"name": "Chats a day",
"description": "Roughly how many customer chats they get a day",
"kind": "number"
},
{
"name": "When to start",
"kind": "choice",
"options": [
"This week",
"This month",
"Later, just looking"
]
}
],
"qualify": {
"text": "Sells on Shopee or Lazada and gets customer chats every day.",
"rules": [
{
"field": "chats_a_day",
"op": ">=",
"value": 20,
"then": "fit"
}
]
},
"brief": "Ask a few details at a time, in plain words.",
"promise": "Our team will contact you within 1 working day."
} promise_only
{
"promise": "Our team will call you today."
} switch_off
{
"enabled": false
}Response 200
Saved: the settings as they are now.
saved
{
"code": 200,
"message": "Lead settings saved",
"data": {
"kind": "plan",
"id": "6af558ef1b05a7659e658089",
"name": "Pro",
"saved": true,
"lead": {
"enabled": true,
"fields": [
{
"key": "name",
"description": "The person's name",
"required": true,
"name": "Name",
"kind": "text"
},
{
"key": "phone",
"description": "A phone number our team can call",
"required": true,
"name": "Phone",
"kind": "phone"
},
{
"key": "chats_a_day",
"description": "Roughly how many customer chats they get a day",
"required": false,
"name": "Chats a day",
"kind": "number"
},
{
"key": "when_to_start",
"description": "",
"required": false,
"name": "When to start",
"kind": "choice",
"options": [
"This week",
"This month",
"Later, just looking"
]
}
],
"qualify": {
"text": "Sells on Shopee or Lazada and gets customer chats every day.",
"rules": [
{
"field": "chats_a_day",
"op": ">=",
"value": 20,
"then": "fit"
}
]
},
"brief": "Ask a few details at a time, in plain words.",
"promise": "Our team will contact you within 1 working day.",
"meeting": {
"enabled": false,
"kind": "phone",
"length_minutes": 30,
"hours": [
{
"day": 1,
"from": "10:00",
"to": "17:00"
}
],
"gap_minutes": 15,
"notice_hours": 2,
"ahead_days": 14,
"timezone": "Asia/Bangkok",
"address": "",
"map_url": "",
"hosts_count": 0
},
"updated_at": "2026-11-14T03:00:00.000Z"
}
}
}Errors
- 400: The settings don't fit the rules. The message names the problem (e.g. `need_a_required_field`, `rule_field_unknown:<key>`, `field_options_missing:<key>`, `meeting_needs_a_host`).
- 401 (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- 403 (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- 404: No product or plan with this id in this shop.
- 429 (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.