Metafield

Version 2020-01

The Metafield resource allows you to add additional information to other Admin API resources. Metafields can be used in several ways, such as to add a summary to a blog post. You can also use metafields to share information with other Shopify apps.

Resources that can have metafields

Metafields can be added to the following resources:

Type of resource	Location of metafields
Article	`/admin/blogs/#{id}/articles/#{id}/metafields.json`
Blog	`/admin/blogs/#{id}/metafields.json`
CustomCollection and SmartCollection	`/admin/collections/#{id}/metafields.json`
Customer	`/admin/customers/#{id}/metafields.json`
Draft Order	`/admin/draft_orders/#{id}/metafields.json`
Order	`/admin/orders/#{id}/metafields.json`
Page	`/admin/pages/#{id}/metafields.json`
Product	`/admin/products/#{id}/metafields.json`
Product Variant	`/admin/products/#{id}/variants/#{id}/metafields.json`
Product Image	`/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image` This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.
Shop	`/admin/metafields.json`

What you can do with Metafield

The Shopify API lets you do the following with the Metafield resource. More detailed versions of these general actions may be available:

GET /admin/api/2020-01/metafields.json Retrieves a list of metafields that belong to a resource
GET /admin/api/2020-01/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image Retrieves a list of metafields that belong to a Product Image resource
GET /admin/api/2020-01/metafields/count.json Retrieves a count of a resource's metafields
GET /admin/api/2020-01/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
POST /admin/api/2020-01/metafields.json Creates a new metafield for a resource
PUT /admin/api/2020-01/metafields/{metafield_id}.json Updates a metafield
DELETE /admin/api/2020-01/metafields/{metafield_id}.json Deletes a metafield by its ID

Metafield properties

created_at read-only	`"created_at": "2012-03-13T16:09:54-04:00"` The date and time (ISO 8601 format) when the metafield was created.
updated_at read-only	`"updated_at": "2012-08-24T14:02:15-04:00"` The date and time (ISO 8601 format) when the metafield was last updated.
description	`"description": null` A description of the information that the metafield contains.
id read-only	`"id": 915396206` The unique ID of the metafield.
key required	`"key": "warehouse"` The name of the metafield. Maximum length: 30 characters.
namespace required	`"namespace": "inventory"` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.
owner_id	`"owner_id": 690933842` The unique ID of the resource that the metafield is attached to.
owner_resource	`"owner_resource": "product"` The type of resource that the metafield is attached to.
value required	`"value": 25` The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to `tags` and key is equal to `alt`.
value_type required	`"value_type": "integer"` The metafield's information type. Valid values: `string`, `integer`, `json_string`.

Endpoints

GET /admin/api/2020-01/metafields.json

Retrieves a list of metafields that belong to a resource. Note: As of version 2019-07, this endpoint implements pagination by using links that are provided in the response header. Sending the page parameter will return an error. To learn more, see Making requests to paginated REST Admin API endpoints.

limit	Amount of results (default: `50`, maximum: `250`)
since_id	Restrict results to after the specified ID
created_at_min	Show metafields created after date (format: 2014-04-25T16:15:47-04:00)
created_at_max	Show metafields created before date (format: 2014-04-25T16:15:47-04:00)
updated_at_min	Show metafields last updated after date (format: 2014-04-25T16:15:47-04:00)
updated_at_max	Show metafields last updated before date (format: 2014-04-25T16:15:47-04:00)
namespace	Show metafields with given namespace
key	Show metafields with given key
value_type	string: Show only metafields with string value types integer: Show only metafields with integer value types
fields	comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/api/2020-01/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 721389482,
      "namespace": "affiliates",
      "key": "app_key",
      "value": "app_key",
      "value_type": "string",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
    }
  ]
}

Retrieve metafields after the specified ID that belong to a Shop resource

GET /admin/api/2020-01/metafields.json?since_id=721389482

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298172,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:20:56-05:00",
      "updated_at": "2020-11-04T16:20:56-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298172"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/2020-01/products/632910392/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 845366454,
      "namespace": "translations",
      "key": "title_fr",
      "value": "produit",
      "value_type": "string",
      "description": "French product title",
      "owner_id": 632910392,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}

GET /admin/api/2020-01/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

Retrieves a list of metafields that belong to a Product Image resource.

Retrieve a list of metafields that belong to a Product Image resource

GET /admin/api/2020-01/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 625663657,
      "namespace": "translation",
      "key": "title_fr",
      "value": "tbn",
      "value_type": "string",
      "description": "French product image title",
      "owner_id": 850703190,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}

