Shopify Metafield Import Error: Owner Subtype Does Not Match

Quick answer

If a Shopify bulk import fails with Owner subtype does not match the metafield definition's constraints, check the metafield definition and the product’s Shopify product category before changing the value. A definition can be restricted to specific taxonomy categories. Set the correct category first, then retry the metafield values. Also verify the import targets the correct owner type: product versus variant.

Why it happens

A metafield definition is more than a namespace and key. It declares an owner type, data type, and potentially a set of constraints. Shopify supports category-based constraints on product metafield definitions: a field intended for shoes need not apply to sweaters. That is what owner subtype refers to in this constraint system. Product and variant are separate owner types.

Bulk migrations expose this because products may arrive without their final Shopify taxonomy category, while the import tries to write constrained metafields. The value can be syntactically valid and still be rejected.

Practical implementation: fix the import in the right order

1. Record the failing row, namespace/key, and exact error. Do not change the metafield’s type at random.
2. Go to Settings → Custom data → Products. Inspect the definition, value type, and any category restrictions. If it is a variant definition, look under Variants instead.
3. Open the failed product and inspect Category. Confirm that it matches an allowed Shopify taxonomy category, not merely a custom product type.
4. On a new store, establish the definitions and import product categories first. Verify categories saved, then import the constrained metafield values. If your tool claims to do both in one pass, test its processing order on one record.
5. Verify the import column. In Matrixify’s Products sheet, product-level fields use Metafield: while variant-level fields use Variant Metafield:.
6. Retry one known-good product and one failed product, then run a ten-product sample before scaling up.

Developer check: inspect constraints with GraphQL

query ProductMetafieldDefinitions {
  metafieldDefinitions(first: 100, ownerType: PRODUCT) {
    nodes {
      namespace
      key
      ownerType
      type { name }
      constraints {
        key
        values(first: 20) { nodes { value } }
      }
    }
  }
}

Locate your namespace.key in the results. A constraint with key: "category" lists applicable taxonomy categories. Paginate if you have more than 100 definitions. This is a diagnostic query, not a mutation.

Common misunderstanding

“Owner subtype means I put a product metafield on a variant.” That can be a separate mistake, but the specific subtype constraint in Shopify’s conditional definitions is based on product categories. Correcting a product/variant header will not fix an incompatible category.

“The JSON must be malformed.” Constraint failures and invalid-value errors are different. Fix the reported constraint before rewriting a valid JSON payload.

How to test this

1. Record the original category and definition constraints on a failing product.
2. Assign a compatible category and save.
3. Import only the failing metafield, then verify its value on the product and through the Admin API.
4. Repeat with an incompatible category in a development store to verify the restriction.
5. Export the repaired records and compare them to the original import file.

Sources and further reading

• Shopify Dev: Conditional metafield definitions
• Shopify Dev: MetafieldDefinition
• Matrixify: Metafields import/export

Documentation checked October 9, 2026.