> ## Documentation Index
> Fetch the complete documentation index at: https://www.twicecommerce.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Discount Codes
> Redeemable codes that apply a percentage or fixed discount to eligible items at checkout or on an existing order.
A discount code is a merchant-defined string that a customer enters at checkout (or an operator applies to an order) to reduce the price of eligible items. Codes are case-insensitive — `SUMMER20` and `summer20` resolve to the same code.
**Discount codes vs Price Tables:** Price Tables define the base price for a listing. Discount codes reduce the total *after* the base price is calculated. Use Price Tables for rate cards and seasonal pricing; use discount codes for targeted promotions, limited-time offers, or customer-specific incentives.
## How it works
### Discount types
Every code has a **value type** that determines how the discount is calculated.
| Value type | Behaviour | Example |
| ------------------- | ------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| **Percentage** | Reduces each eligible item's subtotal by a percentage (0–100 %). | `SUMMER20` → 20 % off eligible items |
| **Fixed per order** | Subtracts a flat amount from the order, spread proportionally across eligible items by their subtotals. | `SAVE10` → €10 off the order total |
| **Fixed per item** | Subtracts a flat amount from each eligible item independently. | `5OFF` → €5 off every eligible item |
For fixed types, the discount on any single item never exceeds that item's subtotal — no item goes below zero.
When a fixed-per-order discount is spread across items, the allocation uses largest-remainder rounding so the per-item amounts sum exactly to the total discount.
### Restrictions
A code can be restricted to specific items. Leave a restriction empty to apply the code to everything.
| Restriction | Effect |
| ------------------ | ---------------------------------------------------------------------------------- |
| **Purchase types** | Limit the code to bookings, sales, subscriptions, or any combination. |
| **Listings** | Limit the code to specific listings. Items from other listings are not discounted. |
| **Collections** | Limit the code to items that belong to specific collections. |
When both listing and collection restrictions are set, an item must match at least one of the specified listings *or* belong to at least one of the specified collections.
### Validity windows
Two independent date windows control when a code can be used.
| Window | Controls |
| --------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------- |
| **Valid from / Valid to** | When the code itself is redeemable. Outside this window the code is rejected. Dates are evaluated in the tenant's timezone. |
| **Item start date from / Item start date to** | Which item start dates the code applies to. A booking starting outside this window is not eligible, even if the code is otherwise valid. |
Both windows are optional. A code with no validity window is redeemable at any time.
### Usage limits
Set a **usage limit** to cap how many times a code can be used across all customers. Each order that carries the code counts as one use. Deleting an order releases its use automatically.
Codes with no usage limit can be used an unlimited number of times.
Usage is enforced with row-level locking to prevent race conditions on high-demand codes.
### Enabled / disabled
A code has an **enabled** toggle. Disabled codes are rejected at checkout and cannot be applied to orders. Disable a code to stop it from being used without deleting it.
### Access control
Every code has an **access** setting that controls who can apply it.
| Access | Behaviour |
| -------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Public** (default) | Anyone with the code can redeem it — customers at checkout, staff in the admin, and integrations. |
| **Internal** | Only staff and integrations can apply the code. Customers who enter an internal code at checkout see a generic "Invalid discount code" message — the storefront does not reveal that the code exists but is restricted. |
Use internal codes for staff-applied promotions, partner discounts, or integration-driven pricing adjustments that customers should not self-serve.
In the discount codes table, internal codes are marked with a **Staff only** chip next to the code string.
## At checkout
The checkout order summary includes a discount code input. The customer enters a code and the storefront validates it against the current cart items.
* On success, the discount is applied and the updated totals are shown. The code appears as a badge in the order summary with the discount amount and a remove button.
* On failure, a generic "Invalid discount code" message is shown. The storefront does not reveal the specific reason (expired, usage limit reached, etc.) to prevent code enumeration.
A checkout carries at most **one** discount code at a time. Entering a new code replaces any previously applied code.
Discount code endpoints on the storefront are rate-limited to prevent brute-force enumeration.
### Checkout links
Discount codes can also be applied on checkout links — checkouts backed by an existing order. The code input appears when both conditions are met:
* The linked order has **no existing discount codes**.
* All eligible items on the order are **fully unpaid**.
If the order already carries a discount code, the existing codes appear as locked chips in the order summary and no new code can be entered. Partially paid orders and instalment links do not support discount codes.
Subscription line items are not eligible for checkout link discounts — only booking and sale items are discounted.
## On orders
Once an order is created, the applied discount code is stored with its per-item allocations. The code string is snapshotted at application time — renaming or deleting the code later does not affect existing orders.
Operators can manage discount codes on an order from the **Discounts** drawer on the order detail page:
* **Add a code** — search for and validate a code against the order's line items. The drawer previews the discount amount before you confirm.
* **Remove a code** — remove a previously applied code to restore original pricing.
* **Multiple codes** — unlike checkout (one code only), operators can apply multiple codes to a single order from the admin.
The discount allocation is visible on each line item's pricing breakdown.
## Related
Base pricing that discount codes reduce.
Codes can be restricted to specific listings.
Codes can be restricted to specific collections.
Where discount codes are captured and stored.