GET /admin/api/2020-01/metafields/count.json

Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/api/2020-01/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Retrieve a count of metafields that belong to a Product resource

GET /admin/api/2020-01/products/632910392/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

GET /admin/api/2020-01/metafields/{metafield_id}.json

Retrieves a single metafield from a resource by its ID.

fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single metafield by its ID

GET /admin/api/2020-01/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "app_key",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Retrieve a single metafield by its ID

GET /admin/api/2020-01/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "produit",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

POST /admin/api/2020-01/metafields.json

Creates a new metafield for a resource.

Create a new metafield for a Shop resource

POST /admin/api/2020-01/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298173,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:21:02-05:00",
    "updated_at": "2020-11-04T16:21:02-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298173"
  }
}

Create a new metafield for a Product resource

POST /admin/api/2020-01/products/632910392/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298174,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:21:03-05:00",
    "updated_at": "2020-11-04T16:21:03-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298174"
  }
}

Creating a metafield without a key will fail and return an error

POST /admin/api/2020-01/metafields.json

{
  "metafield": {
    "key": null
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "namespace": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "key": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ],
    "value": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-01/metafields/{metafield_id}.json

Updates a metafield.

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-01/metafields/721389482.json

{
  "metafield": {
    "id": 721389482,
    "value": "something new",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "something new",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:05-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-01/products/632910392/metafields/845366454.json

{
  "metafield": {
    "id": 845366454,
    "value": "titre",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "titre",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:06-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

DELETE /admin/api/2020-01/metafields/{metafield_id}.json

Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/api/2020-01/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/api/2020-01/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-04

Resources that can have metafields

Metafields can be added to the following resources:

Type of resource	Location of metafields
Article	`/admin/blogs/#{id}/articles/#{id}/metafields.json`
Blog	`/admin/blogs/#{id}/metafields.json`
CustomCollection and SmartCollection	`/admin/collections/#{id}/metafields.json`
Customer	`/admin/customers/#{id}/metafields.json`
Draft Order	`/admin/draft_orders/#{id}/metafields.json`
Order	`/admin/orders/#{id}/metafields.json`
Page	`/admin/pages/#{id}/metafields.json`
Product	`/admin/products/#{id}/metafields.json`
Product Variant	`/admin/products/#{id}/variants/#{id}/metafields.json`
Product Image	`/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image` This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.
Shop	`/admin/metafields.json`

What you can do with Metafield

The Shopify API lets you do the following with the Metafield resource. More detailed versions of these general actions may be available:

GET /admin/api/2020-04/metafields.json Retrieves a list of metafields that belong to a resource
GET /admin/api/2020-04/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image Retrieves a list of metafields that belong to a Product Image resource
GET /admin/api/2020-04/metafields/count.json Retrieves a count of a resource's metafields
GET /admin/api/2020-04/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
POST /admin/api/2020-04/metafields.json Creates a new metafield for a resource
PUT /admin/api/2020-04/metafields/{metafield_id}.json Updates a metafield
DELETE /admin/api/2020-04/metafields/{metafield_id}.json Deletes a metafield by its ID

Metafield properties

created_at read-only	`"created_at": "2012-03-13T16:09:54-04:00"` The date and time (ISO 8601 format) when the metafield was created.
updated_at read-only	`"updated_at": "2012-08-24T14:02:15-04:00"` The date and time (ISO 8601 format) when the metafield was last updated.
description	`"description": null` A description of the information that the metafield contains.
id read-only	`"id": 915396206` The unique ID of the metafield.
key required	`"key": "warehouse"` The name of the metafield. Maximum length: 30 characters.
namespace required	`"namespace": "inventory"` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.
owner_id	`"owner_id": 690933842` The unique ID of the resource that the metafield is attached to.
owner_resource	`"owner_resource": "product"` The type of resource that the metafield is attached to.
value required	`"value": 25` The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to `tags` and key is equal to `alt`.
value_type required	`"value_type": "integer"` The metafield's information type. Valid values: `string`, `integer`, `json_string`.

Endpoints

GET /admin/api/2020-04/metafields.json

limit	Amount of results (default: `50`, maximum: `250`)
since_id	Restrict results to after the specified ID
created_at_min	Show metafields created after date (format: 2014-04-25T16:15:47-04:00)
created_at_max	Show metafields created before date (format: 2014-04-25T16:15:47-04:00)
updated_at_min	Show metafields last updated after date (format: 2014-04-25T16:15:47-04:00)
updated_at_max	Show metafields last updated before date (format: 2014-04-25T16:15:47-04:00)
namespace	Show metafields with given namespace
key	Show metafields with given key
value_type	string: Show only metafields with string value types integer: Show only metafields with integer value types
fields	comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/api/2020-04/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 721389482,
      "namespace": "affiliates",
      "key": "app_key",
      "value": "app_key",
      "value_type": "string",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
    }
  ]
}

Retrieve metafields after the specified ID that belong to a Shop resource

GET /admin/api/2020-04/metafields.json?since_id=721389482

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298172,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:20:56-05:00",
      "updated_at": "2020-11-04T16:20:56-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298172"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/2020-04/products/632910392/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 845366454,
      "namespace": "translations",
      "key": "title_fr",
      "value": "produit",
      "value_type": "string",
      "description": "French product title",
      "owner_id": 632910392,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}

GET /admin/api/2020-04/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

Retrieves a list of metafields that belong to a Product Image resource.

Retrieve a list of metafields that belong to a Product Image resource

GET /admin/api/2020-04/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 625663657,
      "namespace": "translation",
      "key": "title_fr",
      "value": "tbn",
      "value_type": "string",
      "description": "French product image title",
      "owner_id": 850703190,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}

