Carts & checkout

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.

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

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

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