Skip to Content
Build a shop

ORBCOMMERCE DOCUMENTATION

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.

OnExampleWhere the value goes
a LineAn engraving, a size configuratorYour offers function, the Quote and the Order.
the CartA gift message, a note for the carrierThe Quote and the Order.

The recipe A gift message, end to end builds one from the declaration to the packing slip.

Declare

Any Standard Schema with JSON Schema support works, such as Zod 4.2 or newer:

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

The checkout draws the control from the schema:

SchemaControl
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 objectA control of your own.
askWhat 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:

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:

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

CodeWhenWhat the problem tells you
configuration_invalidadd() with a value the schema refuses.errors[] with a pointer per field, such as #/body/configuration/engraving/text.
extension_invalidsetExtension() with a refused value.errors[] with pointer #/body/value.
extension_invalidquote() 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

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

Your deliverOrder 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":

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 →

Choose payment providers →

On this page