ORBCART DOCUMENTATION
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.
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
| 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_invalidand not kept. - A kept code that stops qualifying, for example when the Cart drops below the minimum, appears in
cart.changesascode_invalid. It applies again once the Cart qualifies. - A free-shipping code while express is chosen stays in the Cart.
cart.changessayscode_invalidwithreason: "shipping_method"andmethods: ["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.discountsandquote.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 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 declared discounts.
End a promotion early
Tag the affected Offers and invalidate the tag. How →