Shopify Metafields Bulk Create & Update via Admin API

Efficiently manage Shopify metafields using the Admin API, creating or updating multiple product, customer, collection, and order metafields in bulk with fewer API calls.

Key Points

Update up to 100 metafields per request, saving time and reducing API load calls.
Supports 6 entity types: products, variants, collections, customers, orders, and shops.
Reduces API requests by as much as 90% when managing bulk metafields updates.

Managing metafields in Shopify is now simpler. With Shopify’s Admin GraphQL API, developers can easily create or update multiple metafields simultaneously using the bulk metafieldsSet mutation. This method is a game-changer for Shopify web development, as it significantly reduces the number of API calls needed to handle large sets of product, variant, collection, or customer data metafields.

Whether you are developing a complex Shopify website or hiring a professional Shopify developer, understanding how to efficiently manage metafields is crucial for structured and scalable store management.

Required Permissions

To use the metafieldsSet mutation, your app or access token must have the necessary Admin API privileges:

Scope Type and Permission Name

Read/Write: write_metafields
Read/Write: write_products (if targeting products)
Read/Write: write_customers (if targeting customers)
Read/Write: write_collections (if targeting collections)

Ensuring the correct permissions is a crucial step in any custom Shopify web development project to prevent errors during bulk metafield updates.

Understanding the metafieldsSet Mutation

The metafieldsSet mutation enables you to create new metafields or update existing ones using the ownerId and namespace/key combination. This is especially useful for Shopify web development services focused on product customization, advanced filtering, or customer-specific needs data.

Example Mutation: Bulk Create/Update Metafields

                                        mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      namespace
      key
      value
      type
      owner {
        ... on Product {
          id
          title
        }
      }
    }
    userErrors {
      field
      message
      code
    }
  }
}

Example Variables

                                        {
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/1234567890",
      "namespace": "custom",
      "key": "material",
      "type": "single_line_text_field",
      "value": "Cotton"
    },
    {
      "ownerId": "gid://shopify/Product/1234567890",
      "namespace": "custom",
      "key": "color",
      "type": "single_line_text_field",
      "value": "Blue"
    },
    {
      "ownerId": "gid://shopify/Product/1234567890",
      "namespace": "custom",
      "key": "size",
      "type": "single_line_text_field",
      "value": "Large"
    }
  ]
}

Using this structure helps a Shopify developer manage metafields for multiple products efficiently without making multiple API calls, speeding up Shopify website development projects efficient.

Supported Metafield Owners

Entity Type and Example GID Format

Product: gid://shopify/Product/1234567890
Product Variant: gid://shopify/ProductVariant/987654321
Collection: gid://shopify/Collection/1122334455
Customer: gid://shopify/Customer/9988776655
Shop: gid://shopify/Shop/1
Order: gid://shopify/Order/6677889900

This flexibility is why Shopify web development services are so valuable: they enable businesses to utilize advanced data structures for products, customers, and collections.

How the Bulk Metafields Operation Works

Each metafield is uniquely identified by the combination of:

ownerId
namespace
key

Behavior:

If the metafield does not exist, Shopify will create it.
If the metafield already exists, Shopify will update it.

You can send up to 100 metafields per request, making it ideal for professional Shopify website development and custom Shopify web development projects.

Response Example

                                        {
  "data": {
    "metafieldsSet": {
      "metafields": [
        {
          "id": "gid://shopify/Metafield/123456789",
          "namespace": "custom",
          "key": "color",
          "value": "Blue",
          "type": "single_line_text_field",
          "owner": {
            "id": "gid://shopify/Product/1234567890",
            "title": "Cotton T-Shirt"
          }
        }
      ],
      "userErrors": []
    }
  }
}

Error Handling

INVALID_TYPE

Description: The type you provided doesn’t match the existing metafield type.
Example: "message": "Type mismatch for metafield 'color'."

OWNER_NOT_FOUND

Description: The ownerId is missing or invalid.
Example: "message": "Product not found for provided ownerId."

INVALID_NAMESPACE_KEY

Description: The namespace or key format is invalid.
Example: "message": "Invalid namespace 'custom space'."

Proper error handling is critical when you hire Shopify developer to manage bulk metafields efficiently.

Example Use Case: Bulk Updating Product Metafields

You can update metafields for multiple products in a single mutation:

                                        mutation metafieldsSet($metafields: [MetafieldsSetInput!]!) {
  metafieldsSet(metafields: $metafields) {
    metafields {
      id
      key
      value
      owner {
        ... on Product {
          title
        }
      }
    }
    userErrors {
      message
    }
  }
}

Variables

                                        {
  "metafields": [
    {
      "ownerId": "gid://shopify/Product/1234567890",
      "namespace": "custom",
      "key": "bundle_id",
      "type": "number_integer",
      "value": "123"
    },
    {
      "ownerId": "gid://shopify/Product/9876543210",
      "namespace": "custom",
      "key": "bundle_id",
      "type": "number_integer",
      "value": "456"
    }
  ]
}

This approach ensures your Shopify web development services projects are scalable, reducing errors and maintaining consistent product data.

Steps to Use

Generate Admin Access Token

Use a private or custom Shopify app to obtain an Admin API token.

Get Product or Entity GIDs

Use the Admin GraphQL API to retrieve GIDs for products, variants, collections, or other entities.

Use the metafieldsSet Mutation

Pass your metafield data using the mutation.

Validate Response and Handle Errors

Check for userErrors to ensure all metafields were successfully created or updated.

Optional: Query Metafields

Use the metafields connection to confirm updates and verify data integrity.

By implementing these steps with custom Shopify web development or hiring a skilled Shopify developer, businesses can manage metafields effectively and improve their overall Shopify store performance.

Final Words

Shopify’s metafieldsSet mutation is a cornerstone for efficient bulk metafield management. Whether you’re optimizing products, collections, or customer data, leveraging this API allows for structured, scalable, and error-free Shopify website development. Partnering with professional Shopify web development services or hiring a reliable Shopify developer ensures your store operates efficiently while keeping data consistent across all entities.