折扣碼與分潤
折扣碼是一條規則：結帳時若通過驗證，就在訂單應收裡記下一筆負額明細，把客人要付的錢往下調。折扣不是訂單上某個彙總欄位，而是金流模型裡和商品同層的一筆 charge line。
理解這點，你才能正確解讀折扣——它和加價、房升補款一樣，都是 訂單金流 裡的 chargeLines 之一，只是金額為負。本篇說明怎麼設定折扣碼、結帳時怎麼試算與套用、折扣如何反映在訂單，以及 KOL 分潤的概念。
折扣碼物件
一張折扣碼（discount code）由三件事組成：折抵規則（折多少）、適用限制（誰、什麼時候、哪些商品能用）、以及選用的分潤設定（推薦人能拿多少）。建立後用 GET /discount-codes 列表、GET /discount-codes/{id} 取單一明細（含適用 trip 與兌換紀錄）。
| 欄位（回傳） | 意義 |
|---|---|
code / label | 結帳輸入碼（不分大小寫須唯一）／後台辨識名稱 |
discountType / discountValue | fixed（定額 TWD）或 percentage（1–100 百分比） |
isActive | 是否啟用；停用後前台無法套用 |
validFrom / validUntil | 生效起迄日（留空為不限） |
maxRedemptions / redemptionCount | 總兌換上限／已兌換次數 |
maxRedemptionsPerCustomer | 每位客戶兌換上限 |
minOrderTwd | 最低應收門檻 |
appliesToAll / tripIds | 全站適用，或限定的行程清單 |
allowedPriceChannels / allowedCustomerTypes | 限定的價格通路／客戶分類 |
stackable | 是否可與其他折扣併用 |
profitShareType / profitShareValue / profitSharePayee | 分潤方式／數值／對象（見下） |
設定折扣碼
建立用 POST /discount-codes，至少帶 code、label、discountType、discountValue。其餘欄位都是用來收窄「什麼情況下這碼有效」：
- 折抵方式：
fixed把discountValue當作折抵的台幣金額；percentage把它當作百分比（1–100）套在折扣前應收上。 - 使用限制：用
maxRedemptions限總量、maxRedemptionsPerCustomer限單客、validFrom/validUntil限期間、minOrderTwd設低消門檻。 - 適用範圍：
appliesToAll為全站碼；或設tripIds把它綁定特定行程。 - 併用政策：
stackable決定能否和別張折扣一起用。
更新用 PATCH /discount-codes/{id}（送出完整欄位），單純啟停用 set-active。
改規則不回寫已成交的訂單。每筆兌換在成交當下就凍結了一份快照（折多少、依什麼規則、分潤給誰），所以你事後調整折扣碼，不會動到歷史訂單的金額或分潤。
結帳前試算
在真正套用前，先用 GET /discount-codes/preview 做唯讀試算——它跑和正式結帳同一套驗證與計算，但不消耗兌換名額。帶上 code、kind、total，以及視情況的 tripId / priceChannel / customerType / userId。
回傳是一個結果信封，讓你能依機器可讀的理由分支：
成功： { ok: true, discountTwd, newTotalTwd, profitShareTwd }
失敗： { ok: false, reason } // 例如過期 / 額滿 / 未達門檻 / 通路不符
試算成功不保證結帳一定成功。名額是在結帳那一刻 race-safe 地鎖定的——兩個人同時用最後一個名額，只有一個會成功。把 preview 當成 UI 的即時提示，不要當成保留。
折扣怎麼反映在訂單
折扣在結帳時和商品同一筆交易寫入：商品先記正向應收明細，折扣再記一筆負額 charge line。於是訂單的應收自然往下調，你不需要自己算總額。
- 折扣明細是
order.chargeLines裡金額為負的一筆，和加價、房升補款並列——所以在GET /orders/{id}看到的grossReceivableTwd已經是折後應收。 - 折扣不會把應收壓到負數：折抵金額會被 floor 到讓應收最低為 0。
- 收款計畫（訂金 / 尾款）會跟著最新應收重算，你拿到的
outstandingTwd就是折後尚欠。
不要在自己的 UI 重算折後金額——一律讀訂單回傳的 grossReceivableTwd / outstandingTwd。折扣的真相在訂單的應收明細，不在折扣碼本身。
KOL 分潤
折扣碼可同時當作推薦分潤的載體：當一張碼設了 profitShareType / profitShareValue / profitSharePayee，每次兌換就會在成交快照裡凍結一筆 profitShareTwd 與受款對象。這讓「給客人的折扣」和「給推薦人的分潤」能各自記帳。
用 GET /discount-codes/{id}/redemptions 取兌換 / 分潤報表：
| 欄位 | 意義 |
|---|---|
redemptions[] | 每筆兌換：orderNumber、originalTotalTwd、discountTwd、profitShareTwd、orderStatus |
totalDiscountTwd | 此碼累計折抵 |
totalProfitShareTwd | 此碼累計分潤 |
totalPaidTwd | 對應訂單累計已收現金 |
分潤的「應付」和「實付」是兩回事。報表給你應分潤的金額，但實際出款走 cairn 的 payouts 流程（對推薦人 / 合作方付款），不是客戶退款。兩者不要混用——退客人錢看 訂單退款，付分潤看 payouts。
下一步
- 訂單與金流模型：應收明細、現金、三軸狀態的全貌——折扣是其中的一筆負額。
- 付款流程：折後應收怎麼向客人收款。
- discount-codes API · CLI discount-codes。