GET /admin/api/2020-04/metafields/count.json

Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/api/2020-04/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Retrieve a count of metafields that belong to a Product resource

GET /admin/api/2020-04/products/632910392/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

GET /admin/api/2020-04/metafields/{metafield_id}.json

Retrieves a single metafield from a resource by its ID.

fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single metafield by its ID

GET /admin/api/2020-04/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "app_key",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Retrieve a single metafield by its ID

GET /admin/api/2020-04/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "produit",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

POST /admin/api/2020-04/metafields.json

Creates a new metafield for a resource.

Create a new metafield for a Shop resource

POST /admin/api/2020-04/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298173,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:21:02-05:00",
    "updated_at": "2020-11-04T16:21:02-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298173"
  }
}

Create a new metafield for a Product resource

POST /admin/api/2020-04/products/632910392/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298174,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:21:03-05:00",
    "updated_at": "2020-11-04T16:21:03-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298174"
  }
}

Creating a metafield without a key will fail and return an error

POST /admin/api/2020-04/metafields.json

{
  "metafield": {
    "key": null
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "namespace": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "key": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ],
    "value": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-04/metafields/{metafield_id}.json

Updates a metafield.

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-04/metafields/721389482.json

{
  "metafield": {
    "id": 721389482,
    "value": "something new",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "something new",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:05-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-04/products/632910392/metafields/845366454.json

{
  "metafield": {
    "id": 845366454,
    "value": "titre",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "titre",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:06-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

DELETE /admin/api/2020-04/metafields/{metafield_id}.json

Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/api/2020-04/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/api/2020-04/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-07

Resources that can have metafields

Metafields can be added to the following resources:

Type of resource	Location of metafields
Article	`/admin/blogs/#{id}/articles/#{id}/metafields.json`
Blog	`/admin/blogs/#{id}/metafields.json`
CustomCollection and SmartCollection	`/admin/collections/#{id}/metafields.json`
Customer	`/admin/customers/#{id}/metafields.json`
Draft Order	`/admin/draft_orders/#{id}/metafields.json`
Order	`/admin/orders/#{id}/metafields.json`
Page	`/admin/pages/#{id}/metafields.json`
Product	`/admin/products/#{id}/metafields.json`
Product Variant	`/admin/products/#{id}/variants/#{id}/metafields.json`
Product Image	`/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image` This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.
Shop	`/admin/metafields.json`

What you can do with Metafield

The Shopify API lets you do the following with the Metafield resource. More detailed versions of these general actions may be available:

GET /admin/api/2020-07/metafields.json Retrieves a list of metafields that belong to a resource
GET /admin/api/2020-07/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image Retrieves a list of metafields that belong to a Product Image resource
GET /admin/api/2020-07/metafields/count.json Retrieves a count of a resource's metafields
GET /admin/api/2020-07/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
POST /admin/api/2020-07/metafields.json Creates a new metafield for a resource
PUT /admin/api/2020-07/metafields/{metafield_id}.json Updates a metafield
DELETE /admin/api/2020-07/metafields/{metafield_id}.json Deletes a metafield by its ID

Metafield properties

created_at read-only	`"created_at": "2012-03-13T16:09:54-04:00"` The date and time (ISO 8601 format) when the metafield was created.
updated_at read-only	`"updated_at": "2012-08-24T14:02:15-04:00"` The date and time (ISO 8601 format) when the metafield was last updated.
description	`"description": null` A description of the information that the metafield contains.
id read-only	`"id": 915396206` The unique ID of the metafield.
key required	`"key": "warehouse"` The name of the metafield. Maximum length: 30 characters.
namespace required	`"namespace": "inventory"` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.
owner_id	`"owner_id": 690933842` The unique ID of the resource that the metafield is attached to.
owner_resource	`"owner_resource": "product"` The type of resource that the metafield is attached to.
value required	`"value": 25` The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to `tags` and key is equal to `alt`.
value_type required	`"value_type": "integer"` The metafield's information type. Valid values: `string`, `integer`, `json_string`.

Endpoints

GET /admin/api/2020-07/metafields.json

limit	Amount of results (default: `50`, maximum: `250`)
since_id	Restrict results to after the specified ID
created_at_min	Show metafields created after date (format: 2014-04-25T16:15:47-04:00)
created_at_max	Show metafields created before date (format: 2014-04-25T16:15:47-04:00)
updated_at_min	Show metafields last updated after date (format: 2014-04-25T16:15:47-04:00)
updated_at_max	Show metafields last updated before date (format: 2014-04-25T16:15:47-04:00)
namespace	Show metafields with given namespace
key	Show metafields with given key
value_type	string: Show only metafields with string value types integer: Show only metafields with integer value types
fields	comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/api/2020-07/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 721389482,
      "namespace": "affiliates",
      "key": "app_key",
      "value": "app_key",
      "value_type": "string",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
    }
  ]
}

Retrieve metafields after the specified ID that belong to a Shop resource

GET /admin/api/2020-07/metafields.json?since_id=721389482

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298172,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:20:56-05:00",
      "updated_at": "2020-11-04T16:20:56-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298172"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/2020-07/products/632910392/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 845366454,
      "namespace": "translations",
      "key": "title_fr",
      "value": "produit",
      "value_type": "string",
      "description": "French product title",
      "owner_id": 632910392,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}

GET /admin/api/2020-07/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

Retrieves a list of metafields that belong to a Product Image resource.

Retrieve a list of metafields that belong to a Product Image resource

GET /admin/api/2020-07/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 625663657,
      "namespace": "translation",
      "key": "title_fr",
      "value": "tbn",
      "value_type": "string",
      "description": "French product image title",
      "owner_id": 850703190,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}

