Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

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.

src/worker.ts
discounts: [
  { id: "welcome", code: "WELCOME10", percentage: 10 },
],

The buyer enters the code:

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.

// €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

OptionExampleWhat 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.
percentage10Percent off. Use this or amount.
amount500Fixed 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.
minimumSubtotal5000Value 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 →

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 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:

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 →

Add your own fields with extensions →

On this page