# 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:<key>`, `field_options_missing:<key>`, `meeting_needs_a_host`).
- **401** (Y20, Y21, Y22): No key, or the key is unknown, revoked or expired. Ask the shop owner for a valid key (Settings → API keys). Do not retry with the same key.
- **403** (Y31, Y32, Y34, Y35): The key is real but can't be used now. Tell the owner why; retrying won't help.
- **404**: No product or plan with this id in this shop.
- **429** (R01): Too many requests: 120 a minute per shop. Wait the number of seconds in the Retry-After header, then send the same request again.
