Metafield

Version 2019-04

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:

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/2019-04/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)
page
deprecated

The page of results to show.

(default: 1)
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/2019-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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/2019-04/metafields.json?since_id=721389482
View Response 
HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298210,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-06-29T12:00:47-04:00",
      "updated_at": "2020-06-29T12:00:47-04:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298210"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/api/2019-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}
GET /admin/api/2019-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}
GET /admin/api/2019-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/2019-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}
POST /admin/api/2019-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": 1063298212,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-06-29T12:00:56-04:00",
    "updated_at": "2020-06-29T12:00:56-04:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298212"
  }
}

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": 1063298213,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-06-29T12:00:57-04:00",
    "updated_at": "2020-06-29T12:00:57-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298213"
  }
}

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": [
      "can't be blank"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ]
  }
}
PUT /admin/api/2019-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:00:59-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:01:00-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}
DELETE /admin/api/2019-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 2019-07

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:

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/2019-07/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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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": 1063298211,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-06-29T12:00:50-04:00",
      "updated_at": "2020-06-29T12:00:50-04:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298211"
    }
  ]
}

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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}
GET /admin/api/2019-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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}
GET /admin/api/2019-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-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/2019-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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}
POST /admin/api/2019-07/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": 1063298212,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-06-29T12:00:56-04:00",
    "updated_at": "2020-06-29T12:00:56-04:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298212"
  }
}

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": 1063298213,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-06-29T12:00:57-04:00",
    "updated_at": "2020-06-29T12:00:57-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298213"
  }
}

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": [
      "can't be blank"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ]
  }
}
PUT /admin/api/2019-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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:00:59-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:01:00-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}
DELETE /admin/api/2019-07/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 2019-10

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:

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/2019-10/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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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": 1063298211,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-06-29T12:00:50-04:00",
      "updated_at": "2020-06-29T12:00:50-04:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298211"
    }
  ]
}

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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04:00",
      "owner_resource": "product",
      "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
    }
  ]
}
GET /admin/api/2019-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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04:00",
      "owner_resource": "product_image",
      "admin_graphql_api_id": "gid://shopify/Metafield/625663657"
    }
  ]
}
GET /admin/api/2019-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-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/2019-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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}
POST /admin/api/2019-10/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": 1063298212,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-06-29T12:00:56-04:00",
    "updated_at": "2020-06-29T12:00:56-04:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298212"
  }
}

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": 1063298213,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-06-29T12:00:57-04:00",
    "updated_at": "2020-06-29T12:00:57-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298213"
  }
}

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": [
      "can't be blank"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ]
  }
}
PUT /admin/api/2019-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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:00:59-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:01:00-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/845366454"
  }
}
DELETE /admin/api/2019-10/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-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:

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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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": 1063298211,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-06-29T12:00:50-04:00",
      "updated_at": "2020-06-29T12:00:50-04:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298211"
    }
  ]
}

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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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-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-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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-04/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298212,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-06-29T12:00:56-04:00",
    "updated_at": "2020-06-29T12:00:56-04:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298212"
  }
}

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": 1063298213,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-06-29T12:00:57-04:00",
    "updated_at": "2020-06-29T12:00:57-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298213"
  }
}

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": [
      "can't be blank"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ]
  }
}
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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:00:59-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:01:00-04: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-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-04 (Latest)

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:

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
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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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": 1063298211,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-06-29T12:00:50-04:00",
      "updated_at": "2020-06-29T12:00:50-04:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298211"
    }
  ]
}

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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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": 1063298212,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-06-29T12:00:56-04:00",
    "updated_at": "2020-06-29T12:00:56-04:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298212"
  }
}

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": 1063298213,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-06-29T12:00:57-04:00",
    "updated_at": "2020-06-29T12:00:57-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298213"
  }
}

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": [
      "can't be blank"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ]
  }
}
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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:00:59-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:01:00-04: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 (Release candidate)

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:

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
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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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": 1063298211,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2020-06-29T12:00:50-04:00",
      "updated_at": "2020-06-29T12:00:50-04:00",
      "owner_resource": "shop",
      "admin_graphql_api_id": "gid://shopify/Metafield/1063298211"
    }
  ]
}

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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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-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-06-29T11:36:40-04:00",
      "updated_at": "2020-06-29T11:36:40-04: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-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-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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T11:36:40-04: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-04/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response 
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298212,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2020-06-29T12:00:56-04:00",
    "updated_at": "2020-06-29T12:00:56-04:00",
    "owner_resource": "shop",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298212"
  }
}

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": 1063298213,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2020-06-29T12:00:57-04:00",
    "updated_at": "2020-06-29T12:00:57-04:00",
    "owner_resource": "product",
    "admin_graphql_api_id": "gid://shopify/Metafield/1063298213"
  }
}

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": [
      "can't be blank"
    ],
    "value_type": [
      "can't be blank",
      "is not included in the list"
    ]
  }
}
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-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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:00:59-04: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-06-29T11:36:40-04:00",
    "updated_at": "2020-06-29T12:01:00-04: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-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
{
}