Skip to content

Shopify Dude Fix

Shopify Checkout Metafield Disappeared After 2026-04? Move It to Cart and Copy It to Order

Checkout UI extensions can no longer use old checkout metafields on API 2026-04. Migrate to cart metafields, enable cartToOrderCopyable, and test the order data.

Quick answer: Shopify removed the old checkout-metafield read/write model from checkout and customer account UI extensions in API 2026-04. For checkout input, write a cart metafield using updateCartMetafield or removeCartMetafield. If the value must appear on the resulting order, create an order metafield definition with the same namespace and key and enable its cartToOrderCopyable capability. Customer account extensions should read the appropriate order metafields, not rely on the removed checkout metafield surface.
On this page

Why an old extension can lose its data

Older Checkout UI extension examples used useMetafield(), shopify.metafields, and change types such as updateMetafield. Those APIs belonged to an older model where checkout-scoped data could be collected and later read from the order. As of API version 2026-04, Shopify removed that checkout metafield behavior and moved the buyer-journey data model to cart metafields.

It is easy to update the extension’s api_version, adopt newer Polaris components, and overlook the storage contract. The UI can still render a checkbox or gift message, while the order no longer contains the value expected by fulfillment or customer service. A successful render is not a data migration.

Shopify announced the deprecation on April 27, 2026. Its February 4, 2026 cart-to-order copying capability supplies the new persistence path. These are related changes, but the copy is not automatic for every cart metafield.

Decide which resource owns the data

Ask when the value is needed. During checkout, the cart owns the buyer’s current selection. After order creation, the order owns the completed transaction’s data. In a customer account UI extension that displays past-order details, read the order metafield. Do not treat a customer account extension as a place to mutate the old checkout state.

Examples include a gift-requested flag, a delivery preference, or a custom order reference. Avoid storing sensitive personal information merely because a metafield is convenient. Choose appropriate access permissions and app-reserved namespaces when needed.

Change checkout writes to cart metafields

Shopify’s upgrade guide uses the shopify global in current Checkout UI extensions. The following is a focused example for a boolean buyer choice:

async function saveGiftChoice(isChecked) {
  const change = isChecked
    ? {
        type: 'updateCartMetafield',
        metafield: {
          namespace: 'custom',
          key: 'gift_requested',
          value: 'true',
          type: 'boolean'
        }
      }
    : {
        type: 'removeCartMetafield',
        namespace: 'custom',
        key: 'gift_requested'
      };

  const result = await shopify.applyMetafieldChange(change);
  // Inspect the result and current metafield state in your UI.
  return result;
}

Read the cart value through shopify.appMetafields after declaring the metafield in your extension configuration. Do not keep the deprecated useMetafield() hook or the old updateMetafield change type in an extension upgraded to 2026-04. Also check whether the cart instructions permit setting metafields; accelerated checkout methods can restrict changes.

For apps migrating from versions earlier than 2025-10, the upgrade also involves Polaris web components and Preact. Treat the UI migration and the metafield migration as separate checks rather than assuming one solves the other.

Make the value persist to the order

A cart metafield and an order metafield are different resources. The order copy requires both a matching order metafield definition and an enabled cartToOrderCopyable capability on that definition. Match the namespace and key exactly. Shopify’s upgrade guide also notes that the app needs the appropriate write_orders scope for this setup.

For example, if checkout writes custom.gift_requested on the cart, define custom.gift_requested on orders and enable the copy capability. At order creation, Shopify can copy the cart value to the matching order metafield. If the order definition is absent, the namespace differs, or the capability is off, don’t expect the data to appear on the order.

This is preferable to creating a separate order-edit webhook solely to transfer a basic buyer choice. It is also safer than using cart attributes for all custom data, because metafields support type validation and access controls. However, do not replace line-item properties blindly: item-specific personalization can still belong on the line item rather than the entire cart.

Update downstream integrations and customer account views

Fulfillment apps, notification templates, reporting jobs, and customer account extensions may be reading the old field. Inventory every consumer before release. Update GraphQL selections to read the order metafield from the correct resource, and verify that order edits, refunds, and repeat purchases do not make a stale cart-level value look like a new selection.

Also distinguish this migration from the separate owner_type requirement in extension metafield declarations. That newer declaration rule controls which resource’s metafields Shopify fetches; it does not replace cart-to-order copying. See the owner_type deployment guide for that separate problem.

Common misunderstanding: “If the checkout extension successfully writes a cart metafield, Shopify will automatically put it on the order.” Only when an order metafield definition has the matching namespace and key and cartToOrderCopyable enabled. A cart write and an order copy are separate contracts.

How to test this

  1. Identify every old useMetafield, shopify.metafields, and updateMetafield call in the extension.
  2. Replace checkout writes with cart metafield changes and verify the value updates when the buyer toggles the control.
  3. Remove the value and verify the cart no longer exposes a stale selection.
  4. Create the matching order metafield definition and enable cartToOrderCopyable; verify permissions and app scopes.
  5. Complete an approved test checkout and read the resulting order’s metafield through Admin GraphQL.
  6. Disable the copy capability in a safe test and confirm the order no longer receives the value; restore it before release.
  7. Test a customer account view, fulfillment integration, and an accelerated checkout path, noting any restrictions on cart writes.