# Extensions

Your own typed fields on a Line or the Cart. An engraving, a gift message, a configurator's choices.

Need a value OrbCart doesn't know? Declare it once with a schema. OrbCart
validates it, keeps it with the purchase and hands it to your ERP with the Order.

| On       | Example                                | Where the value goes                             |
| -------- | -------------------------------------- | ------------------------------------------------ |
| a Line   | An engraving, a size configurator      | Your `offers` function, the Quote and the Order. |
| the Cart | A gift message, a note for the carrier | The Quote and the Order.                         |

The recipe [A gift message, end to end](/docs/shop/gift-message) builds one from the declaration to the
packing slip.

## Declare

Any [Standard Schema](https://standardschema.dev) with JSON Schema support works,
such as Zod 4.2 or newer:

```ts title="src/commerce.ts"
import { z } from "zod";
import type { CommerceConfig } from "@orbcart/runtime";

export const commerce = {
  channels,
  offers,
  extensions: {
    engraving: { on: "line", schema: z.object({ text: z.string().trim().min(1).max(20) }) },
    giftMessage: { on: "cart", schema: z.string().max(200) },
  },
} satisfies CommerceConfig;
```

```ts title="src/worker.ts"
export default defineCommerce(commerce);
```

Names start with a letter and use only letters, digits and `_`.

## Ask for a value at checkout

Add `ask` to a Cart extension to render a field in the standard React checkout. Set a schema title
for the label. Without `ask`, the extension still works through `setExtension()`, but checkout does
not render it. See [the gift message recipe](/docs/shop/gift-message).

The checkout draws the control from the schema:

| Schema                                                | Control                                                           |
| ----------------------------------------------------- | ----------------------------------------------------------------- |
| Text, such as `z.string().max(40)`                    | A text field; a text area above 100 characters.                   |
| A boolean, such as `z.literal(true)`                  | A checkbox. Unticked is no value, so `required` means tick.       |
| A choice of texts, such as `z.enum(["Frau", "Herr"])` | A select. A literal's `title` is shown in place of it.            |
| Anything else, such as an object                      | [A control of your own](/docs/shop/react-checkout#fields-of-your-own). |

| `ask`        | What it means                                                                            |
| ------------ | ---------------------------------------------------------------------------------------- |
| `"optional"` | The field is shown. Leaving it blank never blocks a purchase.                            |
| `"required"` | The Cart gets no Quote until the extension has a value. The rule holds for every client. |

A required extension without a value is in the Cart's `missing` as `extensions.<name>`, and a Quote
asked for anyway is refused as `cart_incomplete`. Two things follow from the rule living on the
server:

- A wallet's sheet, such as Apple Pay or Google Pay, cannot ask your question, so those express
  buttons are offered only once it is answered. An express checkout with a review page, such as
  PayPal, asks it there.
- An agent over UCP cannot answer it either and hands the checkout over to the buyer.

For a custom checkout, the Cart lists what it asks in `askedExtensions`, by extension name, each
with its JSON Schema, and in `fields` as `extensions.<name>` with `required` or `optional`. Only
asked extensions are listed. Use the usual extension setter and remover; OrbCart owns validation.

## Set values from the storefront

Pass your configuration's type to `createCommerce`. Every value is then typed by
its schema:

```ts browser
import type { commerce as config } from "../commerce/src/commerce";

const commerce = createCommerce<typeof config>({ url, key });
const cart = await commerce.cart();

await cart.add("BOTTLE-750", { configuration: { engraving: { text: "Anna 2026" } } });
await cart.setExtension("giftMessage", "Happy birthday!");
await cart.removeExtension("giftMessage");
```

The same reference with a different configuration becomes its own Line. Two
bottles engraved differently are two Lines.

## Charge for a configuration

A Line's values arrive in your `offers` function as `line.configuration`. When the
price depends on it, echo the configuration back with the price:

```ts
export const offers: OffersContract = async (lines, { currency }) =>
  lines.map((line) => {
    const engraved = line.configuration.engraving !== undefined;

    return {
      reference: line.reference,
      configuration: line.configuration,
      title: engraved ? "Bottle 750 ml · engraved" : "Bottle 750 ml",
      price: { amount: engraved ? 2990 : 2490, currency },
      taxCategory: "standard",
      ...(engraved && { withdrawal: { excluded: "personalized" } }),
    };
  });
```

An answer without `configuration` applies to every Line of that reference. Cart
extensions never change an amount by themselves.

## When a value is refused

| Code                    | When                                     | What the problem tells you                                                            |
| ----------------------- | ---------------------------------------- | ------------------------------------------------------------------------------------- |
| `configuration_invalid` | `add()` with a value the schema refuses. | `errors[]` with a `pointer` per field, such as `#/body/configuration/engraving/text`. |
| `extension_invalid`     | `setExtension()` with a refused value.   | `errors[]` with pointer `#/body/value`.                                               |
| `extension_invalid`     | `quote()` after you changed a schema.    | `invalid` names the extensions to fix or remove.                                      |

Map `errors[].pointer` to your form fields to show the message where it belongs.

## Read them in the Order

```ts
order.quote.lines[0].configuration; // { engraving: { text: "Anna 2026" } }
order.quote.extensions; // { giftMessage: "Happy birthday!" }
```

Your [`deliverOrder`](/docs/integrate/inventory#hand-orders-to-your-erp) receives the
same Order.

## Name them for your team

The admin shows a Line's configuration beside the Order, each value under the `title` of its
JSON Schema, in your team's language. A field without one reads as its name, so `firstRegistration`
shows as "First registration":

```ts
import { z } from "zod";

const Car = z
  .object({ firstRegistration: z.string().meta({ title: "Erstzulassung" }) })
  .meta({ title: "Fahrzeug" });
// The admin shows "Fahrzeug › Erstzulassung".
```

## Generate a client that knows them

`GET /v1/openapi.json` on your environment describes the API with your declarations: the
`LineConfiguration` and `CartExtensions` schemas name each extension with its JSON Schema, and every
cart extension has the path of its own, such as `PUT /v1/carts/{cart}/extensions/giftMessage`. A
client generated from it knows the fields of your shop.

The description is public, like the endpoint: write the schemas, their enums and descriptions as
something a storefront may read, and keep internal codes out of them. In it, a field with a
default counts as optional, though your environment always sends it.

## Limits

- Each value is at most **16 KiB** as JSON. Enough for a configurator's choices.
- Values are personal data. They never appear in logs, and members without access to buyer data see them redacted.
- AI agents cannot set extensions. If a Cart extension needs a new value, the agent hands the checkout to the buyer. [AI agents →](/docs/shop/agents)

[Choose payment providers →](/docs/shop/payments)