Action RequiredAPI 2026-04

Checkout metafields removed
Migrate to cart metafields / order metafields

In API version 2026-04, reading and writing checkout metafields from checkout / customer account UI extensions has been "removed." Extensions on older versions must be upgraded to 2026-04 and migrated.

On this page
  1. What changed (in 30 seconds)
  2. Migration map diagram: from where, to where
  3. Two migration targets (cart / order metafields)
  4. New capability: automatic cart → order copy
  5. Action Required: what to do (3 steps)
  6. 5 key points for developers
  7. 3 practical business use cases
  8. One-line summary for proposals

1What changed

API version 2026-04 as ofthe ability to read and write checkout metafields from checkout / customer account UI extensions has been removed.
Instead,Checkout UI extensions use cart metafields,Customer Account UI extensions use order metafields .

What was removed

in checkout / customer account UI extensions checkout metafields reading and writing. Not available in 2026-04.

Migration target for Checkout UI extensions

cart metafields Replace with this. Use this for retaining data during checkout.

Migration target for Customer Account UI extensions

order metafields Replace with this. Use this for referencing data on post-purchase / account pages.

This is not a deprecation notice — it is "removed". If you upgrade to 2026-04 on an old version as-is, anything depending on checkout metafields will break, so complete the migration before upgrading.

2Migration map diagram: from where, to where

~ Older API versions Checkout UI extensions Customer Account UI extensions checkout metafields checkout metafields Migrate Migrate API 2026-04 and later Checkout UI extensions cart metafields Customer Account UI extensions order metafields Auto-copy on order creation Copy cart metafields values to order metafields
The key point is thatthe migration target differs by extension type. The checkout side uses cart, and the post-order account side uses order. In addition, values stored on the cart can be automatically carried over to the order at order creation (see next section).

3Two migration targets (cart / order metafields)

Itemcart metafieldsorder metafields
Extension used Checkout UI extensions Customer Account UI extensions
Primary role Holding and reading/writing data during checkout Reading/writing data tied to the order
Relationship to legacy checkout metafields Replacement in Checkout UI extensions Replacement in Customer Account UI extensions
Official migration guide "Migrate to cart metafields in checkout UI extensions" "Migrate to order metafields in customer account UI extensions"
The concrete API schemas and code diffs for each metafield arenot documentedin the changelog body itself. Refer to the two official migration guides above.

4New capability: auto-copy from cart to order

Order metafield definitions gained anew capability: At order creation, cart metafields values can be automatically copied to order metafields. This simplifies data management that spans cart and order.

(1) Hold the value on the cart

A Checkout UI extension writes to cart metafields.

(2) Auto-copy at order creation

Based on the order metafield definition settings, the value is automatically copied to the order side.

(3) Reference on the order

Customer Account UI extensions and order data can treat it as an order metafield.

This makes the common pattern of "using information collected at checkout on post-order screens" possiblewithout writing manual data hand-off code. The copy is triggered atorder creation.

5Action Required: what to do (3 steps)

1

Inventory dependencies

Identify all places in checkout / customer account UI extensions that read or write checkout metafields.

2

Replace per the migration guide

Rewrite Checkout UI extensions to use cart metafields, and Customer Account UI extensions to use order metafields.

3
2026-04

Upgrade to API 2026-04

After migrating, upgrade the extensions to 2026-04. This is mandatory if you are still on an older version.

Order matters: "Migrate → Upgrade"checkout metafields have already been removed in 2026-04, so if you only bump the version without migrating, the affected features will break.

65 key points for engineers

removed

1. It's "removed," not "deprecated"

Reading and writing checkout metafields was already removed in 2026-04. Putting it off in hopes of a grace period is not an option. Complete the migration before upgrading the version.

2. The migration target depends on the extension type

Checkout UI → cart metafields; Customer Account UI → order metafields. Note that the replacement for "checkout metafields" splits into two paths depending on the extension.

3. Build cart→order auto-copy into your design

A new capability of order metafield definitions lets you automatically copy values from the cart to the order at order creation. This reduces the need to write your own hand-off code.

2 guides

4. The official migration guides are the source of truth

Two migration guides are provided, one for cart and one for order. Concrete API specs and code diffs are not included in this article, so refer to the guides.

cart ↔ order

5. Re-divide data "ownership" between cart and order

Redesign with a clear split: data needed during checkout lives on the cart, and data that must persist after the order is placed lives on the order. For data needed in both places, the standard pattern is "write to the cart and auto-copy to the order at order creation."

73 practical use cases

USE CASE 1

"checkout metafields inventory → planned migration" for an existing store

Problem
Older API versions of checkout / customer account UI extensions depend on checkout metafields, and will break when upgraded to 2026-04.
Approach
List every dependency, then methodically replace Checkout UI extensions with cart metafields and Customer Account UI extensions with order metafields before upgrading.
Outcome
Avoid running into unsupported versions and production incidents, and keep maintainability on the latest API.
Technical notes
Follow the order: migrate first, then upgrade to 2026-04. Follow the two official migration guides for the concrete steps.
USE CASE 2

Automatically carry "information collected at checkout" through to post-purchase screens

Problem
You want to collect things like gift messages, delivery preferences, and consent flags at checkout and also show them on the post-purchase account screens, but the data hand-off was implemented by hand.
Approach
Write to cart metafields and use the order metafield definition's auto-copy to copy values to the order at order creation. The Customer Account UI extension then reads from order metafields.
Outcome
No more custom hand-off logic, reducing both the risk of data inconsistency and the implementation effort.
Technical notes
The copy fires at order creation. Design with the assumption that values changing after the order is created are out of scope.
USE CASE 3

Templatize "2026-04 readiness projects" for agencies and partners

Challenge
Multiple client extensions rely on checkout metafields, and investigating and migrating each project individually is inefficient.
Approach
Standardize a horizontal-rollout checklist: "detect dependencies → replace with cart/order → configure automatic copy → upgrade to 2026-04."
Impact
Level the estimation and quality of migration projects, shortening delivery times and preventing oversights.
Technical notes
Branch the checklist by extension type (Checkout UI / Customer Account UI), since the migration target differs accordingly.

8One-line summary for proposals

"In API 2026-04, checkout metafields have been removed. Checkout UI extensions must migrate to cart metafields, and Customer Account UI extensions must migrate to order metafields .
In addition, cart→order can now be automatically copied at order creation, reducing the need for custom-built data integrations.
The golden rule for ordering: 'migrate first, then upgrade to 2026-04.'"