Shopify Checkout Extension Deploy Fails on 2027-01? Add owner_type to Metafield Declarations

Quick answer

When a Checkout UI or Customer Account UI extension targets API version 2027-01 or later, every declared metafield in shopify.extension.toml must include owner_type. Without it, Shopify blocks deployment. The property is already accepted on 2026-10, where it is optional, so you can fix the configuration before upgrading.

Audit both [[extensions.metafields]] and [[extensions.targeting.metafields]]. The latter is easy to miss because it is nested under a specific render target. If the extension does not declare metafields in TOML, this particular requirement does not apply.

What changed and why

Older examples declare only namespace and key. That left Shopify to determine which resource types might contain the requested data. On October 8, 2026, Shopify introduced owner_type to specify the owner explicitly, allowing the extension runtime to fetch only the metafields it needs. The field becomes mandatory with API version 2027-01.

There is an important distinction between a metafield definition in the shop and a metafield declaration in an extension. Adding a definition in the Shopify admin does not automatically update shopify.extension.toml. The deployment rule checks the extension’s declarations.

Correct the extension TOML

Here is a compact configuration for API version 2026-10. It shows a product metafield available to the extension and a customer metafield requested only for a particular checkout target:

api_version = "2026-10"

[[extensions.metafields]]
namespace = "custom"
key = "care_instructions"
owner_type = "PRODUCT"

[[extensions.targeting]]
target = "purchase.checkout.actions.render-before"
module = "./src/Actions.jsx"

[[extensions.targeting.metafields]]
namespace = "custom"
key = "loyalty_tier"
owner_type = "CUSTOMER"

Merge these declarations into your existing extension configuration; do not replace the full file with this excerpt. Keep your current extension type, handle, capabilities, modules, and target definitions. The target and module above are illustrative and must match an actual supported target and file in your project.

For checkout declarations, Shopify documents these owner types: CART, COMPANY, COMPANY_LOCATION, CUSTOMER, PRODUCT, PRODUCTVARIANT, and SHOP. The exact owner type is determined by where the value lives, not by the UI screen displaying it. Check the target-specific customer account documentation before assuming a checkout owner type is valid on every customer account target.

Audit every declaration, including repeated keys

1. Find the extension configurations. Search your app’s extensions/ directory for shopify.extension.toml files and locate all occurrences of [[extensions.metafields]] and [[extensions.targeting.metafields]].
2. Map namespace and key to a real owner. For example, a product care instruction belongs to PRODUCT, while a loyalty tier stored on a customer belongs to CUSTOMER. Do not guess from the key name.
3. Split ambiguous declarations. If the same namespace/key pair is used on two resource types, Shopify requires separate declarations with separate owner_type values. One declaration does not cover both owners.
4. Keep declaration scope intentional. Use extensions.metafields for an extension-wide requirement and extensions.targeting.metafields when only a particular target needs the data.
5. Upgrade and deploy in stages. Add owner types on API version 2026-10 first, test, then upgrade to 2027-01 when you are ready. This isolates the declaration change from unrelated API migrations.

Do not confuse this with the 2026 checkout-metafield migration

Shopify separately removed the old checkout metafield read/write API in checkout and customer-account UI extensions beginning with 2026-04. That migration moved checkout data toward cart metafields and customer-account scenarios toward order metafields. The new owner_type requirement does not restore the removed checkout metafield API, nor does it migrate data between cart and order resources. Treat those as separate changes and test them independently.

Common misunderstanding

“My extension deploys on 2026-10, so the TOML is future-proof.” Not necessarily. On 2026-10, owner_type is optional. The same declaration without it is rejected on 2027-01.

“I can use ORDER everywhere because the data appears on an order-status page.” The owner must match the resource storing the metafield. A product metafield remains PRODUCT even when shown after purchase.

“This applies to every metafield in my app.” The announced deployment requirement is for metafields declared in Checkout and Customer Account UI extension TOML files, not every Admin API metafield or theme Liquid lookup.

How to test this

1. Record the extension’s current API version and save a working deployment or version reference.
2. On 2026-10, add owner_type to every declaration in both TOML locations. Search again to ensure none were skipped.
3. Run the extension locally on a development store with sample metafields for each owner type, including B2B company/location context if used.
4. Verify the extension reads the correct value for each product, customer, and other applicable resource. Test absent values and buyers who do not have the expected resource context.
5. Build and deploy a development version. When ready, switch to API 2027-01 and confirm that validation no longer reports missing owner types.
6. Check all configured render targets, not only the one visible in your first preview. Keep rollback instructions for the previous deployed version.

Sources and further reading

• Shopify developer changelog: owner_type required in 2027-01 (October 8, 2026)
• Shopify developer docs: using metafields in checkout
• Shopify developer docs: metafields in customer accounts
• Shopify developer changelog: earlier checkout metafield API deprecation

Documentation checked October 18, 2026.