# 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](/commerce/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](/integrations/identity). |
| `codes`    | `["VIP20"]`             | Codes your own pricing redeems. [Discounts →](/commerce/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](#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.                      |
| `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 `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" }
```

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

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

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

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

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