# 促销与定价规则

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

> Markdown version of https://kanorio.com/zh-CN/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-CN/help/promotions