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