ORBCART 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 _.
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 #/configuration/engraving/text. |
extension_invalid | setExtension() with a refused value. | errors[] with pointer #/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.
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 →