Carts & checkout

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.

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"Your name. Unique per Channel. Shown in Quotes and Orders.
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.
minimumSubtotal5000Goods 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 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 →

Add your own fields with extensions →

On this page