GET /admin/api/2020-07/metafields/count.json

Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/api/2020-07/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Retrieve a count of metafields that belong to a Product resource

GET /admin/api/2020-07/products/632910392/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

GET /admin/api/2020-07/metafields/{metafield_id}.json

Retrieves a single metafield from a resource by its ID.

fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single metafield by its ID

GET /admin/api/2020-07/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "app_key",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Retrieve a single metafield by its ID

GET /admin/api/2020-07/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "produit",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

POST /admin/api/2020-07/metafields.json

Creates a new metafield for a resource.

Create a new metafield for a Shop resource

POST /admin/api/2020-07/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298173,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:21:02-05:00",
    "updated_at": "2020-11-04T16:21:02-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298173"
  }
}

Create a new metafield for a Product resource

POST /admin/api/2020-07/products/632910392/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298174,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:21:03-05:00",
    "updated_at": "2020-11-04T16:21:03-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298174"
  }
}

Creating a metafield without a key will fail and return an error

POST /admin/api/2020-07/metafields.json

{
  "metafield": {
    "key": null
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "namespace": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "key": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ],
    "value": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-07/metafields/{metafield_id}.json

Updates a metafield.

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-07/metafields/721389482.json

{
  "metafield": {
    "id": 721389482,
    "value": "something new",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "something new",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:05-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-07/products/632910392/metafields/845366454.json

{
  "metafield": {
    "id": 845366454,
    "value": "titre",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "titre",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:06-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

DELETE /admin/api/2020-07/metafields/{metafield_id}.json

Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/api/2020-07/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/api/2020-07/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
}

Version 2020-10 (Latest)

Resources that can have metafields

Metafields can be added to the following resources:

Type of resource	Location of metafields
Article	`/admin/blogs/#{id}/articles/#{id}/metafields.json`
Blog	`/admin/blogs/#{id}/metafields.json`
CustomCollection and SmartCollection	`/admin/collections/#{id}/metafields.json`
Customer	`/admin/customers/#{id}/metafields.json`
Draft Order	`/admin/draft_orders/#{id}/metafields.json`
Order	`/admin/orders/#{id}/metafields.json`
Page	`/admin/pages/#{id}/metafields.json`
Product	`/admin/products/#{id}/metafields.json`
Product Variant	`/admin/products/#{id}/variants/#{id}/metafields.json`
Product Image	`/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image` This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.
Shop	`/admin/metafields.json`

What you can do with Metafield

The Shopify API lets you do the following with the Metafield resource. More detailed versions of these general actions may be available:

GET /admin/api/2020-10/metafields.json Retrieves a list of metafields that belong to a resource
GET /admin/api/2020-10/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image Retrieves a list of metafields that belong to a Product Image resource
GET /admin/api/2020-10/metafields/count.json Retrieves a count of a resource's metafields
GET /admin/api/2020-10/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
POST /admin/api/2020-10/metafields.json Creates a new metafield for a resource
PUT /admin/api/2020-10/metafields/{metafield_id}.json Updates a metafield
DELETE /admin/api/2020-10/metafields/{metafield_id}.json Deletes a metafield by its ID

Metafield properties

created_at read-only	`"created_at": "2012-03-13T16:09:54-04:00"` The date and time (ISO 8601 format) when the metafield was created.
updated_at read-only	`"updated_at": "2012-08-24T14:02:15-04:00"` The date and time (ISO 8601 format) when the metafield was last updated.
description	`"description": null` A description of the information that the metafield contains.
id read-only	`"id": 915396206` The unique ID of the metafield.
key required	`"key": "warehouse"` The name of the metafield. Maximum length: 30 characters.
namespace required	`"namespace": "inventory"` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.
owner_id	`"owner_id": 690933842` The unique ID of the resource that the metafield is attached to.
owner_resource	`"owner_resource": "product"` The type of resource that the metafield is attached to.
value required	`"value": 25` The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to `tags` and key is equal to `alt`.
value_type required	`"value_type": "integer"` The metafield's information type. Valid values: `string`, `integer`, `json_string`.

Endpoints

GET /admin/api/2020-10/metafields.json

limit	Amount of results (default: `50`, maximum: `250`)
since_id	Restrict results to after the specified ID
created_at_min	Show metafields created after date (format: 2014-04-25T16:15:47-04:00)
created_at_max	Show metafields created before date (format: 2014-04-25T16:15:47-04:00)
updated_at_min	Show metafields last updated after date (format: 2014-04-25T16:15:47-04:00)
updated_at_max	Show metafields last updated before date (format: 2014-04-25T16:15:47-04:00)
namespace	Show metafields with given namespace
key	Show metafields with given key
value_type	string: Show only metafields with string value types integer: Show only metafields with integer value types
fields	comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/api/2020-10/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 721389482,
      "namespace": "affiliates",
      "key": "app_key",
      "value": "app_key",
      "value_type": "string",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
    }
  ]
}

Retrieve metafields after the specified ID that belong to a Shop resource

GET /admin/api/2020-10/metafields.json?since_id=721389482

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298172,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:20:56-05:00",
      "updated_at": "2020-11-04T16:20:56-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298172"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/2020-10/products/632910392/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 845366454,
      "namespace": "translations",
      "key": "title_fr",
      "value": "produit",
      "value_type": "string",
      "description": "French product title",
      "owner_id": 632910392,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}

