Recipes

ORBCART DOCUMENTATION

A gift message, end to end

Declare a gift message once, let the buyer write it in the bag, and print it on the packing slip. Checked on the server, kept in the Quote and frozen in the Order.

You add a field OrbCart does not know: a gift message of up to 200 characters. The buyer writes it in the bag, the server checks it against your schema, and your ERP prints it on the packing slip. No table, no endpoint and no migration of your own.

You need a commerce Worker and a React storefront, such as the one from Add to cart. The Extensions page has every rule.

1. Declare it

An extension is a name, where it sits and a schema. on: "cart" puts it on the whole purchase:

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

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

src/worker.ts passes it on as defineCommerce(commerce). A schema OrbCart cannot describe as JSON Schema, such as one with a transform, fails the deployment, not a buyer.

2. Let the buyer write it

The field saves when the buyer leaves it. It goes through the Cart's checkout store, so it waits its turn behind any other change of the Cart:

app/gift-message.tsx
import { CommerceError, describe } from "@orbcart/client";
import type { Cart, CommerceCart } from "@orbcart/client";
import { useState } from "react";

const words = describe("en-GB");

export function GiftMessage({ cart, current }: { cart: CommerceCart; current: Cart }) {
  const saved = current.extensions.giftMessage;
  const [text, setText] = useState(typeof saved === "string" ? saved : "");
  const [problem, setProblem] = useState<string>();

  async function save() {
    setProblem(undefined);
    const checkout = cart.checkout();
    try {
      await (text.trim()
        ? checkout.setExtension("giftMessage", text)
        : checkout.removeExtension("giftMessage"));
    } catch (error) {
      if (!(error instanceof CommerceError)) throw error;
      setProblem(words.problem(error.problem.code));
    }
  }

  return (
    <label className="gift-message">
      Gift message
      <textarea
        value={text}
        maxLength={200}
        onChange={(e) => setText(e.target.value)}
        onBlur={save}
      />
      {problem && <span role="alert">{problem}</span>}
    </label>
  );
}

Render it in the bag below the Lines, with the Cart access and the Cart as read: <GiftMessage cart={cart} current={bag.cart} /> in the Bag of the mini cart. maxLength only helps the buyer; the server's schema decides.

Why in the bag

<Checkout> has no place for fields of your own yet. Ask in the bag, or build the checkout page yourself with useCheckout() or the checkout store, whose setExtension is the same.

3. Print it on the packing slip

The value is in the Quote the buyer agreed to and frozen in the Order. deliverOrder hands it on:

src/erp.ts
import type { DeliverOrderContract } from "@orbcart/runtime";

export const deliverOrder: DeliverOrderContract = async (order, { signal }) => {
  const { giftMessage } = order.quote.extensions;

  const salesOrder = await erp.createSalesOrder(
    {
      externalId: order.id,
      lines: order.quote.lines.map(({ reference, quantity }) => ({ sku: reference, quantity })),
      packingSlipNote: typeof giftMessage === "string" ? giftMessage : undefined,
    },
    { idempotencyKey: order.id, signal },
  );
  return { reference: salesOrder.number };
};

The rest of the hand-off is in Send paid Orders to your ERP. Your backend reads the same value with admin.orders.get(id) as order.quote.extensions.giftMessage.

What the buyer sees

  • The field in the bag, with what they wrote before, on every device that opens the Cart.
  • A message over 200 characters cannot be typed. One sent anyway is refused with extension_invalid, and the field says "Please check the details you added to your order."
  • Their words on the packing slip, exactly as they agreed to them in the Quote.

A gift message is personal data. OrbCart keeps it out of logs and events and shows it only to team members with access to buyer data. AI agents cannot set an extension; a buyer who needs one finishes on your checkout (AI agents).

Variations

On this page