# Discounts

Codes, automatic promotions, free shipping and redemption limits. Declared, not coded.

Declare discounts on the Channel. OrbCart applies them, spreads them over the
Lines and shows them in the Cart, the Quote and the Order.

```ts title="src/worker.ts" members="ChannelConfig"
discounts: [
  { id: "welcome", code: "WELCOME10", percentage: 10 },
],
```

The buyer enters the code:

```ts browser
await cart.enterCode("welcome10"); // any spelling
await cart.removeCode("WELCOME10");
```

## Common recipes

A complete walk-through, from the declaration to a test: [Free shipping and a welcome code](/recipes/free-shipping-and-codes).

```ts alternatives value="Discount"
// €5 off orders from €40
{ id: "five-off", code: "FIVE", amount: 500, minimumSubtotal: 4000 }

// Free standard shipping from €50, no code needed; express stays paid
{ id: "free-shipping", scope: "shipping", percentage: 100, minimumSubtotal: 5000, methods: ["standard"] }

// 20 % off every unit tagged "outdoor", for one weekend
{
  id: "weekend",
  scope: "line",
  percentage: 20,
  tags: ["outdoor"],
  from: "2026-10-09T22:00:00Z",
  until: "2026-10-11T22:00:00Z",
}

// The first 500 buyers, once each
{ id: "launch", code: "LAUNCH", percentage: 15, limit: { total: 500, perBuyer: 1 } }

// Never combined with anything else
{ id: "vip", code: "VIP30", percentage: 30, combination: "exclusive" }
```

## Options

| Option            | Example                       | What it does                                                                                      |
| ----------------- | ----------------------------- | ------------------------------------------------------------------------------------------------- |
| `id`              | `"welcome"`                   | Your name. Unique per Channel. Shown in Quotes and Orders.                                        |
| `percentage`      | `10`                          | Percent off. Use this **or** `amount`.                                                            |
| `amount`          | `500`                         | Fixed amount off, in minor units.                                                                 |
| `code`            | `"WELCOME10"`                 | Applies only when entered. Without it, applies automatically.                                     |
| `scope`           | `"order"`                     | `order` (default): the goods. `line`: each unit of matching Lines. `shipping`: the shipping cost. |
| `references`      | `["BACKPACK-30-GREEN"]`       | Only these Offers.                                                                                |
| `tags`            | `["outdoor"]`                 | Only Offers with these tags.                                                                      |
| `minimumSubtotal` | `5000`                        | Goods value before discounts the Cart must reach.                                                 |
| `methods`         | `["standard"]`                | Shipping discounts only: these shipping rule IDs, in every country. Without it, every method.     |
| `from`, `until`   | `"2026-10-09T22:00:00Z"`      | Active from `from` until just before `until`. RFC 3339.                                           |
| `limit`           | `{ total: 500, perBuyer: 1 }` | How often it can be redeemed.                                                                     |
| `combination`     | `"exclusive"`                 | `combinable` (default) stack. Of the `exclusive` ones, only the best applies, alone.              |

## What the buyer sees

* **A code that applies nowhere** is refused with `code_invalid` and not kept.
* **A kept code that stops qualifying,** for example when the Cart drops below the minimum, appears in `cart.changes` as `code_invalid`. It applies again once the Cart qualifies.
* **A free-shipping code while express is chosen** stays in the Cart. `cart.changes` says `code_invalid` with `reason: "shipping_method"` and `methods: ["standard"]`, so you can tell the buyer to pick standard. The React kit says it for you. A code for a method the Cart cannot get at all is refused.
* **Applied discounts** are listed once each in `estimate.discounts` and `quote.discounts`, with the amount they took off.

## Redemption limits

A redemption counts when the Order is placed. A Quote reserves one while it is
valid, so the last redemption cannot go to two buyers at once.

`perBuyer` counts [signed-in buyers](/integrations/identity) by their identity and
guests by their email address.

## Codes from your own pricing

Already run promotions in your ERP? Your `offers` function receives every entered
code. Redeem the ones you know and report them:

```ts
export const offers: OffersContract = async (lines, { codes, currency }) => {
  const prices = await erp.prices(lines, { codes, currency });

  return prices.map((price) => ({
    reference: price.sku,
    title: price.name,
    price: { amount: price.amount, currency },
    taxCategory: "standard",
    appliedCodes: price.redeemedCodes, // such as ["VIP20"]
  }));
};
```

OrbCart checks a code against `offers` first. Only a code that `offers` does not
redeem is checked against your declared `discounts`.

## End a promotion early

Tag the affected Offers and invalidate the tag. [How →](/integrations#end-a-sale-early)

[Add your own fields with extensions →](/commerce/extensions)