GET /admin/api/2020-10/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

Retrieves a list of metafields that belong to a Product Image resource.

Retrieve a list of metafields that belong to a Product Image resource

GET /admin/api/2020-10/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 625663657,
      "namespace": "translation",
      "key": "title_fr",
      "value": "tbn",
      "value_type": "string",
      "description": "French product image title",
      "owner_id": 850703190,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}

GET /admin/api/2020-10/metafields/count.json

Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/api/2020-10/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Retrieve a count of metafields that belong to a Product resource

GET /admin/api/2020-10/products/632910392/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

GET /admin/api/2020-10/metafields/{metafield_id}.json

Retrieves a single metafield from a resource by its ID.

fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single metafield by its ID

GET /admin/api/2020-10/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "app_key",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Retrieve a single metafield by its ID

GET /admin/api/2020-10/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "produit",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

POST /admin/api/2020-10/metafields.json

Creates a new metafield for a resource.

Create a new metafield for a Shop resource

POST /admin/api/2020-10/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298173,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:21:02-05:00",
    "updated_at": "2020-11-04T16:21:02-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298173"
  }
}

Create a new metafield for a Product resource

POST /admin/api/2020-10/products/632910392/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298174,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:21:03-05:00",
    "updated_at": "2020-11-04T16:21:03-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298174"
  }
}

