Developer / UI Extensions / Breaking change notice

Metafield declarations now support owner_type as a new property
From 2027-01, extensions without it can't be deployed

In Checkout and Customer Account UI extensions,shopify.extension.toml metafield declarations can now specify which resource each metafield belongs to. It's optional in 2026-10 and required from 2027-01 onward. Shopify fetches only the resources the extension needs, which improves extension performance.

On this page
  1. What's changing? (30-second overview)
  2. How it works: owner_type narrows what gets fetched
  3. Timeline: optional in 2026-10, required in 2027-01
  4. Affected vs. unaffected extensions
  5. Example declaration and how identical namespace/key pairs are handled
  6. Migration steps (3 steps)
  7. 5 key points for developers
  8. 3 practical use cases
  9. One-line summary for proposals

1What's changing?

Until now, metafield declarations used only namespace and key, with no indication of which resource (a product? a customer?) they belonged to.
Now, the owner_type propertyis being added, so you can declare which resource owns each metafield.Required from API version 2027-01.
?

Before: no owner specified

Metafield declarations were specified by namespace / key. The resource type wasn't part of the declaration.

After: owner_type explicitly declares the owner

PRODUCT or CUSTOMER — declare the owner like this. Shopify fetches metafields only for the resource types the extension needs.

2How it works: owner_type narrows what gets fetched

shopify.extension.toml namespace / key owner_type = PRODUCT ① The extension declares metafields Shopify Checks owner_type to decide what to fetch ② Selects only the needed resource types PRODUCT ✓ Fetched Other resources — not fetched Other resources — not fetched Performance improvement ③ Lighter extensions
The article states the goal is "to fetch only the metafields for the resource types an extension needs, improving extension performance". No figures are given on how much faster it gets.

3Timeline: optional in 2026-10, required in 2027-01

~ 2026-07 No owner_type 2026-10 owner_type can be specified (Optional / can be added now) 2027-01 owner_type required on every declaration Deploys are blocked if missing Required from then on
If even one metafield declaration is missing owner_type, deploys themselves are blocked from 2027-01 onward. Add it to every declaration before upgrading. You can add it ahead of time as of 2026-10.

4Affected vs. unaffected extensions

ConditionImpactNotes
Checkout UI extensionsthat declare metafields in toml and use API 2027-01 or later Affected owner_type required on every declaration
Customer Account UI extensionsthat declare metafields in toml and use API 2027-01 or later Affected owner_type required on every declaration
The extensions above using API 2026-10 Optional Can be specified. Recommended time to get ahead
Extensions that don't declare metafields in toml Not affected No action needed
Target section 1

[[extensions.metafields]]

Extension-level metafield declarations. Accepts the owner_type property.

Target section 2

[[extensions.targeting.metafields]]

Per-target metafield declarations. These also accept the owner_type property.

5Example syntax and handling of identical namespace/key

Below is an example based on the article's description. The namespace / key values are illustrative. For possible owner_type values, the article only mentions PRODUCTandCUSTOMER as examples, with no full list given (see the related docs).

Blocked in 2027-01
[[extensions.metafields]] namespace = "custom" key = "example" # owner_type missing
OK
[[extensions.metafields]] namespace = "custom" key = "example" owner_type = "PRODUCT"

When you need to read the same namespace / key from multiple resources

Use custom.example from both products and customers Declaration A custom.example / PRODUCT Declaration B custom.example / CUSTOMER One per owner_type: split the declarations
[[extensions.metafields]] namespace = "custom" key = "example" owner_type = "PRODUCT" [[extensions.metafields]] namespace = "custom" key = "example" owner_type = "CUSTOMER"

6Migration steps (3 steps)

1

Add owner_type to the toml

Open your extension's shopify.extension.toml and add the appropriate owner_type to each metafield declaration.

2

Split declarations for multiple resources

If you use the same namespace / key from more than one resource type, create a separate declaration for each owner_type.

3

Redeploy and verify

Redeploy the extension and confirm it completes without any validation errors about metafield declarations.

Add it during 2026-10 and you can handle it separately from the 2027-01 upgrade. You won't have to bump the API version and fix metafield declarations at the same time.

75 key points for developers

1. A deploy block, not a warning

From 2027-01, a deploy fails if even one owner_type is missing. If you deploy extensions through CI/CD, expect the pipeline to stop and prepare for it.

TOML

2. Two declaration sections are affected

[[extensions.metafields]] and [[extensions.targeting.metafields]] : both of them. Watch out for missing declarations on the target side.

P C

3. One declaration = one owner_type

If you read the same namespace / key from multiple resources, split it into separate declarations. First, take stock of which resources' data each existing declaration actually reads.

4. The goal is performance

This tells Shopify which resource types to fetch metafields for, so it fetches only those. Getting owner_type right directly reduces how much data your extension fetches.

?

5. The full value list and runtime behavior aren't in the article

The only owner_type values the article gives as examples are PRODUCT and CUSTOMER . It doesn't list every allowed value or explain what the extension gets back if owner_type is wrong. Check the related docs, "Configure metafields for Checkout UI extensions" and "Configure metafields for Customer Account UI extensions".

83 practical use cases

USE CASE 1

Audit and update all the UI extensions you build or maintain for clients ahead of time

Challenge
You maintain Checkout / Customer Account UI extensions for several clients, and you don't know which ones will stop deploying once you move to 2027-01.
Approach
Go through every repository's shopify.extension.toml to list its metafield declarations, then add owner_type and redeploy during 2026-10.
Impact
Prevents deploy blocks when upgrading to 2027-01, so API update work stays on schedule.
Technical note
Extensions that don't declare metafields are unaffected, so start by filtering on whether declarations exist to get a realistic effort estimate.
CI
USE CASE 2

Avoiding "deploy halts" in CI/CD pipelines

Challenge
Extensions are auto-deployed from CI, so there's a risk that deploys fail after the API version bump PR is merged, blocking production releases.
Approach
Separately from the PR that bumps the API version to 2027-01, first deploy a PR that only adds owner_type, on 2026-10.
Impact
Splitting the change into two steps makes it easier to isolate the cause if a deploy fails, avoiding release stoppages.
Technical note
Per the article, the completion criterion is confirming that no metafield declaration validation errors appear after redeploying.
Data fetched
USE CASE 3

Reviewing heavy, metafield-dependent extensions

Challenge
Some extensions reference many metafields on products, customers, and other resources, and it's unclear which resources' data they actually use.
Approach
Use the owner_type update as a chance to clarify which resource type each declaration references and clean up unneeded declarations.
Impact
Shopify fetches only the resource types you need, improving extension performance (the size of the improvement isn't specified).
Technical note
Places that use the same namespace / key across multiple resources need their declarations split. Identify them during the audit.

9One-line summary for proposals

"Checkout / Customer Account UI extension metafield declarations now include owner_type, which identifies the owning resource.
You can specify it starting in 2026-10, and from 2027-01 deploys fail if it's missing.
Add it to your toml and redeploy now to make your extensions lighter and keep upgrades unblocked."