# 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](/recipes/add-to-cart). The [Extensions](/commerce/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", 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:

```tsx title="app/gift-message.tsx" browser
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.

<Callout title="Why in the bag">
  [`<Checkout>`](/sdks/react) 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](/recipes/checkout-without-react),
  whose `setExtension` is the same.
</Callout>

## 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](/recipes/erp-order-handoff). 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](/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](/commerce/extensions#charge-for-a-configuration).
* **Typed values in the storefront:** `createCommerce<typeof commerce>()` types `setExtension` by your
  schema. [Set values from the storefront](/commerce/extensions#set-values-from-the-storefront).