# Promotions

> Create coupons, discounts, bundles and buy-X-get-Y offers, change them, pause them or end them by archiving.

These are the shop's own SellerSideKick promotions. They apply on the SellerSideKick store and in the chat bot. Marketplace promotions (Shopee, Lazada, TikTok) are not listed or changed here: manage them in each seller center.

| Job | Connector tool | API |
|---|---|---|
| List, find an id, check a code is free | `list_promotions` | `GET /promotions?type=&status=` |
| Create | `create_promotion` | `POST /promotions/{type}` |
| Change fields | `update_promotion` | `PATCH /promotions/{type}/{id}` |
| Pause, resume, end | `set_promotion_status` | `POST /promotions/{type}/{id}/status` |

Listing needs `catalog:read`; the other three need `promotions:write`.

## The four types

- **`coupon`**: a code the buyer enters. `discount_type` (`percentage` or `fixed`), `value`, `applies_to`; optional `min_order_amount`, `max_discount_amount` (a THB cap on a percentage) and `can_stack` (usable with other promotions).
- **`discount`**: the same fields as a coupon, without `can_stack`. Or a rate per product instead: `product_discounts`, each `sku` with its own `discount_type` and `value` (`fixed` = THB off every unit), and no `discount_type`, `value`, `max_discount_amount` or `applies_to` beside it. One discount then holds a whole sale and switches on and off at once.
- **`bundle`**: buy these products together for less. `products` (each `sku` and `quantity`: two or more products, or one product in a quantity of 2 or more, like "10 for 100"; every complete set in a cart gets the deal) and `bundle_discount_type` with its value: `fixed_price` with `bundle_price` (what one set costs; the customer saves the set's normal price minus it, never less than 0), `percentage` with `bundle_discount_percentage`, or `fixed` with `bundle_discount` (THB off the set).
- **`bogo`**: buy X, get Y. `products` with `role` `buy` or `get`, at least one of each. Or Mix & Match, buy from a list and choose a gift: `choose_gift: true` with `buy` and `get` products. Every `buy_quantity` units bought of the buy list (added up; default 1) earn `get_quantity` gifts (default 1) the customer picks from the get list (the same one as often as they like); a gift they don't pick is the first `get` product with stock.

Every type also has `code`, `name`, `starts_at` and `ends_at` (required on create), and optional `description`, `max_uses`, `max_uses_per_customer` and, on create, `status` (`active` by default, or `inactive`).

- `code`: letters, digits, `-` and `_`, up to 64 characters; lower case is upper-cased. Unique in the shop.
- `applies_to`: `{ "all_products": true }`, or any mix of `categories`, `brands` and `skus`, not both.
- A product list (`applies_to.skus` or `product_discounts`) holds up to 5,000 SKUs and goes in **one request**, unlike product and stock rows: an update replaces the saved list, so splitting it keeps only the last part. Read the products first (`find_products` or `GET /products`) and list only SKUs on the store; one unknown SKU refuses the whole list.
- Dates are ISO 8601. Send Thai time with its offset, e.g. `2026-11-01T00:00:00+07:00`. `ends_at` must be after `starts_at`.
- A percentage can't be more than 100. SKUs must be on your SellerSideKick store.

## Feature a discount in the chat bot

A `discount` (either kind) can also take `bot_feature`, to have the shop's chat bot promote it:

```json
"bot_feature": {
  "enabled": true,
  "announcement_th": "รถเหล็กโทมิก้าทุกรุ่น ลด 15% ถึง 15 พ.ย. นี้เท่านั้น",
  "announcement_en": "Every Tomica car is 15% off until 15 November."
}
```

While the promotion is active and inside its dates, the chat bot on LINE, Facebook, Instagram and web chat (never on Shopee, Lazada or TikTok Shop):

- opens a conversation with the announcement. Leave `announcement_th` empty and the bot uses one built from the promotion's name and end date;
- recommends this promotion's in-stock products first when they fit what the customer asks for;
- ranks them a little higher among relevant search results.

It starts and stops with the promotion's dates by itself: there is nothing to switch off when it ends.

- `enabled`: `true` or `false` (default `false`).
- `announcement_th`: the Thai message, up to 400 characters, trimmed. `announcement_en`: an optional English version, also up to 400.
- Optional on create: left out, the discount is not featured.
- On a change, `bot_feature` replaces the whole setting, so send all three keys; a key left out becomes `false` or empty. Leave `bot_feature` out to keep the saved one. To stop featuring it early, send `"enabled": false` with the saved announcements (to keep them) or empty ones.
- A bundle takes it too: the bot offers its set first when one of its products fits. So does a BOGO: the bot offers its buy products first, with the free gift. Coupons don't take it (`400`).

Every discount, bundle and BOGO reads back with its `bot_feature`. Confirm the announcement text with the owner before sending it: customers see it as written.

## Create

`POST /promotions/coupon`:

```json
{
  "code": "WELCOME10",
  "name": "ส่วนลด 10% สำหรับลูกค้าใหม่",
  "discount_type": "percentage",
  "value": 10,
  "max_discount_amount": 100,
  "applies_to": { "all_products": true },
  "starts_at": "2026-11-01T00:00:00+07:00",
  "ends_at": "2026-11-30T23:59:59+07:00",
  "max_uses_per_customer": 1
}
```

Confirm the code, dates, amount and products with the owner first. **Creating is not safe to retry**: if a call fails or times out, list the promotions to see whether it was created before sending it again. A code the shop already uses is refused.

## Change

Send only the fields that change, for example `{ "ends_at": "2026-12-15T23:59:59+07:00" }`. To add products to a discount, send the whole new list: the saved one plus the new SKUs (`list_promotions` shows the saved one). The type in the path must match the promotion's type. The change is checked against the promotion as it will be afterwards: the dates stay in order, a percentage stays at 100 or below, a BOGO keeps a buy and a get product, a bundle keeps 2 or more products. A code that another promotion of the shop uses is refused (`409`).

## Pause, resume or end

`{ "status": "inactive" }` pauses, `active` resumes, `archive` ends it for good. Nothing is deleted: an archived promotion stays in the history. Confirm with the owner before archiving.
