# Discounts

Codes, automatic promotions, free shipping, batches of single-use codes and redemption limits. Made by your team in the admin.

Your team makes discounts in the admin, under **Orders › Discounts**: what a
discount takes off, for what, under which conditions, and for how long. Pause
one and it stops with the next view and quote; end one and it is over for good.
OrbCart applies them, spreads them over the Lines and shows them in the Cart,
the Quote and the Order.

A discount is data your team owns, not code you deploy. The same operations are
in the Admin API (`/v1/discounts`), so an integration can make them too.

## Start with discounts

Declare discounts on the Channel to start with. OrbCart creates each one the
first time it runs, when no discount of that ID exists. From then on the
discount is your team's: a change in the code never overwrites what they did, and
one they ended stays ended.

```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](/docs/shop/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"`                   | Its name in Quotes and Orders, unique in the whole environment. In the admin it comes from the name your team gives. |
| `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`                        | Value before discounts; shipping counts only shipped Lines matching its reference/tag filters.                       |
| `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.                                                                                        |
| `except`          | `{ tags: ["clearance"] }`     | Offers that never take it and never count toward its minimum.                                                        |
| `locations`       | `{ included: ["hamburg"] }`   | Only orders of these Locations (`included`), or never of these (`excluded`).                                         |
| `combination`     | `"exclusive"`                 | `combinable` (default) stack. Of the `exclusive` ones, only the best applies, alone.                                 |

## Locations and what never counts

A discount can hold only for orders that belong to some Locations, or never for
others: `locations: { included: ["hamburg"] }`. An order belongs to the
Locations it is picked up at, worked on at or booked at; an order shipped from
stock belongs to none, so it is in no `included` Location.

`except` names Offers the discount never takes anything off and that do not count
toward its `minimumSubtotal`, by reference or tag, such as everything tagged
`clearance`.

**A gift card is never discounted.** Mark the offer in your `offers` answer with
`giftCard: true`: no discount takes anything off it, and its price never helps a
cart reach a minimum. [Gift cards →](/docs/shop/gift-cards)

## Batches of single-use codes

Open a discount and generate a batch: a prefix and a number, such as `WERK` and
`500`. OrbCart issues that many codes like `WERK-7QK2-M4XA`, each of which works
once. Export them as CSV and hand them out; the discount lists every order that
redeemed one.

- A code is spent when the order is placed. A quote holds it while the quote is valid, and
  the buyer's order button keeps it until the payment has its outcome, however long the
  provider takes, so two checkouts racing for one code cannot both get it. A payment that
  fails or is cancelled gives the code back.
- **A cancelled or refunded order does not give its code back.** The order was placed, so the
  code is spent. If the buyer should have another try, send them a new code.
- A retried order does not spend a second code.
- A discount can have a code of its own beside its batches, and several batches. A prefix
  belongs to one batch in the whole environment, and a code belongs to one discount of a
  channel: a shared code another live discount uses, or one that starts with a batch's
  prefix, is refused.

## 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 and the buyer's payment keeps it until it ends, so the last redemption cannot go
to two buyers at once. The discount's page
lists every redemption with its order and the time.

`perBuyer` counts [signed-in buyers](/docs/integrate/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 team's discounts.

## End a promotion early

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

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