Add a custom field to Shopify checkout with a checkout UI extension
From the work/ 10 min read
Build a checkout UI extension that adds a field, save the value as a cart metafield that is copied to the order, and see which targets need Shopify Plus.
- Checkout
- Shopify apps
- Shopify Plus
In this article (9)
To add a custom field to Shopify checkout, create a checkout UI extension with the Shopify CLI, draw the field with Shopify's components, and save what the shopper types in a cart metafield that is copied to the order. On the information, shipping and payment steps, this requires Shopify Plus.
Below is the full code for a purchase-reference field, the targets table with the plan each one needs, and the change to make if you save the value with attributes today. We did not run it in a store: we validated the code and the GraphQL mutation with Shopify's own tools.
What a checkout UI extension is
A checkout UI extension is a small program, written with Preact, that Shopify runs inside checkout at a fixed spot called a target. You declare it in a shopify.extension.toml file, draw it with Shopify web components (s-text-field, s-banner, s-checkbox), and read or change checkout through the global shopify object. You do not edit the checkout HTML: you add a piece at a place Shopify already exposes.
A field takes three things: a target to show it in, a component that collects the text, and a place to store the value so it reaches the order. All three are in Shopify's official tutorial and its example repository, which build a delivery-instructions field; here we build a purchase reference and add what the tutorial leaves out.
Scroll the figure sideways to see all of it
Create the extension with the Shopify CLI
The tutorial asks for Shopify CLI 3.85.1 or higher and, inside your app, this command:
shopify app generate extension --template checkout_ui --name po-reference
shopify app generate extensioncreates an extension in the app you are standing in.--template checkout_uipicks the checkout UI template, which tracks the current API version.--name po-referenceis the folder and extension name.
The CLI creates shopify.extension.toml, src/Checkout.jsx, a locales folder and a package.json. Run shopify app dev and press p to open the preview; if you edit the .toml, restart the command.
This is the shopify.extension.toml for our field. The CLI generates the uid and the API version (the documentation lists 2026-10 as the latest on November 12, 2026); keep whatever the CLI writes:
api_version = "2026-10"
[[extensions]]
name = "po-reference"
handle = "po-reference"
type = "ui_extension"
[[extensions.targeting]]
module = "./src/Checkout.jsx"
target = "purchase.checkout.contact.render-after"
[[extensions.targeting.metafields]]
namespace = "my_app"
key = "po_reference"
api_versionpins the version of the APIs the extension receives.[[extensions]]gives the name, thehandle(it cannot change after you deploy) and theui_extensiontype.[[extensions.targeting]]links the file to the target. Here the field renders right after the contact block, on the information step.[[extensions.targeting.metafields]]requests themy_app.po_referencemetafield so the extension can read it. Replacemy_appwith a namespace of your own.
Choose where the field appears in checkout
There are two families of targets. Static targets render in a fixed place, such as after the shipping methods list. Block targets (purchase.checkout.block.render) render wherever the merchant places them. Either way, the extension does not show until the merchant adds the app block in the editor (Settings > Checkout > Customize checkout > Add app block), per the testing guide. The full list is in the targets reference.
Put the field next to the step it belongs to: a purchase reference with contact, delivery instructions with shipping (purchase.checkout.shipping-option-list.render-after). Two warnings from the field UX guide and the tutorial: shipping targets do not render on a checkout with only digital products, and shipping-option-list.render-after renders once per purchase type (one-time and subscription), so the official example returns null unless the group is oneTimePurchase, to avoid writing the metafield twice.
Scroll the figure sideways to see all of it
Build the field with Shopify's components
This is src/Checkout.jsx. We validated it with the validator of Shopify's checkout-extensions skill, on the purchase.checkout.contact.render-after target:
import '@shopify/ui-extensions/preact';
import {render} from 'preact';
import {useState} from 'preact/hooks';
const NAMESPACE = 'my_app';
const KEY = 'po_reference';
export default function extension() {
render(<Extension />, document.body);
}
function Extension() {
const {appMetafields, applyMetafieldChange, instructions, i18n} = shopify;
// The value saved earlier in this checkout, so the field survives a reload.
const saved = appMetafields.value.find(
(entry) =>
entry.target.type === 'cart' &&
entry.metafield.namespace === NAMESPACE &&
entry.metafield.key === KEY,
);
const [value, setValue] = useState(String(saved?.metafield.value ?? ''));
const [failed, setFailed] = useState(false);
// Accelerated checkout (Apple Pay, Google Pay) can turn this off.
if (!instructions.value.metafields.canSetCartMetafields) {
return null;
}
async function save() {
const text = value.trim();
const result = await applyMetafieldChange(
text === ''
? {type: 'removeCartMetafield', namespace: NAMESPACE, key: KEY}
: {
type: 'updateCartMetafield',
metafield: {
namespace: NAMESPACE,
key: KEY,
type: 'single_line_text_field',
value: text,
},
},
);
setFailed(result.type === 'error');
}
function updateValue(event) {
setValue(event.currentTarget.value);
}
return (
<s-text-field
label={i18n.translate('poLabel')}
value={value}
error={failed ? i18n.translate('poError') : undefined}
onInput={updateValue}
onBlur={save}
/>
);
}
- The first three lines bring in Preact and the
s-*components, which are registered globally. NAMESPACEandKEYmust be identical to the.tomland to the order definition.extension()is what Shopify runs; it only mounts the component.- From the
shopifyobject we useappMetafields(read),applyMetafieldChange(write),instructions(what is allowed) andi18n(translated strings). savedlooks up the cart metafield to prefill the field if the shopper comes back to this step.- If
canSetCartMetafieldsis false the extension renders nothing. Shopify warns that with Apple Pay or Google Pay the change can fail. savestores withupdateCartMetafieldor, if the shopper emptied the field, deletes withremoveCartMetafield. It runs ononBlur, not on every keystroke: the performance guide warns that too many changes can rate limit the extension.- If
result.typeiserror, the field shows our own text: the errormessageis not localized and Shopify says not to show it to the shopper. updateValueis a named function because the validator rejected the arrow function inline in the JSX.- The
s-text-fieldgets a label, a value, an error and the two events. The strings live inlocales/en.default.jsonplus one file per language.
Save the value on the order
The value is stored as a cart metafield with applyMetafieldChange. Per the API reference, that metafield is copied to an order metafield when the order is created, as long as an order metafield definition exists with the same namespace and key and the cart to order copyable capability turned on. Without that definition the value stays on the cart and never reaches the order.
Create the definition in the admin, single line text, with Copy values from cart metafields enabled, as the tutorial says. Or use the API with the cartToOrderCopyable capability; we validated this mutation against the Admin GraphQL schema:
mutation {
metafieldDefinitionCreate(
definition: {
name: "PO reference"
namespace: "my_app"
key: "po_reference"
type: "single_line_text_field"
ownerType: ORDER
capabilities: { cartToOrderCopyable: { enabled: true } }
}
) {
createdDefinition { id namespace key }
userErrors { field message code }
}
}
namespaceandkeyrepeat the extension's; if one letter differs, nothing is copied.ownerType: ORDERdefines the metafield on orders, not on carts.capabilitiesturns oncartToOrderCopyable, the one that copies the cart value.- Always read
userErrors: that is where Shopify returns validation failures.
The migration guide adds that the app needs the write_orders scope for the metafields to reach the order; the tutorial does not mention it, so confirm it in your app. Once a test order comes in, the value shows in the Metafields section of its detail page.
If you save the value with applyAttributeChange today, note that the Attributes API reference marks it deprecated and tells you to use cart metafields instead.
Scroll the figure sideways to see all of it
What needs Plus and what does not
Shopify's rule: extensions that render on the information, shipping and payment steps are available only on stores with Shopify Plus. Per the page on technologies for customizing checkout, extensions for Thank you and Order status are available on all plans except Shopify Starter. That "except Starter" corrects the common "all plans".
| Where it renders | Example target | Plan |
|---|---|---|
| Information step | purchase.checkout.contact.render-after | Shopify Plus |
| Shipping step | purchase.checkout.shipping-option-list.render-after | Shopify Plus |
| Payment step | purchase.checkout.payment-method-list.render-after | Shopify Plus |
| Thank you page | purchase.thank-you.block.render | All but Starter; read-only metafields |
The thank-you page does not work for this field: the order already exists and its targets can read metafields but not write them. Without Plus, the place to ask is the theme's cart: an input named attributes[reference] inside the cart form creates an attribute, per the Liquid documentation. Check with a test order where it shows in the admin.
If what you want is to change prices or validate the cart on the server, that is Functions territory: see how to migrate Shopify Scripts to Functions for discounts.
Common mistakes
- Not adding the block in the editor. The deployed extension stays hidden until the merchant adds it in the checkout editor.
- Forgetting the order definition, or changing one letter of the namespace or key. The metafield stays on the cart and the order arrives without the value.
- Still using
applyAttributeChange. It is marked deprecated; use cart metafields. - Saving on every keystroke. Too many changes can rate limit the extension; save when the field loses focus or after a short pause.
- Ignoring Apple Pay and Google Pay. Check
canSetCartMetafieldsand handle theerror; with accelerated checkout the change can fail. - Using a shipping target on a digital cart. It does not render; for a value that applies to every order, use the contact target.
Frequently asked questions
Can I do this without Shopify Plus?
Not inside checkout: information, shipping and payment are Plus only. Thank you and Order status accept extensions on every plan except Starter, but with read-only metafields. Without Plus, ask for the value in the theme's cart with an attribute.
How do I make the field required?
With useBuyerJourneyIntercept from the Buyer Journey API, which can block progress and show an error under a field. It needs the block_progress capability on the extension, and the merchant must allow it in the checkout behavior settings; otherwise canBlockProgress arrives false.
Where do I see what the shopper typed?
On the order's detail page, in the Metafields section, as long as the order definition has the copy from cart turned on. Place a test order after every namespace or key change.
Why a metafield and not an attribute?
Because applyAttributeChange is marked deprecated in the API reference, with the instruction to use cart metafields, and because a metafield has a type and a definition you control in the admin.
Checklist
- The store is on Shopify Plus if the field goes on information, shipping or payment.
- The extension was created with
shopify app generate extension --template checkout_ui. - The target sits on the right step and the extension copes with a digital-only cart.
NAMESPACE,KEYand the.tomlmatch the order definition.- The order definition has copy from cart turned on and the app has
write_orders. - The code checks
canSetCartMetafieldsand saves when the field loses focus. - The merchant added the app block in the checkout editor.
- A test order shows the value under Metafields.
With a cart metafield and its order definition, the field gets where you need it. If the app that hosts the extension also has screens in the admin, read the Polaris 2 release candidate for Shopify apps.
Saw this on Instagram? Comment CAMPO on the Reel and I'll send you the guide.
Written by

Published November 12, 2026 · updated November 18, 2026