# 促銷與定價規則

> Automatic discounts and discount codes that Kanorio applies at checkout.

> Markdown version of https://kanorio.com/zh-Hant/developers/products/promotions. Append `.md` to any developer docs URL for this format. Index: https://kanorio.com/llms.txt · MCP: https://app.kanorio.com/api/mcp
>
> Translated from the English original: https://kanorio.com/en/developers/products/promotions.md

Status: **Available**

促銷活動會改變顧客在結帳時的支付金額：包含滿足條件時自動套用的折扣，以及顧客輸入的優惠代碼。促銷活動指向其折扣的對象；商品本身並不擁有促銷活動。

## API 的運作方式

- 使用 Management API 管理促銷活動：`promotions.list`、`promotions.get`、`promotions.create`、`promotions.update`（PATCH）、`promotions.archive`、`promotions.unarchive` 與 `promotions.delete`。規則與後台相同，`promotions.create` 支援 `Idempotency-Key`。
- 以選擇器而非商品清單指定適用品項：`kinds`（PRODUCT、BOOKING、CUSTOM）、`refs`（商品與可選的方案、預約資源，或自訂品項的 SKU）、`categoryIds` 與 `priceRange`。`marketIds` 可將促銷限定在部分市場。預約與自訂品項也能納入範圍，包含滿額折抵。
- Kanorio 會在託管結帳過程中評估促銷活動，因此您的前端無需自行計算折扣。Headless 前端可讀取促銷活動來顯示標籤，但折扣只會在 Kanorio 的結帳頁套用。
- 訂閱 `promotions.redeemed` 與 `promotions.redemption_revoked`，即可得知已付款訂單使用了促銷、以及全額退款歸還了使用次數；`ec.order.paid` 會帶 `promotionId` 與 `promotionCode`。

下方的支援表格顯示了 API 所公開的功能。

## What the APIs expose

| Capability | Status | API | Elements | Hosted site | Webhooks |
| --- | --- | --- | --- | --- | --- |
| Promotions & discount codes | Available | Management API `promotions.*` (list, get, create, update, archive, unarchive, delete; applied automatically at hosted checkout) | — | `/marketing/promotions`, `/data/promotions` | `promotions.redeemed`, `promotions.redemption_revoked`; `ec.order.paid` carries `promotionId` / `promotionCode` |

## API reference

- Management API: [Promotions](https://kanorio.com/en/developers/management-api/promotions) (7 operations)

## Webhook events

- `promotions.redeemed`: Fired when a paid order redeems a promotion (automatic discount or discount code). Carries the promotion, the order and how the discount was split across lines; never the buyer email.
- `promotions.redemption_revoked`: Fired when a full refund revokes a redemption (the promotion usage count is given back). Partial refunds do not revoke.

Payloads: https://kanorio.com/en/developers/webhooks/events

## Recent changes

- 2026-11-03: Promotions: create and manage promotions through the API; selector-based targeting

Full changelog: https://kanorio.com/en/developers/changelog

## For site owners

Dashboard help: https://kanorio.com/zh-Hant/help/promotions