Skip to content

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)
  1. What a checkout UI extension is
  2. Create the extension with the Shopify CLI
  3. Choose where the field appears in checkout
  4. Build the field with Shopify's components
  5. Save the value on the order
  6. What needs Plus and what does not
  7. Common mistakes
  8. Frequently asked questions
  9. Checklist

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.

where the field can go: three checkout stepsinformationPO referenceextra fieldcontact.render-aftershippingPO referenceextra fieldshipping-option-listpaymentPO referenceextra fieldpayment-method-listall three checkout steps: Shopify Plus onlyThank you and Order status: every plan but Starter, read-only metafieldsthe field lives on a checkout steptargets per Shopify's documentation, API 2026-10

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
  1. shopify app generate extension creates an extension in the app you are standing in.
  2. --template checkout_ui picks the checkout UI template, which tracks the current API version.
  3. --name po-reference is 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"
  1. api_version pins the version of the APIs the extension receives.
  2. [[extensions]] gives the name, the handle (it cannot change after you deploy) and the ui_extension type.
  3. [[extensions.targeting]] links the file to the target. Here the field renders right after the contact block, on the information step.
  4. [[extensions.targeting.metafields]] requests the my_app.po_reference metafield so the extension can read it. Replace my_app with 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.

checkout targets and the plan each one needstargetstepplanpurchase.checkout.contact.render-afterinformationPluspurchase.checkout.shipping-option-list.render-aftershippingPluspurchase.checkout.payment-method-list.render-afterpaymentPluspurchase.checkout.block.renderin the editorPluspurchase.thank-you.block.renderThank youall but Starteron Thank you the metafield is read-only: the field cannot be saved thereinformation, shipping, payment: Shopify Plus onlysource: shopify.dev, checkout targets and technologies, API 2026-10

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}
    />
  );
}
  1. The first three lines bring in Preact and the s-* components, which are registered globally.
  2. NAMESPACE and KEY must be identical to the .toml and to the order definition.
  3. extension() is what Shopify runs; it only mounts the component.
  4. From the shopify object we use appMetafields (read), applyMetafieldChange (write), instructions (what is allowed) and i18n (translated strings).
  5. saved looks up the cart metafield to prefill the field if the shopper comes back to this step.
  6. If canSetCartMetafields is false the extension renders nothing. Shopify warns that with Apple Pay or Google Pay the change can fail.
  7. save stores with updateCartMetafield or, if the shopper emptied the field, deletes with removeCartMetafield. It runs on onBlur, not on every keystroke: the performance guide warns that too many changes can rate limit the extension.
  8. If result.type is error, the field shows our own text: the error message is not localized and Shopify says not to show it to the shopper.
  9. updateValue is a named function because the validator rejected the arrow function inline in the JSX.
  10. The s-text-field gets a label, a value, an error and the two events. The strings live in locales/en.default.json plus 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 }
  }
}
  1. namespace and key repeat the extension's; if one letter differs, nothing is copied.
  2. ownerType: ORDER defines the metafield on orders, not on carts.
  3. capabilities turns on cartToOrderCopyable, the one that copies the cart value.
  4. 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.

the extension's files and the value's pathshopify.extension.tomltarget and requested metafieldsrc/Checkout.jsxthe field and applyMetafieldChangelocales/en.default.jsonthe field's stringspath of the values-text-fieldthe shopper typesapplyMetafieldChangecart metafieldmy_app.po_referencecart_to_order_copyableorder metafieldmy_app.po_referenceon order creationwithout the order definition, the value stays on the cartthe value reaches the order only with the definitionorder metafield definition with copy from the cart

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 rendersExample targetPlan
Information steppurchase.checkout.contact.render-afterShopify Plus
Shipping steppurchase.checkout.shipping-option-list.render-afterShopify Plus
Payment steppurchase.checkout.payment-method-list.render-afterShopify Plus
Thank you pagepurchase.thank-you.block.renderAll 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 canSetCartMetafields and handle the error; 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, KEY and the .toml match the order definition.
  • The order definition has copy from cart turned on and the app has write_orders.
  • The code checks canSetCartMetafields and 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

Luis Morales

Luis Morales

Frontend and Shopify developer, EcomLabs

@luismoralesdev on Instagram

Published November 12, 2026 · updated November 18, 2026

← Blog