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.

JobConnector toolAPI
List, find an id, check a code is freelist_promotionsGET /promotions?type=&status=
Createcreate_promotionPOST /promotions/{type}
Change fieldsupdate_promotionPATCH /promotions/{type}/{id}
Pause, resume, endset_promotion_statusPOST /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:

"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:

{
  "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.