# 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](/docs/shop/add-to-cart). The [Extensions](/docs/shop/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:

```ts title="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](/docs/shop/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:

```ts title="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](/docs/integrate/erp-order-handoff). 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](/docs/shop/agents#good-to-know)).

## Variations

- **An engraving with a surcharge** is a Line extension: `on: "line"`, and `offers` prices the Line
  by its `configuration`. [Charge for a configuration](/docs/shop/extensions#charge-for-a-configuration).
- **Typed values in the storefront:** `createCommerce<typeof commerce>()` types `setExtension` by your
  schema. [Set values from the storefront](/docs/shop/extensions#set-values-from-the-storefront).