# 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

```ts title="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:

```ts title="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](/docs/shop/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](/docs/integrate/identity). |
| `codes`    | `["VIP20"]`             | Codes your own pricing redeems. [Discounts →](/docs/shop/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](/docs/integrate/tax#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](#end-a-sale-early) 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 →](/docs/shop/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 →](/docs/shop/gift-cards#sell-a-gift-card) |
| `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](https://www.gesetze-im-internet.de/pangv_2022/__7.html)).
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](/docs/integrate/orders-and-refunds#refund-a-deposit).

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 `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.

```ts value="Partial<OfferedReference>"
{ 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.

```ts value="Partial<OfferedReference>"
// 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](/docs/shop/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](/docs/integrate/tax#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`:

```ts value="UnavailableReference"
{ 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.** `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.

## 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](/docs/shop/catalog#shipping-restrictions-and-limits)), 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 →](/docs/shop/extend#answer-them-from-another-system)

## 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:

```ts
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](/docs/integrate/erp-prices-and-stock) builds `offers` and `inventory`
over HTTP, with parsed answers and a reservation.

[Check stock and hand off Orders →](/docs/integrate/inventory)