ORBCOMMERCE 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" }. The price of one, gross or net like the Channel. |
taxCategory | yes | "standard", "reduced", see tax categories |
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. | |
url | "https://shop.example.com/products/backpack-30". The page a Line links back to. | |
deliveryTime | "Ships in 3 weeks", when the goods take longer than shipping says. See below. | |
compareAt | The price before a sale, for display. | |
unitPrice | { price: { amount: 1990, currency: "EUR" }, per: "kg" }, the price per kilogram. See below. | |
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. | |
supply | { type: "b2c_work_on_movable_goods", location }. See below. | |
giftCard | true for a voucher for later purchases: no discount takes anything off it, and each unit sold issues a card. Gift cards → | |
singlePurpose | With giftCard: true when the voucher can be spent on one rate of VAT only, so VAT falls on its sale. Gift cards → | |
attributes | { Colour: "Green" }, flat text under the Line's title, kept in the Order. See below. | |
appliedCodes | Codes your pricing redeemed for this Offer. |
Send the unit price beside the price
Goods sold by weight, volume, length or area show their price per kilogram, litre, metre or square metre
beside the price, as EU and German price indication rules ask. Send it as unitPrice, from the same source
and moment as price, so a sale moves both: per is one of kg, 100g, l, 100ml, m and m2.
OrbCart never derives one. It carries yours on the Line as line.offer.unitPrice, and the Quote freezes it
beside the price it belongs to. Leave it out for goods sold by the piece.
Charge a refundable deposit separately
Send deposit: { price: { amount: 750, currency: "EUR" }, taxCategory: "zero" }
for a refundable security charged per unit. Its currency and gross/net basis follow the Channel,
but its tax category is explicit: use the category appropriate to the deposit, not automatically
the merchandise's. A zero-rate example is not tax advice.
price, compareAt and unitPrice exclude the deposit. Display the deposit beside the merchandise
price, never folded into it or into the unit price (German PAngV §7).
The core multiplies it by quantity, never discounts it, taxes it separately and includes it once
in the payable total. A deposit does not increase discount thresholds or the value used to allocate shipping tax.
Quotes and estimates expose line.deposit pricing separately from merchandise line.totals.
Their aggregate totals.deposit is the deposit before any net-price tax is added;
totals.subtotal remains merchandise only. totals.total already includes deposits and all tax:
do not add the deposit again. Invoice-style payment providers receive a separate deposit line.
Whole-unit refunds include only the deposit still outstanding. A bundle-component refund never
refunds a deposit implicitly. To return just the security while the buyer keeps the merchandise,
use the deposit refund target.
OrbCatalog accepts the same deposit on OfferUpsert, carries it on delivered offers and product-card
offers, and passes it to OrbCart. A Source's next upsert without it removes it.
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 admin 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" }Link back to the goods
url is the goods' page in your storefront, read as line.offer.url, so a Line leads the buyer
back to what they chose. Like image, anything but an absolute http or https URL is ignored.
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.
Name what sets a Line apart
attributes are flat text, a name and a value each, such as { Colour: "Green", "Frame size": "M" }.
The buyer reads them as written under the Line's title, in the bag, the checkout's summary and the
order page, so name them in the channel's language; an empty value is left out. The Order keeps them,
and staff read them in the admin as rows under the Line's title, each name in words: frameSize
reads Frame size.
A Line's configuration is whatever JSON your line extensions take, and staff read
it as nested facts beside the attributes: eight at first, the rest one click away. An object or list of up
to three values stands open; a larger or deeper one waits folded under a one-line preview, its name or
title where it has one. A list of plain values reads as one, true as Yes, a time in the reader's own
zone, and null or an empty value is left out. Five levels down a value shows as …, and one click copies
its raw JSON. Keep the variant in attributes and what the buyer chose in configuration.
Mark work done at your Location
supply marks a stand-alone valuation of or work on a consumer's own goods, physically performed at one
of your Locations, such as a ski service in your workshop. OrbCart then taxes the Line where that Location
is. Take the Location's id, name and address from your catalog's public /v1/locations, and leave shipping out. It is
for nothing else: see work performed at your Location.
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 the price of one. 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.
Goods the catalog keeps
When OrbCatalog keeps your goods, its signed offers are the answer for them: price, tags, sale window,
expiry, shipping restrictions and limits come from the catalog, and your offers function never
rebuilds them. A product's public read shows each variant's shipping and limits too
(Read the catalog), but that is a description for
pages and for refusing a shipping method a good cannot go by, never an offer: it carries no price and
gives no right to answer for a catalog SKU.
Add merchant-priced services
Attach offers: { catalog, merchant: { references, offers } } when your code prices references
the catalog does not know, such as a workshop fitting. The catalog is asked for every Line over
its signed call. Your function receives only the references you configured, and its answer counts
only after the catalog explicitly answers unknown for the whole reference.
If the catalog offers a reference you configured, neither price is used: the Line cannot be bought
(answer_invalid) until you resolve the conflict. Out of stock, not offered, a missing answer or
a malformed answer never transfers authority to your function. Either side failing refuses the
Quote as provider_unavailable; the buyer can retry.
Publishing catalog goods invalidates their SKUs as well as their product tag, so cached merchant
prices cannot hide a new catalog claim. Merchant offers in this composition last at most the
default offer lifetime (15 minutes), even if your function sends a later expiresAt; shorter
windows still hold. This lifetime also bounds a missed invalidation. Placed Orders keep their
agreed price, expiry and signed Quote document.
Shipping discounts count only eligible shipped Lines towards minimumSubtotal, never services
or downloads. Their references and tags filters also limit which shipped Lines count.
Configuration and mixed-cart walk →
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
apps/nordgrat-cart-worker/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.