Creating a metafield without a key will fail and return an error

POST /admin/api/2020-10/metafields.json

{
  "metafield": {
    "key": null
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "namespace": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "key": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ],
    "value": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2020-10/metafields/{metafield_id}.json

Updates a metafield.

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-10/metafields/721389482.json

{
  "metafield": {
    "id": 721389482,
    "value": "something new",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "something new",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:05-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2020-10/products/632910392/metafields/845366454.json

{
  "metafield": {
    "id": 845366454,
    "value": "titre",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "titre",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:06-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

DELETE /admin/api/2020-10/metafields/{metafield_id}.json

Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/api/2020-10/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/api/2020-10/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
}

Version 2021-01 (Release candidate)

Resources that can have metafields

Metafields can be added to the following resources:

Type of resource	Location of metafields
Article	`/admin/blogs/#{id}/articles/#{id}/metafields.json`
Blog	`/admin/blogs/#{id}/metafields.json`
CustomCollection and SmartCollection	`/admin/collections/#{id}/metafields.json`
Customer	`/admin/customers/#{id}/metafields.json`
Draft Order	`/admin/draft_orders/#{id}/metafields.json`
Order	`/admin/orders/#{id}/metafields.json`
Page	`/admin/pages/#{id}/metafields.json`
Product	`/admin/products/#{id}/metafields.json`
Product Variant	`/admin/products/#{id}/variants/#{id}/metafields.json`
Product Image	`/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image` This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.
Shop	`/admin/metafields.json`

What you can do with Metafield

The Shopify API lets you do the following with the Metafield resource. More detailed versions of these general actions may be available:

GET /admin/api/2021-01/metafields.json Retrieves a list of metafields that belong to a resource
GET /admin/api/2021-01/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image Retrieves a list of metafields that belong to a Product Image resource
GET /admin/api/2021-01/metafields/count.json Retrieves a count of a resource's metafields
GET /admin/api/2021-01/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
POST /admin/api/2021-01/metafields.json Creates a new metafield for a resource
PUT /admin/api/2021-01/metafields/{metafield_id}.json Updates a metafield
DELETE /admin/api/2021-01/metafields/{metafield_id}.json Deletes a metafield by its ID

Metafield properties

created_at read-only	`"created_at": "2012-03-13T16:09:54-04:00"` The date and time (ISO 8601 format) when the metafield was created.
updated_at read-only	`"updated_at": "2012-08-24T14:02:15-04:00"` The date and time (ISO 8601 format) when the metafield was last updated.
description	`"description": null` A description of the information that the metafield contains.
id read-only	`"id": 915396206` The unique ID of the metafield.
key required	`"key": "warehouse"` The name of the metafield. Maximum length: 30 characters.
namespace required	`"namespace": "inventory"` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.
owner_id	`"owner_id": 690933842` The unique ID of the resource that the metafield is attached to.
owner_resource	`"owner_resource": "product"` The type of resource that the metafield is attached to.
value required	`"value": 25` The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to `tags` and key is equal to `alt`.
value_type required	`"value_type": "integer"` The metafield's information type. Valid values: `string`, `integer`, `json_string`.

Endpoints

GET /admin/api/2021-01/metafields.json

limit	Amount of results (default: `50`, maximum: `250`)
since_id	Restrict results to after the specified ID
created_at_min	Show metafields created after date (format: 2014-04-25T16:15:47-04:00)
created_at_max	Show metafields created before date (format: 2014-04-25T16:15:47-04:00)
updated_at_min	Show metafields last updated after date (format: 2014-04-25T16:15:47-04:00)
updated_at_max	Show metafields last updated before date (format: 2014-04-25T16:15:47-04:00)
namespace	Show metafields with given namespace
key	Show metafields with given key
value_type	string: Show only metafields with string value types integer: Show only metafields with integer value types
fields	comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/api/2021-01/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 721389482,
      "namespace": "affiliates",
      "key": "app_key",
      "value": "app_key",
      "value_type": "string",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
    }
  ]
}

Retrieve metafields after the specified ID that belong to a Shop resource

GET /admin/api/2021-01/metafields.json?since_id=721389482

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298172,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:20:56-05:00",
      "updated_at": "2020-11-04T16:20:56-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298172"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/2021-01/products/632910392/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 845366454,
      "namespace": "translations",
      "key": "title_fr",
      "value": "produit",
      "value_type": "string",
      "description": "French product title",
      "owner_id": 632910392,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}

