Skip to Content
Build a shop

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:

src/commerce.ts
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:

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.

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