# SellerSideKick developer docs (full text) > SellerSideKick is an AI chatbot and back office for online shops that sell on LINE, Facebook (Messenger), Instagram, TikTok, Shopee and Lazada. Every English guide, then the API reference. Each part starts with its source URL. --- # SellerSideKick developer docs > Let an AI assistant or a script read and update your shop's products, stock and promotions. SellerSideKick is an AI chatbot and back office for online shops that sell on LINE, Facebook (Messenger), Instagram, TikTok, Shopee and Lazada. These docs cover one job: letting an AI assistant or a script work on a shop's catalogue for you. The usual case: you have an Excel sheet of new prices, a stock count or a list of new products. You hand it to Claude, ChatGPT or Gemini, the assistant shows you what it is about to change, you say yes, and it applies the sheet. ## Two ways in | | AI-assistant connector | Shop API key | |---|---|---| | For | Claude, ChatGPT, Gemini Enterprise, Gemini CLI | coding tools, scripts, your own integrations | | Address | `https://mcp.sellersidekick.ai/mcp` | `https://api.sellersidekick.ai/v1/api` | | How it signs in | you sign in with SellerSideKick, pick the shop and the permissions | a key (`ssk_…`) you create in **Settings → API keys** | | Revoke | **Settings → API keys → Connected AI assistants** (Disconnect) | **Settings → API keys** (Revoke) | Start with the connector if you use a chat assistant. Use a key only when a program needs one. See [Connect ChatGPT, Claude or Gemini](https://docs.sellersidekick.ai/connect-ai-assistant). ## What you can do - **Prices and product details:** change prices, names, descriptions, categories and brands by SKU. See [Update prices](https://docs.sellersidekick.ai/update-prices). - **Stock:** set counted stock or add and remove units. See [Update stock counts](https://docs.sellersidekick.ai/update-stock). - **New products and variants:** add products, with sizes or colours as variants. See [Add new products and variants](https://docs.sellersidekick.ai/add-products). - **Promotions:** create coupons, discounts, bundles and buy-X-get-Y offers, change them, pause them or end them. See [Promotions](https://docs.sellersidekick.ai/promotions). ## Rules that apply everywhere - **Monthly plans only.** The connector and API keys work while the shop is on a monthly plan (such as Pro or Pro Plus), not on Basic (pay-as-you-go coins). - **Preview first.** Every write can run as a dry run that changes nothing. A good assistant always shows you the preview and waits for your yes. - **Up to 500 rows per request.** Bigger sheets are split. Each row succeeds or fails on its own. A promotion's product list is the exception: up to 5,000 SKUs, always sent whole. - **Nothing is deleted.** Products are created and updated; promotions are archived, not deleted. - **SellerSideKick products only.** A SKU that exists only on a marketplace has to be added to your SellerSideKick store from the dashboard first. ## What reaches the marketplaces - **Stock counts** reach your linked Shopee, Lazada and TikTok listings, usually within about 10 minutes. - **Prices, names, descriptions and promotions** change your SellerSideKick store and chat bot only. Marketplace prices and listings are still edited in each marketplace's seller center. ## For AI agents - Every page has a Markdown copy: add `.md` to its address, for example [/docs/update-stock.md](https://docs.sellersidekick.ai/update-stock.md). - [llms.txt](https://docs.sellersidekick.ai/llms.txt) lists every page; [llms-full.txt](https://docs.sellersidekick.ai/llms-full.txt) has them all in one file. - The [API reference](https://docs.sellersidekick.ai/reference) is generated from the OpenAPI spec at `https://api.sellersidekick.ai/v1/api/openapi.json`. --- # Quickstart: update your catalogue from Excel with an AI assistant > Connect Claude, ChatGPT or Gemini to your shop, give it a spreadsheet, check its preview and apply it. About ten minutes. This is for shop owners. You need a SellerSideKick shop on a monthly plan (such as Pro or Pro Plus) and an AI assistant that can use connectors: Claude, ChatGPT or Gemini. ## 1. Prepare the sheet One row per product, matched by **SKU** (your own product code). Use the columns you need: | Column | Example | Notes | |---|---|---| | SKU | `TM-001` | Required on every row. | | Name | `รถเหล็กโทมิก้า รุ่นรถตำรวจ` | Thai, English or both. | | Price | `139` | In THB. | | Stock | `40` | Units on the shelf now. | | Category | `Toys` | Must be one of your shop's categories. | | Brand | `Tomica` | A new brand is added for you. | | Parent SKU | `SHIRT-01` | Only for a variant (a size or colour of another product). | Any layout works; the assistant maps your columns. Keep one SKU per row. ## 2. Connect your assistant Add the SellerSideKick connector at `https://mcp.sellersidekick.ai/mcp`, sign in with your SellerSideKick account, pick the shop and tick the permissions: - `catalog:read`, reading your shop, categories, products and promotions, is always on. - `catalog:write` for prices, product details and new products. - `stock:write` for stock counts. - `promotions:write` only if you want the assistant to change promotions. - `bot:write` only if you want the assistant to change the chat bot's Playbook and FAQ. Step-by-step for each assistant: [Connect ChatGPT, Claude or Gemini](https://docs.sellersidekick.ai/connect-ai-assistant). ## 3. Give it the sheet Attach the file and say what you want. For example: > Here is my price list. Update the prices in my SellerSideKick shop. Show me the preview first and wait for my OK. > This is today's stock count. Set the stock in SellerSideKick to these numbers. Preview first. > Add the new products in this sheet. The "Size" column makes variants of the main product. ## 4. Check the preview The assistant runs a **dry run** first: nothing changes yet. It should tell you which shop it is working on and show: - how many rows would be created, updated or left unchanged; - every row with an **error** and why, for example an unknown category or a SKU that exists only on a marketplace. Fix the sheet or tell the assistant how to handle the error rows. When the preview looks right, say yes. ## 5. Apply and check The assistant sends the same rows for real and reports the result. Open the dashboard at [app.sellersidekick.ai](https://app.sellersidekick.ai) to see the changes. Every change made through the connector is listed with its before and after values in **Settings → API keys**. ## What happens on the marketplaces - **Stock** reaches your linked Shopee, Lazada and TikTok listings, usually within about 10 minutes. - **Prices and product details** change your SellerSideKick store and chat bot only. Change marketplace prices in each marketplace's seller center. ## If something goes wrong - **"Not on a monthly plan":** the connector works on Pro and Pro Plus. See current plans in the app. - **A row says the SKU is not on your SellerSideKick store:** the product exists only on a marketplace. Add it to your store from the dashboard first. - **"Missing permission":** reconnect and tick the permission the assistant asked for. - More: [Errors and limits](https://docs.sellersidekick.ai/errors-and-limits). --- # Connect ChatGPT, Claude or Gemini > Add the SellerSideKick connector to your AI assistant, or create an API key for coding tools and scripts. There are two ways to let an AI work on your shop. Use the **connector** for chat assistants. Use an **API key** for coding tools, scripts and your own programs. Both work only while your shop is on a monthly plan (such as Pro or Pro Plus), and only an owner or an admin who can manage API keys can set them up. ## The connector The connector is an MCP server (Streamable HTTP) at: ``` https://mcp.sellersidekick.ai/mcp ``` When you add it, your assistant opens a SellerSideKick sign-in page. You sign in, choose **one shop**, tick the permissions and approve. The assistant never sees your password, and you can disconnect it at any time in **Settings → API keys → Connected AI assistants**. ### Permissions | Permission | Lets the assistant | Default | |---|---|---| | `catalog:read` | see the shop, its categories, products with price and stock, and promotions | always on | | `catalog:write` | create products and change prices, names, descriptions, categories and brands | ticked if the assistant asks for it | | `stock:write` | set or adjust stock | ticked if the assistant asks for it | | `promotions:write` | create, change, pause and archive promotions | off until you tick it | | `bot:write` | change the chat bot's Playbook and FAQ | off until you tick it | The sign-in page lists only what the assistant asked for. Untick what the job doesn't need; you can reconnect later with more. ### Tools the assistant gets | Tool | What it does | Needs | |---|---|---| | `whoami` | names the shop it is connected to | `catalog:read` | | `find_products` | looks up products by SKU, or page by page | `catalog:read` | | `list_categories` | lists the category names products may use | `catalog:read` | | `preview_catalog_update` | dry run of a product update: changes nothing | `catalog:write` | | `apply_catalog_update` | creates and updates products | `catalog:write` | | `preview_stock_change` | dry run of a stock change | `stock:write` | | `apply_stock_change` | sets or adjusts stock | `stock:write` | | `list_promotions` | lists the shop's own promotions | `catalog:read` | | `create_promotion` | creates a coupon, discount, bundle or BOGO | `promotions:write` | | `update_promotion` | changes a promotion's fields | `promotions:write` | | `set_promotion_status` | sets a promotion active, inactive or archived | `promotions:write` | | `get_bot_playbook_and_faq` | reads the chat bot's Playbook and FAQ | `catalog:read` | | `preview_playbook_update` / `apply_playbook_update` | replaces the Playbook (dry run, then apply) | `bot:write` | | `preview_faq_update` / `apply_faq_update` | adds, updates or removes FAQ questions (dry run, then apply) | `bot:write` | The read tools are marked read-only and the preview tools change nothing. Most assistants ask you before they run a write tool; either way, ask yours to show you the preview and wait for your yes. ### Claude - **Claude (web and desktop):** open **Settings → Connectors**, choose **Add custom connector**, paste `https://mcp.sellersidekick.ai/mcp`, then **Connect** and sign in. On Team and Enterprise plans an owner may need to add it for the organisation first. Once SellerSideKick is listed in the Claude connectors directory you can add it from there instead. - **Claude Code:** run `claude mcp add --transport http sellersidekick https://mcp.sellersidekick.ai/mcp`, then type `/mcp` in Claude Code and choose **Authenticate**. ### ChatGPT - Turn on **developer mode** (in **Settings → Apps & Connectors → Advanced settings**), then create a connector with the URL `https://mcp.sellersidekick.ai/mcp` and OAuth sign-in. Developer mode is available on some ChatGPT plans only, and menu names can change; search ChatGPT's help for "developer mode" if you can't find it. - Once SellerSideKick is listed in the ChatGPT apps directory, you can add it from there without developer mode. ### Gemini Enterprise An administrator adds SellerSideKick as a custom MCP server: | Setting | Value | |---|---| | Transport | Streamable HTTP | | Server URL | `https://mcp.sellersidekick.ai/mcp` | | Authorization URL | `https://api.sellersidekick.ai/v1/oauth/authorize` | | Token URL | `https://api.sellersidekick.ai/v1/oauth/token` | | Scopes | `catalog:read catalog:write stock:write promotions:write bot:write` (drop the ones you don't want) | | Client ID and secret | issued by us: email team@kuztom.ai with the redirect URL Gemini Enterprise shows you | Each person then signs in with their own SellerSideKick account the first time they use it. ### Gemini CLI Add the server to `~/.gemini/settings.json`: ```json { "mcpServers": { "sellersidekick": { "httpUrl": "https://mcp.sellersidekick.ai/mcp" } } } ``` Start Gemini CLI and run `/mcp auth sellersidekick` to sign in. ### Other MCP clients Any client that supports remote MCP servers over Streamable HTTP with OAuth sign-in can connect. The server publishes its sign-in details at `https://mcp.sellersidekick.ai/.well-known/oauth-protected-resource/mcp`. ## An API key, for coding tools and scripts 1. In the dashboard ([app.sellersidekick.ai](https://app.sellersidekick.ai)), open **Settings → API keys** and choose **Create key**. 2. Name it after its job (for example "Price sheet script"), choose its **access** (full access, read only, or pick the permissions above) and when it **expires** (never, or after 30, 90 or 365 days). 3. Copy the key. It starts with `ssk_` and is shown **once**. Keep it in your tool's secret settings or an environment variable, never in a chat message or a shared file. 4. Give your tool the instructions shown on the same page. They point it at the [OpenAPI spec](https://api.sellersidekick.ai/v1/api/openapi.json) and the rules: confirm the shop, preview first, at most 500 rows per request. Check the key works: ```bash curl -H "Authorization: Bearer $SSK_API_KEY" https://api.sellersidekick.ai/v1/api/me ``` The answer names the shop the key belongs to. A key acts for one shop only and in the name of the person who created it. See [Security](https://docs.sellersidekick.ai/security) for what happens when that person leaves the shop. --- # Update prices > Change prices, names, descriptions, categories and brands of existing products by SKU, with a preview first. Prices and product details are changed by **SKU**. Only the fields you send change; everything else stays as it is. - Connector: `preview_catalog_update`, then `apply_catalog_update` (permission `catalog:write`). - API: `POST /products/upsert` with `dry_run: true`, then the same body with `dry_run: false`. ## Steps 1. **Confirm the shop.** Connector: `whoami`. API: `GET /me`. Tell the owner the shop name. 2. **Read the current values** for the SKUs in the sheet: `find_products` or `GET /products?sku=TM-001,TM-002` (up to 500 per page with `limit`). This shows what will change and which SKUs don't exist yet. 3. **Preview.** Send the rows as a dry run. Show the owner the summary and every `error` row. 4. **Apply** after a clear yes. Report the summary and any `error` rows. ## Request ```json { "dry_run": true, "products": [ { "sku": "TM-001", "price": 139 }, { "sku": "TM-002", "price": 159, "name": { "th": "รถบัสโทมิก้า", "en": "Tomica bus" } } ] } ``` - `price` is in THB, 0 or more. - `name`, `description` and `usage_information` take a string (the Thai text; the English text is kept) or `{ "th": "…", "en": "…" }` to set either or both. - `category` must be one of the names from `list_categories` / `GET /categories` (any case). `brand` may be new: it is added to the shop's brand list. - Don't send `stock` or `parent_sku` for an existing SKU: that row comes back as an error. Stock has [its own call](https://docs.sellersidekick.ai/update-stock). - At most 500 rows per request. Each SKU once per request. ## Result Each row gets a status: | Status | Meaning | |---|---| | `updated` | changed; `changed` lists the fields, e.g. `["price"]` | | `unchanged` | the values were already the same | | `created` | the SKU was new and has been created (see [Add new products](https://docs.sellersidekick.ai/add-products)) | | `error` | not applied; `error` says why | In a dry run the statuses say what would happen and nothing is written. Sending the same rows again is safe: they come back `unchanged`. ## What changes where The new price shows on your SellerSideKick store and the chat bot answers with it. **Marketplace listings keep their own prices**: change those in the Shopee, Lazada or TikTok seller center. When an owner asks for marketplace prices, say so plainly. --- # Update stock counts > Set counted stock or add and remove units by SKU, safely retried with an idempotency key. Reaches linked marketplace listings. Stock is the units **on hand** (on the shelf). **Available** is on hand minus what open orders hold: what can still be sold. - Connector: `preview_stock_change`, then `apply_stock_change` (permission `stock:write`). - API: `POST /stock`. Stock changes only through this call, never through the product update. ## Count or adjust Each row sends **one** of: - `value`: the units now on the shelf, from a count. 0 or more. - `delta`: units to add (positive) or remove (negative), for example `-3` for damaged goods. Not 0. Optional per row: - `expected_from` (with `value` only): the on-hand you read before. If it has changed since, the row is refused instead of overwritten. Use it when time passes between reading and writing. - `reason`: up to 200 characters, shown in the shop's stock history, e.g. `monthly count`. ## Request ```json { "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", "delta": -3, "reason": "damaged in transit" } ] } ``` ## Retrying safely Give each new change its own `idempotency_key` (8–100 characters: letters, digits and `. _ : -`). If the call times out, send the **same request with the same key**: rows already applied come back `already_applied` and are not applied twice. Never reuse a key for a different change: a row with different numbers under a reused key is applied. ## Result | Status | Meaning | |---|---| | `would_update` | dry run: `from`, `to` and `available` show what would happen | | `updated` | applied: `from` (on hand before), `to` (on hand after), `available` | | `already_applied` | this row was already applied under this idempotency key | | `error` | not applied; `error` says why | A dry run checks each row's shape, that the SKU is on your SellerSideKick store and `expected_from`. It does **not** check holds by open orders, a `delta` on a SKU that was never counted, or a replay, so the real call can still answer some rows with `error` or `already_applied`. - A `delta` can't take on hand below what open orders hold. A counted `value` is recorded as counted, even below that. - Only SKUs on your SellerSideKick store: a SKU that is only on a marketplace is an error row and is never sent anywhere. ## What reaches the marketplaces Stock changes are recorded in the shop's stock history and sent to the SKU's linked Shopee, Lazada and TikTok listings, usually within about 10 minutes. --- # Add new products and variants > Create products by SKU with names, price, category, brand, pictures and opening stock, and make sizes or colours variants of a main product. New products go through the same call as updates: a SKU the shop doesn't have yet is created. - Connector: `preview_catalog_update`, then `apply_catalog_update` (permission `catalog:write`). - API: `POST /products/upsert`. ## Required fields for a new SKU | Field | Notes | |---|---| | `sku` | your product code, up to 100 characters | | `name` | a string (Thai) or `{ "th": "…", "en": "…" }` | | `price` | THB | | `category` | a name from `list_categories` / `GET /categories` | | `brand` | a new brand is added to the shop's list | Optional: `description`, `usage_information` (how to use or care for it), `images` (picture links, see below), `stock` (the opening count on the shelf; it needs the `stock:write` permission as well as `catalog:write`), `parent_sku` (makes it a variant). ## Example ```json { "dry_run": true, "products": [ { "sku": "TM-010", "name": { "th": "รถดับเพลิงโทมิก้า", "en": "Tomica fire engine" }, "price": 189, "category": "Toys", "brand": "Tomica", "stock": 12 } ] } ``` ## Pictures Give a product's pictures as links in `images`: 1 to 7, the first is the main picture. They replace the product's pictures, on a new product or an existing one. - Each picture is downloaded and copied onto SellerSideKick, so the link must be a public web address of the picture itself (JPEG, PNG or WebP, up to 15 MB), not a web page that shows it. - 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 without downloading it. - Sending the same links again changes nothing. - Pictures you have as files (API only): upload them with `POST /images` (`multipart/form-data`, field `images`, up to 7 files of 10 MB each). It answers each file's link; put those in `images`. ```json { "dry_run": true, "products": [ { "sku": "TM-011", "name": "รถตำรวจโทมิก้า", "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"] } ] } ``` ## Variants A variant is a size, colour or other option of a main product. Create the main product and give each variant `parent_sku`. The main product may be created in the same request: ```json { "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 } ] } ``` - `parent_sku` must name a main product on your SellerSideKick store, or one created in the same request. It can't be another variant or a product that exists only on a marketplace. - `stock` and `parent_sku` are for **new** products only. Sending them for an existing SKU is an error row; change stock with [Update stock counts](https://docs.sellersidekick.ai/update-stock). ## Common error rows - **Unknown category:** map the sheet's category to one of the shop's names. - **The SKU exists only on a marketplace:** add it to the SellerSideKick store from the dashboard first. - **The same SKU twice** in one request: keep one row per SKU. - **Missing required field** on a new SKU: add `name`, `price`, `category` and `brand`. - **A picture can't be used:** the message names the picture and why (not a public address, the server answered 404, larger than 15 MB). Fix or drop that link. New products appear on the SellerSideKick store and the chat bot can recommend them. A new product's opening stock reaches a marketplace listing once a listing with the same SKU is linked to it. --- # Promotions > Create coupons, discounts, bundles and buy-X-get-Y offers, change them, pause them or end them by archiving. These are the shop's own SellerSideKick promotions. They apply on the SellerSideKick store and in the chat bot. Marketplace promotions (Shopee, Lazada, TikTok) are not listed or changed here: manage them in each seller center. | Job | Connector tool | API | |---|---|---| | List, find an id, check a code is free | `list_promotions` | `GET /promotions?type=&status=` | | Create | `create_promotion` | `POST /promotions/{type}` | | Change fields | `update_promotion` | `PATCH /promotions/{type}/{id}` | | Pause, resume, end | `set_promotion_status` | `POST /promotions/{type}/{id}/status` | Listing needs `catalog:read`; the other three need `promotions:write`. ## The four types - **`coupon`**: a code the buyer enters. `discount_type` (`percentage` or `fixed`), `value`, `applies_to`; optional `min_order_amount`, `max_discount_amount` (a THB cap on a percentage) and `can_stack` (usable with other promotions). - **`discount`**: the same fields as a coupon, without `can_stack`. Or a rate per product instead: `product_discounts`, each `sku` with its own `discount_type` and `value` (`fixed` = THB off every unit), and no `discount_type`, `value`, `max_discount_amount` or `applies_to` beside it. One discount then holds a whole sale and switches on and off at once. - **`bundle`**: buy these products together for less. `products` (each `sku` and `quantity`: two or more products, or one product in a quantity of 2 or more, like "10 for 100"; every complete set in a cart gets the deal) and `bundle_discount_type` with its value: `fixed_price` with `bundle_price` (what one set costs; the customer saves the set's normal price minus it, never less than 0), `percentage` with `bundle_discount_percentage`, or `fixed` with `bundle_discount` (THB off the set). - **`bogo`**: buy X, get Y. `products` with `role` `buy` or `get`, at least one of each. Or Mix & Match, buy from a list and choose a gift: `choose_gift: true` with `buy` and `get` products. Every `buy_quantity` units bought of the buy list (added up; default 1) earn `get_quantity` gifts (default 1) the customer picks from the get list (the same one as often as they like); a gift they don't pick is the first `get` product with stock. Every type also has `code`, `name`, `starts_at` and `ends_at` (required on create), and optional `description`, `max_uses`, `max_uses_per_customer` and, on create, `status` (`active` by default, or `inactive`). - `code`: letters, digits, `-` and `_`, up to 64 characters; lower case is upper-cased. Unique in the shop. - `applies_to`: `{ "all_products": true }`, or any mix of `categories`, `brands` and `skus`, not both. - A product list (`applies_to.skus` or `product_discounts`) holds up to 5,000 SKUs and goes in **one request**, unlike product and stock rows: an update replaces the saved list, so splitting it keeps only the last part. Read the products first (`find_products` or `GET /products`) and list only SKUs on the store; one unknown SKU refuses the whole list. - Dates are ISO 8601. Send Thai time with its offset, e.g. `2026-11-01T00:00:00+07:00`. `ends_at` must be after `starts_at`. - A percentage can't be more than 100. SKUs must be on your SellerSideKick store. ## Feature a discount in the chat bot A `discount` (either kind) can also take `bot_feature`, to have the shop's chat bot promote it: ```json "bot_feature": { "enabled": true, "announcement_th": "รถเหล็กโทมิก้าทุกรุ่น ลด 15% ถึง 15 พ.ย. นี้เท่านั้น", "announcement_en": "Every Tomica car is 15% off until 15 November." } ``` 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. Leave `announcement_th` empty and the bot uses one built from the promotion's name and end date; - recommends this promotion's in-stock products first when they fit what the customer asks for; - ranks them a little higher among relevant search results. It starts and stops with the promotion's dates by itself: there is nothing to switch off when it ends. - `enabled`: `true` or `false` (default `false`). - `announcement_th`: the Thai message, up to 400 characters, trimmed. `announcement_en`: an optional English version, also up to 400. - Optional on create: left out, the discount is not featured. - On a change, `bot_feature` replaces the whole setting, so send all three keys; a key left out becomes `false` or empty. Leave `bot_feature` out to keep the saved one. To stop featuring it early, send `"enabled": false` with the saved announcements (to keep them) or empty ones. - A bundle takes it too: the bot offers its set first when one of its products fits. So does a BOGO: the bot offers its buy products first, with the free gift. Coupons don't take it (`400`). Every discount, bundle and BOGO reads back with its `bot_feature`. Confirm the announcement text with the owner before sending it: customers see it as written. ## Create `POST /promotions/coupon`: ```json { "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 } ``` Confirm the code, dates, amount and products with the owner first. **Creating is not safe to retry**: if a call fails or times out, list the promotions to see whether it was created before sending it again. A code the shop already uses is refused. ## Change Send only the fields that change, for example `{ "ends_at": "2026-12-15T23:59:59+07:00" }`. To add products to a discount, send the whole new list: the saved one plus the new SKUs (`list_promotions` shows the saved one). The type in the path must match the promotion's type. The change is checked against the promotion as it will be afterwards: the dates stay in order, a percentage stays at 100 or below, a BOGO keeps a buy and a get product, a bundle keeps 2 or more products. A code that another promotion of the shop uses is refused (`409`). ## Pause, resume or end `{ "status": "inactive" }` pauses, `active` resumes, `archive` ends it for good. Nothing is deleted: an archived promotion stays in the history. Confirm with the owner before archiving. --- # Update the chat bot's Playbook, FAQ and greeting > Read and change your chat bot's Playbook, its questions and answers, and the greeting new conversations open with, with a preview first. Your chat bot answers customers on LINE, Facebook, Instagram and web chat. Three things you write shape what it says: - **Playbook:** your own instructions to the bot, such as what to recommend first, how to talk and what to say about delivery. - **FAQ:** questions and answers the bot answers from, such as delivery times, payment and returns. - **Greeting:** what a new conversation on LINE, Facebook or Instagram opens with: your text, then up to 10 videos, pictures or sets of product cards, each with an optional message under it. All three are the same as **Bot settings** in the dashboard. Changing them needs the `bot:write` permission; reading them needs only `catalog:read`. - Connector: `get_bot_playbook_and_faq`, then `preview_playbook_update` / `apply_playbook_update` or `preview_faq_update` / `apply_faq_update`. The greeting can't be changed through the connector yet. - API: `GET /bot`, `POST /bot/playbook`, `POST /bot/faq`, `POST /bot/greeting` and `POST /bot/greeting/media`. ## Read them first `GET /bot` answers the Playbook, the FAQ and the greeting. Read them before a change, so the change keeps what you want kept. ## Playbook The text you send **replaces the whole Playbook**, so start from the saved text and change only what you want different. Up to 20,000 characters; `""` clears it. ```json { "dry_run": true, "playbook": "แนะนำรถเหล็ก Majorette และฟิกเกอร์ Jada ที่มาใหม่ก่อน เมื่อลูกค้าถามหาของขวัญ\nตอบสุภาพ ลงท้ายด้วยค่ะ" } ``` - A dry run answers `updated` or `unchanged` and changes nothing. - Sent for real, the bot reloads with the new Playbook. That takes about 20 seconds, and the answer comes once the bot has it (`reloaded: true`). - If the answer is `502`, the text was saved but the bot didn't reload. Send the same request with `"reload": true`. ## FAQ Each row is a `question` (up to 500 characters) and an `answer` (up to 5,000). Up to 200 questions. ```json { "dry_run": true, "faq": [ { "question": "ส่งของกี่วันถึง", "answer": "ส่งภายใน 1-2 วันทำการ ได้รับใน 2-3 วันค่ะ" }, { "question": "รับชำระเงินช่องทางไหนบ้าง", "answer": "โอนผ่านพร้อมเพย์ หรือจ่ายด้วยบัตรผ่านลิงก์ชำระเงินในแชทค่ะ" } ] } ``` - **Questions are matched** to the saved ones ignoring case and extra spaces. A matched question takes your answer and your wording, and keeps any pictures or videos added in the dashboard. - **`mode: "merge"`** (the default) adds new questions at the end, updates matched ones and keeps every other question. - **`mode: "replace"`** makes the FAQ exactly the questions you send, in your order. The others come back as `removed`. `"faq": []` with `replace` removes every question. - Each row answers `created`, `updated` (with `changed`), `unchanged` or `removed`. - The bot answers from the new FAQ from its next message. Pictures and videos on a FAQ answer are added in the dashboard; the API keeps them but can't add them. ## Greeting The greeting goes, word for word, with the first message of a new conversation on LINE, Facebook or Instagram (and again after 7 quiet days), before the bot's reply. It is never sent on Shopee, Lazada or TikTok. 1. Upload each new video or picture with `POST /bot/greeting/media`: a `multipart/form-data` request with one file in the field `file`, an MP4 of at most 25 MB or a JPEG, PNG or WebP picture of at most 8 MB. A video also needs its preview picture: upload a frame of it the same way. Each answers the file's `url`. 2. Send the greeting with `dry_run: true` and check the answer. 3. Send it again without `dry_run`. ```json { "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" }, { "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 พ.ย. นี้ค่ะ" }, { "type": "products", "products": ["TM-001", "TM-011"] } ] } ``` - **What you leave out stays.** Send only `text` to change the words, or `"enabled": false` to stop sending it (the text and items are kept). - **`text`:** one string for every channel, or `line`, `meta` (Facebook Messenger) and `ig` separately. Up to 1,000 characters each; `""` sends your Welcome message instead. - **`items`:** the whole list, in order, up to 10. It replaces the saved items; `[]` sends the text alone. A set of `products` is 1 to 10 SKUs, shown as one swipeable message of cards with price and an "Interested" button. - **`message`:** sent word for word right after its item, up to 1,000 characters: a product's name and sale price under its picture, for example. `"show_message": false` keeps it without sending it. A picture a customer already got is skipped with its message. - **`description`:** what a video or picture shows. Customers don't see it; the bot reads it to answer a customer who asks about that picture. Write one for each. - **Each video and picture goes to a customer once.** Send the same link again to keep that; a new upload goes once more. Product cards go every time. - **On LINE**, a reply holds 5 messages: the text, each item and each message count one. The rest, and the bot's answer after it, go out as LINE push messages, which count toward your LINE plan. ## Common errors - **`403 Y35`:** the key or connection doesn't have `bot:write`. Create a key with it, or reconnect the assistant and tick it. - **The same question twice** in one request: send each question once. - **More than 200 questions** after a merge: remove some, or send the list to keep with `replace`. - **"upload the image with POST /bot/greeting/media"**: a greeting picture or video must be uploaded there first (or already be in the greeting). - **"a video needs its preview picture"**: upload a frame of the video and send it as `thumbnail_url`. --- # Errors and limits > Every error code with its cause and fix, the per-row errors, rate limits, Retry-After, idempotency keys and the 500-row limit. Every error answers `{ "code": , "message": "…", "rcode": "…" }`. Branch on `rcode` (stable) and show `message` to people. Some errors have no `rcode`; use the HTTP status for those. The connector returns the backend's message and `rcode` inside the tool result, marked as an error. A permission the connection lacks is refused by the connector itself before any call, with a message naming the permission. ## Error codes | HTTP | rcode | Cause | Fix | |---|---|---|---| | 400 | none | The body is invalid. The message names the field, e.g. `"products[0].prize" is not allowed`. Unknown fields are refused by name. | Fix the field and send again. | | 401 | `Y20` | No `Authorization: Bearer` header. | Send `Authorization: Bearer ssk_…`. | | 401 | `Y21` | The key is unknown or revoked. | Ask the owner for a valid key. Don't retry with the same key. | | 401 | `Y22` | The key has expired. | The owner creates a new key in **Settings → API keys**. | | 403 | `Y31` | The shop is not on a monthly plan. | The owner moves the shop to a monthly plan. Retrying won't help. | | 403 | `Y32` | The shop is not active (deactivated or archived). | Tell the owner. Retrying won't help. | | 403 | `Y34` | The person who created the key, or approved the connection, left the shop or can no longer manage API keys. | An owner or admin creates a new key or connects again. | | 403 | `Y35` | The key or connection doesn't have the permission this call needs (`catalog:write`, `stock:write`, `promotions:write` or `bot:write`). | Create a key with that permission, or reconnect and tick it. | | 401 | `Y41` | Connector only: the assistant's sign-in expired or isn't valid. | The assistant signs in again (most do this on their own). | | 401 | `Y42` | Connector only: the owner disconnected the assistant. | The owner connects it again. | | 403 | none | A marketplace promotion: read-only here. | Change it in the marketplace's seller center. | | 404 | none | No promotion with this id and type in this shop. | List promotions to get a valid id. | | 409 | none | On a promotion update: the new code is already used by another promotion of the shop. | Pick another code. | | 429 | `R01` | Too many requests. | Wait the `Retry-After` seconds, then send the same request again. | On creating a promotion, an unknown SKU or a code the shop already uses is a `400` whose message says which. ### Key management in the dashboard | HTTP | rcode | Cause | |---|---|---| | 403 | `Y31` | Creating a key while the shop is not on a monthly plan. | | 409 | `Y33` | The shop already has 10 live keys: revoke one first. | | 404 | `Y30` | Revoking a key this shop doesn't have. | ## Row errors Write calls answer `200` with one result per row, in the order sent, and a `summary` with the count per status plus `total`. A bad row never stops the others. A row with status `error` carries an `error` message. Report every one to the owner. Common row errors: - an unknown category; - a SKU that exists only on a marketplace, not on the SellerSideKick store; - `stock` or `parent_sku` sent for an existing product; - a new product missing `name`, `price`, `category` or `brand`; - a `parent_sku` that is a variant, a marketplace-only product or doesn't exist; - the same SKU twice in one request; - stock: `expected_from` no longer matches on hand, or a `delta` would go below what open orders hold, or a `delta` on a SKU that was never counted. ## Limits | Limit | Value | |---|---| | Rows per write request | 500 (products, stock items). Split bigger sheets. | | SKUs in a promotion's product list | 5,000 (`product_discounts`, `applies_to.skus`), in one request: an update replaces the whole list, so never split it | | Requests per shop | 120 a minute, however many keys or connections | | Requests per caller (IP) | 600 a minute, counted before the key is checked | | Products per page | `limit` up to 500, default 100 | | `idempotency_key` | 8–100 characters: letters, digits, `.` `_` `:` `-` | | Stock `reason` | 200 characters | | Product `name` / `description` | 500 / 10,000 characters per language | | Promotion `code` / `name` / `description` | 64 / 200 / 2,000 characters | | Products in a bundle or BOGO | up to 50 (a bundle needs 2 or more) | | Live API keys per shop | 10 | ## Retrying - **429:** wait the number of seconds in the `Retry-After` header, then resend the same request. - **Product updates** (`POST /products/upsert`): safe to resend; rows already applied come back `unchanged`. - **Stock** (`POST /stock`): safe to resend **with the same `idempotency_key`**; applied rows come back `already_applied`. Use a new key for each new change. - **Promotion create:** not safe. List promotions first to see whether it was created. - **Promotion update and status:** safe to resend. - **401 and 403:** don't retry; tell the owner what the message says. --- # Glossary > The terms used in these docs and the API, each with the Thai word sellers use for it. When a shop owner writes in Thai, these are the words they are likely to use. | Term | Thai | Meaning | |---|---|---| | SKU | รหัสสินค้า (SKU) | The shop's own code for one product or variant. Products are matched by it. | | Product | สินค้า | One item on the SellerSideKick store. | | Variant | ตัวเลือกสินค้า | A size, colour or other option of a main product. Set with `parent_sku`. | | Main product (parent) | สินค้าหลัก | The product a variant belongs to. | | Category | หมวดหมู่ | One of the shop's top-level product groups. | | Brand | แบรนด์ | The product's brand. | | Price | ราคา | The selling price on the SellerSideKick store, in THB (บาท). | | Stock | สต็อก | Units of a product. | | On hand | สต็อกคงเหลือ | Units on the shelf now (`stock.on_hand`). | | Available | พร้อมขาย | On hand minus what open orders hold: what can still be sold (`stock.available`). | | Stock count | นับสต็อก | Setting on hand to a counted number (`value`). | | Adjustment | ปรับสต็อก | Adding or removing units (`delta`). | | Promotion | โปรโมชัน | Any of the shop's offers below. | | Coupon | คูปอง | A code the buyer enters for a discount. | | Discount | ส่วนลด | A price cut on chosen products, by percent or a fixed amount. | | Bundle | เซ็ตสินค้า / ซื้อเป็นชุด | Products bought together for less. | | BOGO | ซื้อ 1 แถม 1 / ซื้อ X แถม Y | Buy these products, get those free. | | Code | โค้ด | A promotion's code, e.g. `WELCOME10`. | | Active / inactive | เปิดใช้งาน / ปิดชั่วคราว | A promotion that is running or paused. | | Archive | เก็บถาวร / ปิดถาวร | Ending a promotion for good. It stays in the history; nothing is deleted. | | Dry run / preview | ทดลองก่อน (ยังไม่บันทึก) | A request that reports what would happen and changes nothing. | | Idempotency key | รหัสกันทำซ้ำ | Your id for one stock change, so a retry is never applied twice. | | Marketplace | มาร์เก็ตเพลส | Shopee, Lazada or TikTok Shop. | | Seller center | Seller Center / ศูนย์ผู้ขาย | Each marketplace's own back office, where its prices and listings are edited. | | Listing | รายการสินค้าบนมาร์เก็ตเพลส | A product's page on a marketplace, linked to the SKU. | | API key | คีย์ API | A secret (`ssk_…`) that lets a program work on one shop. | | Connector | ตัวเชื่อมต่อ (Connector) | The way an AI assistant connects to SellerSideKick, at `https://mcp.sellersidekick.ai/mcp`. | | Permission (scope) | สิทธิ์ | What a key or connection may do: `catalog:read`, `catalog:write`, `stock:write`, `promotions:write`, `bot:write`. | | Revoke | ยกเลิกสิทธิ์ | Switching a key or a connection off for good. | | Monthly plan | แพ็กเกจรายเดือน | A monthly subscription, such as Pro or Pro Plus. Needed for API keys and the connector. | | Coins | เหรียญ | Basic's pay-as-you-go credit. | | Chat bot | แชทบอท | SellerSideKick's AI that answers customers. | | LINE OA | LINE OA (LINE Official Account) | A shop's business account on LINE. | --- # Security > How API keys and assistant connections are stored, limited and revoked, what they can never do, and what reaches the marketplaces. ## API keys - **Shown once.** A key (`ssk_` and 40 characters) is shown only when it is created. We store a one-way hash of it and its first 12 characters, so we can tell keys apart but can never show the key again. Lost a key? Revoke it and create a new one. - **One key, one shop.** The key decides the shop; a request can't name another shop. - **Up to 10 live keys per shop.** Give each tool its own key, so you can revoke one without breaking the others. - **Permissions.** A key can have full access (the default), read only, or chosen permissions: `catalog:read` (always included), `catalog:write`, `stock:write`, `promotions:write`. A call outside them is refused with `Y35`. - **Expiry.** A key can expire after 30, 90 or 365 days, or never. The person who created it gets a reminder email 7 days before. An expired key is refused with `Y22`. - **Revoke at any time** in **Settings → API keys**. It stops working at once; the record is kept for the history. - **Keep it secret.** Only in the `Authorization: Bearer` header. Never in a URL, a shared file, a spreadsheet or a chat message. ## Assistant connections - **You sign in with SellerSideKick**, on our own page, and choose one shop and its permissions. The assistant never sees your password or an API key. - The assistant gets **short-lived tokens** limited to that shop and those permissions. We check the connection on every call. - **Disconnect at any time** in **Settings → API keys → Connected AI assistants**. The next call is refused. - The sign-in page says who is asking: the assistant's name, its web address, and a **Verified** badge only for assistants we know. ## Who can do it - Only a shop owner, or an admin with permission to manage API keys, can create keys or connect an assistant. - Keys and connections act **in the name of the person who created them**. Changes show that person in the history. - **If that person leaves the shop**, or loses the permission to manage API keys, their keys and connections stop working (`Y34`). Someone who still manages keys creates new ones. - Everything works only while the shop is on a **monthly plan** (such as Pro or Pro Plus). On Basic (pay-as-you-go coins), existing keys are kept but refused with `Y31`, and work again when the shop is back on a monthly plan. ## What they can never do - **Delete anything.** Products are created and updated, never deleted. Promotions are archived, never deleted. - **Touch marketplace data.** Only products on your SellerSideKick store and your own SellerSideKick promotions can be changed. A SKU that exists only on a marketplace, and every marketplace promotion, is refused. - **Reach another shop.** - **See customers, chats or orders.** The API and the connector cover the catalogue, stock and promotions only. ## What reaches the marketplaces - **Stock** reaches your linked Shopee, Lazada and TikTok listings, usually within about 10 minutes, exactly as a change in the dashboard does. - **Prices, names, descriptions and promotions** stay on your SellerSideKick store and chat bot. Marketplace prices and listings are edited in each seller center. ## Seeing what changed **Settings → API keys** shows how many calls each key made today and in the last 30 days (calls, errors, rate-limited calls, dry runs, rows written), and a log of every change made through a key or an assistant: when, which key or assistant, the SKU or promotion code, the field, and its value before and after. ## Report a problem Email team@kuztom.ai. If a key may have leaked, revoke it first. --- # Changelog > Changes to the shop API, the AI-assistant connector and these docs, newest first. ## Next release: the chat bot's Playbook, FAQ and greeting - **New permission:** `bot:write`. Keys with full access have it; a key or connection with chosen permissions needs it added (a new key, or reconnect and tick it). - **New:** `GET /v1/api/bot` reads the Playbook and the FAQ; `POST /v1/api/bot/playbook` replaces the Playbook; `POST /v1/api/bot/faq` adds, updates or (with `mode: "replace"`) removes questions. All writes take `dry_run`. See [Update the chat bot's Playbook and FAQ](https://docs.sellersidekick.ai/update-bot). - **Connector:** `get_bot_playbook_and_faq`, `preview_playbook_update` / `apply_playbook_update`, `preview_faq_update` / `apply_faq_update`. - **New:** `POST /v1/api/bot/greeting` changes the greeting new conversations on LINE, Facebook and Instagram open with: the text, then up to 10 videos, pictures or sets of product cards, each with an optional `message` sent right after it. `POST /v1/api/bot/greeting/media` uploads its videos and pictures. `GET /v1/api/bot` answers it as `greeting`. API only for now. See [Update the chat bot's Playbook, FAQ and greeting](https://docs.sellersidekick.ai/update-bot#greeting). ## 2026-10-30: product pictures - **New:** product rows in `POST /v1/api/products/upsert` (and the connector's catalogue tools) take `images`: 1 to 7 picture links, copied onto SellerSideKick. See [Add new products](https://docs.sellersidekick.ai/add-products#pictures). - **New:** `POST /v1/api/images` uploads pictures as files (multipart) and answers their links. - `GET /v1/api/products` answers each product's `images`. ## Next release: feature a discount in the chat bot - **New:** `POST /v1/api/promotions/discount` and `PATCH /v1/api/promotions/discount/{id}` take `bot_feature: { enabled, announcement_th, announcement_en }` (announcements up to 400 characters). While the discount runs, the shop's chat bot on LINE, Facebook, Instagram and web chat opens conversations with the announcement and recommends the discount's products first. Discounts read back with it. See [Promotions](https://docs.sellersidekick.ai/promotions). - **New:** bundles and BOGOs take `bot_feature` too, and read back with it. ## Next release: bigger promotion product lists - **Changed:** a promotion's product list (`product_discounts`, `applies_to.skus`) now takes up to **5,000 SKUs**, up from 500. It is sent whole in one request, because an update replaces the saved list. Product and stock writes stay at 500 rows per request. ## Next release: a discount with a rate per product - **New:** `POST /v1/api/promotions/discount` and `PATCH /v1/api/promotions/discount/{id}` take `product_discounts: [{ sku, discount_type, value }]`, a rate per SKU off every unit of it (up to 500 SKUs at first, 5,000 since), instead of `discount_type`, `value` and `applies_to`. One promotion holds the whole sale, so it switches on and off at once. It reads back the same way it is written. ## Next release: stock read-back and simpler variants - **Fixed:** `GET /v1/api/products` answered `stock: { on_hand: null, available: null }` for every product. It now returns the counted and sellable numbers. - **Variants:** a new variant (`parent_sku`) that gives no `category` or `brand` takes the main product's. Anything the row gives still wins. - **Clearer errors:** a new product missing several required fields is told all of them at once, for example `A new product needs name, price and brand.` ## Permissions, key expiry and the AI-assistant connector - **Connector** at `https://mcp.sellersidekick.ai/mcp` for Claude, ChatGPT, Gemini Enterprise and Gemini CLI. You sign in with SellerSideKick and choose the shop and permissions. See [Connect ChatGPT, Claude or Gemini](https://docs.sellersidekick.ai/connect-ai-assistant). - **Permissions on API keys:** `catalog:read`, `catalog:write`, `stock:write`, `promotions:write`. Existing keys and new keys default to full access. A call outside a key's permissions answers `403 Y35`. - **Key expiry:** never, 30, 90 or 365 days, with a reminder email 7 days before. An expired key answers `401 Y22`. - **Connected AI assistants** are listed in **Settings → API keys**, each with a Disconnect button. **Recent API changes** there shows what keys and assistants changed, before and after. - **Change log** in **Settings → API keys**: every change made through a key or an assistant, with the value before and after. - These docs, `llms.txt` and a Markdown copy of every page. ## 2026-10-25: OpenAPI spec 1.1.0 and usage counters - The OpenAPI spec is published at `https://api.sellersidekick.ai/v1/api/openapi.json`, written for AI agents: when to call each operation, what to check first, whether a retry is safe, with examples. - **Usage counters** per key and per shop in **Settings → API keys**: calls, errors, rate-limited calls, dry runs and rows written, today and over the last 30 days. --- # SellerSideKick Shop API reference > Version 1.6.0. Generated from the OpenAPI spec (https://api.sellersidekick.ai/v1/api/openapi.json). Base URL: https://api.sellersidekick.ai/v1/api. 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 /me` shows both. The permissions are `catalog:read` (always: shop, categories, products, promotions), `catalog:write` (create and update products; an opening `stock` on a new product also needs `stock:write`), `stock:write`, `promotions:write`, `bot:write` (the chat bot's Playbook, FAQ and greeting), and for the loyalty program `loyalty: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), and `leads: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 403 `Y35` naming 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 1. Call `GET /me` to confirm which shop the key is for, and tell the owner the shop name. 2. Read before writing: - `GET /categories` for the allowed category names; - `GET /products?sku=...` for the current prices and stock. 3. Send every write with `dry_run: true` first. Show the owner the summary and every row with status `error`, and wait for a clear yes. 4. Send the same request with `dry_run: false`. Report the summary and every `error` row. ## 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 through `POST /products/upsert`. - Pictures: put links in a product's `images` (each is copied onto SellerSideKick). Pictures the owner has as files go up first through `POST /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/program` first: 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 with `POST /loyalty/program/simulate`, add rewards, and switch it on with `POST /loyalty/program/status` once 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 an `idempotency_key` and a `dry_run`: preview first, get the owner's yes, then send the same request with `dry_run: false`. - To check it works as the owner expects: `POST /loyalty/program/checks` runs a ready-made check for each thing the settings promise and reviews them for mistakes; `POST /loyalty/program/test` replays 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 them `subscriptions:write`. Subscribers are the shop's customers and are not in this API. - `GET /subscriptions/readiness` first: 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}` with `status: "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) and `rules` (cancelling, pausing, late payment, refunds, changing plan: a `mode` the sentence is written from, or the shop's own `text`). 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/events` with `connected_plans:write`: `signed_up`, `paid`, `renewed`, `cancelled`, `payment_failed`. The first `paid` with 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)? Send `email` or `phone` (and `plan_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: true` the 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}` (`kind` is `product` or `plan`) reads the settings with `catalog:read`; `PATCH` changes them with `leads:write`. A change names only what it changes; the rest stays. - The form: up to 30 `fields` (`name`, `description` in plain words the bot reads, `kind`, `options` for a choice, `required`). A field's `key` is made from its name when you leave it out; rules name fields by key. Switching it on needs at least one required field. - `qualify.text` says who fits in plain words (the bot judges it); `qualify.rules` are checks on number or choice fields. `brief` is anything else about how to talk about the item; `promise` is 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 shows `hosts_count` only); it can't be switched on before there is a host. ## Limits and errors - 120 requests a minute per shop. On `429`, wait the `Retry-After` seconds 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. ## Authentication - `shopApiKey`: http (bearer). The shop's API key, `ssk_` + 40 characters, from Settings → API keys. One key acts on one shop. ## Shop Which shop the key belongs to, and its categories. ### GET /me Which shop this key belongs to. Operation id: `getShop`. **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` ```json { "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. Operation id: `listCategories`. **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` ```json { "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. Operation id: `listProducts`. **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: set `limit` (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` ```json { "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). Operation id: `upsertProducts`. **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`, `category` and `brand`, and may set `stock` (the opening count) and `parent_sku` (to make it a variant of a main product, which may be created in the same request). - Each row answers `created`, `updated` (with `changed`), `unchanged` or `error`. **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 /images` first 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** (JSON, 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`) ```json { "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`) ```json { "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`) ```json { "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`) ```json { "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` ```json { "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). Operation id: `uploadImages`. **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` ```json { "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). Operation id: `updateStock`. **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) with `value`. A row whose on-hand moved meanwhile is refused instead of overwritten. - Send `dry_run: true` first 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 `delta` can't take on-hand below what open orders hold. A counted `value` is 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** (JSON, 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`) ```json { "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`) ```json { "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` ```json { "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. Operation id: `listPromotions`. **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` ```json { "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. Operation id: `createPromotion`. **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** (JSON, 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`) ```json { "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`) ```json { "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`) ```json { "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`) ```json { "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`) ```json { "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`) ```json { "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`) ```json { "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` ```json { "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. Operation id: `updatePromotion`. **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** (JSON, 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`) ```json { "ends_at": "2026-12-15T23:59:59+07:00" } ``` *Raise a discount to 15%* (`raise`) ```json { "value": 15 } ``` **Response 200:** The promotion as saved. `ok` ```json { "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). Operation id: `setPromotionStatus`. **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** (JSON, required) | Field | Type | Required | Description | |---|---|---|---| | `status` | "active" \| "inactive" \| "archive" | yes | | **Request examples** `pause` ```json { "status": "inactive" } ``` `end` ```json { "status": "archive" } ``` **Response 200:** The promotion with its new status. `ok` ```json { "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. Operation id: `getBot`. **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. `media` are 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` ```json { "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. Operation id: `updatePlaybook`. **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** (JSON, 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`) ```json { "dry_run": true, "playbook": "แนะนำรถเหล็ก Majorette และฟิกเกอร์ Jada ที่มาใหม่ก่อน เมื่อลูกค้าถามหาของขวัญ\nตอบสุภาพ ลงท้ายด้วยค่ะ\nส่งของภายใน 1-2 วันทำการ" } ``` **Response 200:** `updated` (and `reloaded`: the bot uses it now) or `unchanged`. `ok` ```json { "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). Operation id: `updateFaq`. **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 are `removed`. Read `GET /bot` first 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** (JSON, 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`) ```json { "dry_run": true, "faq": [ { "question": "ส่งของกี่วันถึง", "answer": "ส่งภายใน 1-2 วันทำการ ได้รับใน 2-3 วันค่ะ" }, { "question": "รับชำระเงินช่องทางไหนบ้าง", "answer": "โอนผ่านพร้อมเพย์ หรือจ่ายด้วยบัตรผ่านลิงก์ชำระเงินในแชทค่ะ" } ] } ``` *Make the FAQ exactly these two questions* (`replace`) ```json { "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` ```json { "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). Operation id: `updateGreeting`. **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}` (`meta` is Facebook Messenger, `web` the 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 a `video` (with `thumbnail_url`, its preview picture: LINE shows a video only with one), an `image`, or `products` (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 a `description` of 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: false` keeps 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. Its `text` can't have links, @ids or other channels' names (the marketplace forbids them); `""` sends the shop's Welcome message when that has none. `send_items: true` also 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** (JSON, 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`) ```json { "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`) ```json { "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`) ```json { "dry_run": true, "text": { "meta": "สวัสดีค่ะ ผู้ช่วย AI ของร้านค่ะ แอด LINE ของร้านไว้ สั่งของผ่าน LINE Mini App ได้ด้วยค่ะ" } } ``` *Stop sending it (the text and items are kept)* (`off`) ```json { "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` ```json { "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. Operation id: `uploadGreetingMedia`. **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` ```json { "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. Operation id: `listLoyaltyTemplates`. **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` ```json { "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. Operation id: `getLoyaltyProgram`. **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` ```json { "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` ```json { "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. Operation id: `createLoyaltyProgram`. **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 send `status: "active"`. Switch it on with `POST /loyalty/program/status` once 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** (JSON, 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` ```json { "template_key": "classic_points", "name": "นิชิ พอยท์", "description": "สะสมแต้มทุกการสั่งซื้อทาง LINE และ Facebook" } ``` `stamp_card` ```json { "template_key": "stamp_card", "name": "บัตรสะสมแสตมป์", "status": "draft" } ``` `custom_rate` ```json { "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` ```json { "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. Operation id: `updateLoyaltyProgram`. **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** (JSON, 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` ```json { "name": "นิชิ คลับ", "description": "สะสมแต้ม แลกส่วนลด" } ``` `expiry` ```json { "expiry": { "mode": "end_of_year", "months": 12, "year_offset": 1 } } ``` **Response 200:** The program as saved. `ok` ```json { "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. Operation id: `setLoyaltyProgramStatus`. **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** (JSON, required) | Field | Type | Required | Description | |---|---|---|---| | `status` | "active" \| "paused" \| "archived" | yes | | **Request examples** `switch_on` ```json { "status": "active" } ``` `pause` ```json { "status": "paused" } ``` **Response 200:** The program with its new status. `ok` ```json { "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. Operation id: `simulateLoyalty`. **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** (JSON, 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` ```json { "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` ```json { "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. Operation id: `testLoyaltyProgram`. **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** (JSON, 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` ```json { "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` ```json { "template_key": "stamp_card", "steps": [ { "type": "order", "amount": 150, "repeat": 10, "every_days": 3, "expect": { "rewards_issued": 1, "balance": 0 } } ] } ``` `vip_member` ```json { "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` ```json { "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. Operation id: `checkLoyaltyProgram`. **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** (JSON, 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` ```json {} ``` `preset` ```json { "template_key": "cashback_credit" } ``` `before_saving` ```json { "program": { "expiry": { "mode": "fixed_months", "months": 6, "year_offset": 1 } } } ``` **Response 200:** The settings review and every check's outcome. `ok` ```json { "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. Operation id: `listLoyaltyRewards`. **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` ```json { "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. Operation id: `createLoyaltyReward`. **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** (JSON, 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` ```json { "name": "ส่วนลด 50 บาท", "description": "ใช้กับคำสั่งซื้อขั้นต่ำ 300 บาท", "type": "discount_fixed", "value": 50, "cost_units": 500, "min_order_amount": 300, "voucher_valid_days": 30 } ``` `percent` ```json { "name": "ลด 10%", "type": "discount_percent", "value": 10, "max_discount_amount": 200, "cost_units": 800 } ``` `custom` ```json { "name": "กล่องสุ่มฟรี 1 กล่อง", "type": "custom", "cost_units": 1500, "stock": 20, "max_per_member": 1 } ``` **Response 201:** The new reward. `ok` ```json { "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. Operation id: `updateLoyaltyReward`. **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** (JSON, 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` ```json { "cost_units": 400 } ``` `restock` ```json { "stock": 50 } ``` **Response 200:** The reward as saved. `ok` ```json { "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. Operation id: `setLoyaltyRewardStatus`. **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** (JSON, required) | Field | Type | Required | Description | |---|---|---|---| | `status` | "active" \| "inactive" \| "archived" | yes | | **Request examples** `pause` ```json { "status": "inactive" } ``` `remove` ```json { "status": "archived" } ``` **Response 200:** The reward with its new status. `ok` ```json { "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. Operation id: `listLoyaltyMembers`. **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` ```json { "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. Operation id: `getLoyaltyMember`. **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` ```json { "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. Operation id: `listLoyaltyMemberLedger`. **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` ```json { "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. Operation id: `setLoyaltyMemberStatus`. **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** (JSON, required) | Field | Type | Required | Description | |---|---|---|---| | `status` | "active" \| "suspended" | yes | | | `reason` | string | no | Kept in the API change log. (max length 300) | **Request examples** `suspend` ```json { "status": "suspended", "reason": "ตรวจสอบคำสั่งซื้อที่ผิดปกติ" } ``` `reactivate` ```json { "status": "active" } ``` **Response 200:** The member with their status. `suspended` ```json { "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. Operation id: `adjustLoyaltyMember`. **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`. 1. Send it with `dry_run: true`: the answer shows the balance before and after, and nothing changes. 2. Tell the owner the member (code, name), the change and the reason; wait for a clear yes. 3. 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** (JSON, 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` ```json { "units": 100, "reason": "ของขวัญขอโทษที่ส่งช้า", "idempotency_key": "8c6f2d0e-6a1b-4f3e-9d2a-1b7c5e4f3a21", "dry_run": true } ``` `take_back` ```json { "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` ```json { "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` ```json { "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. Operation id: `redeemLoyaltyReward`. **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`. 1. 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. 2. Tell the owner and wait for a clear yes. 3. 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** (JSON, 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` ```json { "reward_id": "6650f0c2a1b2c3d4e5f60731", "idempotency_key": "f1e2d3c4-b5a6-4978-8a9b-0c1d2e3f4a5b", "dry_run": true } ``` `voucher` ```json { "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` ```json { "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` ```json { "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. Operation id: `listLoyaltyRedemptions`. **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` ```json { "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. Operation id: `updateLoyaltyRedemption`. **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** (JSON, 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` ```json { "action": "fulfill", "note": "รับที่หน้าร้าน" } ``` `undo` ```json { "action": "cancel", "reason": "ลูกค้าเปลี่ยนใจ" } ``` **Response 200:** The redemption with its new status. `cancelled` ```json { "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)? Operation id: `getSubscriptionReadiness`. **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` ```json { "code": 200, "message": "OK", "data": { "ready": true, "stripe_connected": true, "charges_enabled": true, "card": true, "promptpay": true, "requirement": null } } ``` `not_connected` ```json { "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. Operation id: `listSubscriptionPlans`. **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` ```json { "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. Operation id: `createSubscriptionPlan`. **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** (JSON, 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` ```json { "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` ```json { "name": "ชมรมคนรักของเล่น", "gives": "membership", "renewal_modes": [ "link" ], "prices": [ { "label": "รายเดือน", "amount": 199, "interval": "month" }, { "label": "รายปี", "amount": 1990, "interval": "year" } ] } ``` **Response 201:** The new plan. `ok` ```json { "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. Operation id: `getSubscriptionPlan`. **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` ```json { "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. Operation id: `updateSubscriptionPlan`. **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** (JSON, 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` ```json { "status": "on_sale" } ``` `describe` ```json { "description": "Chat bot on LINE, Facebook and Instagram, plus the LINE Mini App. Cancel any time." } ``` `details` ```json { "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` ```json { "rules": { "cancel": { "mode": "any_time" }, "pause": { "mode": "no" }, "refund": { "mode": "none" }, "change": { "mode": "now" } } } ``` **Response 200:** The plan as saved. `ok` ```json { "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). Operation id: `addSubscriptionPlanPrice`. **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** (JSON, 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` ```json { "label": "Yearly", "amount": 26215, "interval": "year" } ``` `with_trial` ```json { "label": "Monthly, 7 days free", "amount": 2621.5, "interval": "month", "trial_days": 7 } ``` **Response 201:** The plan with its new price. `ok` ```json { "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. Operation id: `setSubscriptionPlanPrice`. **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** (JSON, 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` ```json { "active": false } ``` `restart` ```json { "active": true } ``` `vat_included` ```json { "vat": "included" } ``` **Response 200:** The plan as saved. `ok` ```json { "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. Operation id: `reportConnectedPlanEvent`. **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** (JSON, 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` ```json { "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` ```json { "idempotency_key": "evt_88", "event": "signed_up", "plan_code": "pro_monthly", "email": "owner@example.com" } ``` `cancelled` ```json { "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` ```json { "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` ```json { "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. Operation id: `getLeadSettings`. **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` ```json { "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. Operation id: `updateLeadSettings`. **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** (JSON, 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` ```json { "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` ```json { "promise": "Our team will call you today." } ``` `switch_off` ```json { "enabled": false } ``` **Response 200:** Saved: the settings as they are now. `saved` ```json { "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:`, `field_options_missing:`, `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.