GET /admin/api/2021-01/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

Retrieves a list of metafields that belong to a Product Image resource.

Retrieve a list of metafields that belong to a Product Image resource

GET /admin/api/2021-01/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 625663657,
      "namespace": "translation",
      "key": "title_fr",
      "value": "tbn",
      "value_type": "string",
      "description": "French product image title",
      "owner_id": 850703190,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}

GET /admin/api/2021-01/metafields/count.json

Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/api/2021-01/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Retrieve a count of metafields that belong to a Product resource

GET /admin/api/2021-01/products/632910392/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

GET /admin/api/2021-01/metafields/{metafield_id}.json

Retrieves a single metafield from a resource by its ID.

fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single metafield by its ID

GET /admin/api/2021-01/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "app_key",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Retrieve a single metafield by its ID

GET /admin/api/2021-01/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "produit",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

POST /admin/api/2021-01/metafields.json

Creates a new metafield for a resource.

Create a new metafield for a Shop resource

POST /admin/api/2021-01/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298173,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:21:02-05:00",
    "updated_at": "2020-11-04T16:21:02-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298173"
  }
}

Create a new metafield for a Product resource

POST /admin/api/2021-01/products/632910392/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298174,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:21:03-05:00",
    "updated_at": "2020-11-04T16:21:03-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298174"
  }
}

Creating a metafield without a key will fail and return an error

POST /admin/api/2021-01/metafields.json

{
  "metafield": {
    "key": null
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "namespace": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "key": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ],
    "value": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/2021-01/metafields/{metafield_id}.json

Updates a metafield.

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2021-01/metafields/721389482.json

{
  "metafield": {
    "id": 721389482,
    "value": "something new",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "something new",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:05-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/2021-01/products/632910392/metafields/845366454.json

{
  "metafield": {
    "id": 845366454,
    "value": "titre",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "titre",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:06-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

DELETE /admin/api/2021-01/metafields/{metafield_id}.json

Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/api/2021-01/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/api/2021-01/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
}

Version unstable

Resources that can have metafields

Metafields can be added to the following resources:

Type of resource	Location of metafields
Article	`/admin/blogs/#{id}/articles/#{id}/metafields.json`
Blog	`/admin/blogs/#{id}/metafields.json`
CustomCollection and SmartCollection	`/admin/collections/#{id}/metafields.json`
Customer	`/admin/customers/#{id}/metafields.json`
Draft Order	`/admin/draft_orders/#{id}/metafields.json`
Order	`/admin/orders/#{id}/metafields.json`
Page	`/admin/pages/#{id}/metafields.json`
Product	`/admin/products/#{id}/metafields.json`
Product Variant	`/admin/products/#{id}/variants/#{id}/metafields.json`
Product Image	`/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image` This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.
Shop	`/admin/metafields.json`

What you can do with Metafield

The Shopify API lets you do the following with the Metafield resource. More detailed versions of these general actions may be available:

GET /admin/api/unstable/metafields.json Retrieves a list of metafields that belong to a resource
GET /admin/api/unstable/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image Retrieves a list of metafields that belong to a Product Image resource
GET /admin/api/unstable/metafields/count.json Retrieves a count of a resource's metafields
GET /admin/api/unstable/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
POST /admin/api/unstable/metafields.json Creates a new metafield for a resource
PUT /admin/api/unstable/metafields/{metafield_id}.json Updates a metafield
DELETE /admin/api/unstable/metafields/{metafield_id}.json Deletes a metafield by its ID

Metafield properties

created_at read-only	`"created_at": "2012-03-13T16:09:54-04:00"` The date and time (ISO 8601 format) when the metafield was created.
updated_at read-only	`"updated_at": "2012-08-24T14:02:15-04:00"` The date and time (ISO 8601 format) when the metafield was last updated.
description	`"description": null` A description of the information that the metafield contains.
id read-only	`"id": 915396206` The unique ID of the metafield.
key required	`"key": "warehouse"` The name of the metafield. Maximum length: 30 characters.
namespace required	`"namespace": "inventory"` A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.
owner_id	`"owner_id": 690933842` The unique ID of the resource that the metafield is attached to.
owner_resource	`"owner_resource": "product"` The type of resource that the metafield is attached to.
value required	`"value": 25` The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to `tags` and key is equal to `alt`.
value_type required	`"value_type": "integer"` The metafield's information type. Valid values: `string`, `integer`, `json_string`.

Endpoints

GET /admin/api/unstable/metafields.json

limit	Amount of results (default: `50`, maximum: `250`)
since_id	Restrict results to after the specified ID
created_at_min	Show metafields created after date (format: 2014-04-25T16:15:47-04:00)
created_at_max	Show metafields created before date (format: 2014-04-25T16:15:47-04:00)
updated_at_min	Show metafields last updated after date (format: 2014-04-25T16:15:47-04:00)
updated_at_max	Show metafields last updated before date (format: 2014-04-25T16:15:47-04:00)
namespace	Show metafields with given namespace
key	Show metafields with given key
value_type	string: Show only metafields with string value types integer: Show only metafields with integer value types
fields	comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/api/unstable/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 721389482,
      "namespace": "affiliates",
      "key": "app_key",
      "value": "app_key",
      "value_type": "string",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
    }
  ]
}

Retrieve metafields after the specified ID that belong to a Shop resource

GET /admin/api/unstable/metafields.json?since_id=721389482

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298172,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-11-04T16:20:56-05:00",
      "updated_at": "2020-11-04T16:20:56-05:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298172"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/unstable/products/632910392/metafields.json

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 845366454,
      "namespace": "translations",
      "key": "title_fr",
      "value": "produit",
      "value_type": "string",
      "description": "French product title",
      "owner_id": 632910392,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}

