Connect your systems

ORBCART DOCUMENTATION

Offers

The one function OrbCart needs from you. Your systems know the goods; offers tells OrbCart.

OrbCart has no product database. Whenever it needs a price, it asks your offers function. You pass Lines in, you get Offers back. No catalog import, no sync.

The smallest offers function

src/offers.ts
import type { OffersContract } from "@orbcart/runtime";

export const offers: OffersContract = async (lines, { currency }) =>
  lines.map((line) => ({
    reference: line.reference,
    title: "Trail backpack · 30 L · Green",
    price: { amount: 8990, currency },
    taxCategory: "standard",
    shipping: { weightInGrams: 950 },
  }));

Pass it to defineCommerce({ channels, offers }). Done.

Connect your real systems

Ask your systems once per call, for all Lines together. Never one request per Line:

src/offers.ts
export const offers: OffersContract = async (lines, { currency, signal }) => {
  const references = [...new Set(lines.map((line) => line.reference))];
  const products = await erp.products(references, { currency, signal });

  return products.map((product) => ({
    reference: product.sku,
    title: product.name,
    price: { amount: product.priceInCents, currency },
    taxCategory: product.vatClass,
    shipping: { weightInGrams: product.weight },
  }));
};

A reference you do not return is unavailable. The buyer sees it as such and cannot buy it.

What OrbCart passes in

Each Line has a reference, a quantity and its configuration (the values of your line extensions). The second argument tells you the context:

FieldExampleUse it for
currency"EUR"The price list to read.
channel"de"Market-specific assortments.
country"AT"Country prices, once an address is known.
buyer{ issuer, subject }Customer-group prices for signed-in buyers.
codes["VIP20"]Codes your own pricing redeems. Discounts →
purpose"display" / "quote"quote is the binding calculation before payment.
cartId"cart_01J..."Cart-scoped pricing or logging.
signalAbortSignalPass it to fetch. It aborts after 3 seconds.

What you return

FieldRequiredExample
referenceyes"BACKPACK-30-GREEN"
titleyes"Trail backpack · 30 L · Green". Name the variant.
priceyes{ amount: 8990, currency: "EUR" }. Unit price, gross or net like the Channel.
taxCategoryyes"standard", "reduced"
shipping{ weightInGrams: 950, restrictions: ["lithium_battery"] }. Leave it out for digital goods.
image"https://cdn.example.com/backpack-400.webp". A picture of at most 400 px, see below.
deliveryTime"Ships in 3 weeks", when the goods take longer than shipping says. See below.
compareAtThe price before a sale, for display.
promotion"−20 % Summer sale", for display.
tags["summer-sale"], to invalidate later.
limits{ min: 1, max: 5 } units per Line.
expiresAtRFC 3339. Default: 15 minutes from now.
componentsA bundle's parts, so one part can be refunded alone.
withdrawal{ excluded: "personalized" } for goods without a right of withdrawal.
attributes{ color: "green" }, kept in the Order.
appliedCodesCodes your pricing redeemed for this Offer.

Send a small picture

image is the URL of a picture of the goods. It is optional, and it is the one place a merchant sets it: the Explorer shows it beside every line of a cart and an order, and storefronts read it as line.offer.image.

  • At most 400 px on the longer side. OrbCart never scales a picture and shows it at up to 200 px, so 400 px covers high-density screens and a larger file only costs bandwidth. A WebP of 5-15 KB is typical.
  • An absolute http or https URL. Anything else is ignored: a broken picture never stops a sale.
  • Keep the file where it is. The Quote and the Order keep the URL, not the file, so old orders show the picture for as long as it is served.
{ reference: "BACKPACK-30-GREEN", /* … */ image: "https://cdn.example.com/backpack-400.webp" }

Say when goods take longer

deliveryTime is your text for goods that take longer than the shipping method says, such as an engraving or a backorder. The buyer sees it on the Line before ordering, apart from the method's own time, and the Quote freezes it. Write a phrase that stands alone, such as "Ships in 3 weeks": OrbCart shows it as is and never calculates a date. Leave it out when the shipping method's time holds.

// An engraved bottle takes three weeks
{ reference: "BOTTLE-750", /* … */ deliveryTime: "Ships in 3 weeks" }

If the time changes before the buyer orders, the Quote reports line_delivery_time_changed and asks again.

Say why something is unavailable

Return a reason instead of leaving the reference out. The buyer sees it in cart.changes:

{ reference: "TENT-2P", unavailable: "discontinued" }

Rules that keep buyers safe

  • Return unit prices. OrbCart applies quantity, discounts and tax.
  • Use integer minor units. 8990 EUR is €89.90.
  • Fail honestly. If your ERP is down, let the error throw. Returning [] would tell buyers everything is sold out.
  • Never invent a fallback price. An unknown reference is unavailable, not free.

When is offers called?

When the Cart's Lines change (purpose: "display"), and again for the binding Quote (purpose: "quote"). Offers from a quote call are reused for the next Quote while they are valid, 15 minutes by default. That keeps a wallet sheet fast when the buyer only changes the address.

End a sale early

Tag the Offers of a promotion. When it ends, invalidate the tag from your backend:

await admin.offers.invalidate({ tags: ["summer-sale"] });

Open Carts ask offers again. A buyer in checkout sees the new price as a quote_changed. Placed Orders keep their price.

Full example

examples/nordgrat/src/offers.ts reads prices from one service and product facts from an ERP, handles sale prices and splits a bundle into parts. The recipe Prices and stock from your ERP builds offers and inventory over HTTP, with parsed answers and a reservation.

Check stock and hand off Orders →

On this page