ORBCOMMERCE DOCUMENTATION
A gift message, end to end
Declare a gift message once, let the buyer write it in checkout, and print it on the packing slip. Checked on the server, kept in the Quote and frozen in the Order.
Add an optional gift message to checkout. If the buyer writes one, the server checks it against your schema and your ERP can print it on the packing slip. Buyers can leave it blank.
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",
ask: "optional",
schema: z.string().trim().min(1).max(200).meta({ title: "Gift message" }),
},
},
} 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. Show your checkout
The standard React checkout shows the field automatically. No React prop or
custom component is needed. The schema's title is the label. Omit ask if your shop should not show
the field in checkout.
The checkout saves edits with the other details. Clearing a saved message removes it. If the schema refuses what the buyer wrote, the checkout marks the field so they can edit or clear it.
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.
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.