GET /admin/api/unstable/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

Retrieves a list of metafields that belong to a Product Image resource.

Retrieve a list of metafields that belong to a Product Image resource

GET /admin/api/unstable/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View Response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 625663657,
      "namespace": "translation",
      "key": "title_fr",
      "value": "tbn",
      "value_type": "string",
      "description": "French product image title",
      "owner_id": 850703190,
      "created_at": "2020-11-04T16:18:59-05:00",
      "updated_at": "2020-11-04T16:18:59-05:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}

GET /admin/api/unstable/metafields/count.json

Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/api/unstable/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

Retrieve a count of metafields that belong to a Product resource

GET /admin/api/unstable/products/632910392/metafields/count.json

View Response

HTTP/1.1 200 OK
{
  "count": 1
}

GET /admin/api/unstable/metafields/{metafield_id}.json

Retrieves a single metafield from a resource by its ID.

fields

Show only certain fields, specified by a comma-separated list of field names.

Retrieve a single metafield by its ID

GET /admin/api/unstable/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "app_key",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Retrieve a single metafield by its ID

GET /admin/api/unstable/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "produit",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:18:59-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

POST /admin/api/unstable/metafields.json

Creates a new metafield for a resource.

Create a new metafield for a Shop resource

POST /admin/api/unstable/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298173,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:21:02-05:00",
    "updated_at": "2020-11-04T16:21:02-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298173"
  }
}

Create a new metafield for a Product resource

POST /admin/api/unstable/products/632910392/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View Response

HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298174,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:21:03-05:00",
    "updated_at": "2020-11-04T16:21:03-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298174"
  }
}

Creating a metafield without a key will fail and return an error

POST /admin/api/unstable/metafields.json

{
  "metafield": {
    "key": null
  }
}

View Response

HTTP/1.1 422 Unprocessable Entity
{
  "errors": {
    "namespace": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "key": [
      "can't be blank",
      "is too short (minimum is 3 characters)"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ],
    "value": [
      "can't be blank"
    ]
  }
}

PUT /admin/api/unstable/metafields/{metafield_id}.json

Updates a metafield.

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/unstable/metafields/721389482.json

{
  "metafield": {
    "id": 721389482,
    "value": "something new",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 721389482,
    "namespace": "affiliates",
    "key": "app_key",
    "value": "something new",
    "value_type": "string",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:05-05:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/721389482"
  }
}

Update a metafield. The namespace and key of an existing metafield can't be changed.

PUT /admin/api/unstable/products/632910392/metafields/845366454.json

{
  "metafield": {
    "id": 845366454,
    "value": "titre",
    "value_type": "string"
  }
}

View Response

HTTP/1.1 200 OK
{
  "metafield": {
    "id": 845366454,
    "namespace": "translations",
    "key": "title_fr",
    "value": "titre",
    "value_type": "string",
    "description": "French product title",
    "owner_id": 632910392,
    "created_at": "2020-11-04T16:18:59-05:00",
    "updated_at": "2020-11-04T16:21:06-05:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}

DELETE /admin/api/unstable/metafields/{metafield_id}.json

Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/api/unstable/metafields/721389482.json

View Response

HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/api/unstable/products/632910392/metafields/845366454.json

View Response

HTTP/1.1 200 OK
{
}