Read and write values

Discover definitions read-only, then upsert values by namespace.key on owner resources.

After install, use your app token (tpat_ or tast_) against the Store API. Value endpoints address definitions by namespace and key, never by raw definition IDs.

Discover definitions (read-only)#

GET /api/2025-01/metafield-definitions?owner_type={owner} lists definitions visible to your token: definitions your app owns, merchant-owned definitions, and another app's definitions only when app_access is shared. Use this when you need to enumerate keys at runtime — not to create schema.

Write values#

PUT on the owner resource accepts an array of {namespace, key, value} entries. Send null or an empty string as value to delete a value. Access is re-checked on every write: your app can set values only on definitions it owns. app_access=shared grants reads to other appropriately scoped apps, not writes.

Owner	Value endpoints	Typical scopes
Product	`GET` / `PUT` `/products/{id}/metafields`	`read_products` / `write_products`
Variant	`GET` / `PUT` `/products/{id}/variants/{variantId}/metafields`	`read_products` / `write_products`
Customer	`GET` / `PUT` `/customers/{id}/metafields`	`read_customers` / `write_customers`
Collection	`GET` / `PUT` `/collections/{id}/metafields`	`read_products` / `write_products`
Category	`GET` / `PUT` `/categories/{id}/metafields`	`read_products` / `write_products`
Page	`GET` / `PUT` `/pages/{id}/metafields`	`read_pages` / `write_pages`
Brand	`GET` / `PUT` `/brands/{id}/metafields`	`read_products` / `write_products`
Vendor	`GET` / `PUT` `/vendors/{id}/metafields`	`read_products` / `write_products`
Order	`GET` / `PUT` `/orders/{orderId}/metafields`	`read_orders` / `write_orders`
Order line	`GET` / `PUT` `/orders/{orderId}/items/{itemId}/metafields`	`read_orders` / `write_orders`
Store (shop)	`GET` / `PUT` `/store/metafields`	`read_storefront` / `write_storefront`

Example: set a product metafield#

set-product-metafields.json json

{
  "metafields": [
    {
      "namespace": "app:my-app",
      "key": "material",
      "value": "organic-cotton"
    }
  ]
}

Call PUT /api/2025-01/products/{product_id}/metafields with the JSON body above. Replace app:my-app with your live namespace (app:{slug}) and material with your declared key.

Further reference#

See the Metafield definitions Store API page for the discovery response shape, owner-type to scope mapping, and visibility matrix. Each owner resource guide (Products, Customers, …) documents its metafield list/set endpoints, translation routes where applicable, and webhook topics for value changes.