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
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:
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:
| Field | Example | Use 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. |
signal | AbortSignal | Pass it to fetch. It aborts after 3 seconds. |
What you return
| Field | Required | Example |
|---|---|---|
reference | yes | "BACKPACK-30-GREEN" |
title | yes | "Trail backpack · 30 L · Green". Name the variant. |
price | yes | { amount: 8990, currency: "EUR" }. Unit price, gross or net like the Channel. |
taxCategory | yes | "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. | |
compareAt | The 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. | |
expiresAt | RFC 3339. Default: 15 minutes from now. | |
components | A 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. | |
appliedCodes | Codes 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
httporhttpsURL. 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.
8990EUR 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.