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:
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:
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:
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
- An engraving with a surcharge is a Line extension:
on: "line", andoffersprices the Line by itsconfiguration. Charge for a configuration. - Typed values in the storefront:
createCommerce<typeof commerce>()typessetExtensionby your schema. Set values from the storefront.
Free shipping and a welcome code
Free standard shipping from €50 without a code, 10 % off with WELCOME10, a code field in the bag, and a test that proves both.
Test a purchase
A Vitest test that buys a backpack against your real Worker, pays with a card through a fake Stripe, reads the Order back and proves a double click buys once.