# Promotions & Pricing Rules

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

> Markdown version of https://kanorio.com/en/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

Status: **Available**

Promotions change what a customer pays at checkout: automatic discounts that apply when conditions are met, and codes the customer enters. Promotions point at what they discount; products do not own promotions.

## How the APIs fit

- Manage promotions with the Management API: `promotions.list`, `promotions.get`, `promotions.create`, `promotions.update` (PATCH), `promotions.archive`, `promotions.unarchive` and `promotions.delete`. The same rules as the dashboard apply, and `promotions.create` accepts an `Idempotency-Key`.
- Target lines with a selector instead of a product list: `kinds` (PRODUCT, BOOKING, CUSTOM), `refs` (a product with an optional variant, a booking resource, or your own SKU for custom lines), `categoryIds` and `priceRange`. `marketIds` limits a promotion to some markets. Bookings and custom lines can be in scope, including for minimum-order discounts.
- Kanorio evaluates promotions during hosted checkout, so your front end does not calculate discounts itself. A headless storefront can read promotions to show badges, but the discount is only applied on Kanorio's checkout page.
- Subscribe to `promotions.redeemed` and `promotions.redemption_revoked` to learn when a paid order used a promotion and when a full refund gave the usage back; `ec.order.paid` carries `promotionId` and `promotionCode`.

The support table below shows what the APIs expose.

## 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/en/help/promotions