Metafield
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 |
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/2019-10/metafields.json Retrieves a list of metafields that belong to a resource
- 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
- GET /admin/api/2019-10/metafields/count.json Retrieves a count of a resource's metafields
- GET /admin/api/2019-10/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
- POST /admin/api/2019-10/metafields.json Creates a new metafield for a resource
- PUT /admin/api/2019-10/metafields/{metafield_id}.json Updates a metafield
- DELETE /admin/api/2019-10/metafields/{metafield_id}.json Deletes a metafield by its ID
Metafield properties
created_at
read-only |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
fields
|
comma-separated list of fields to include in the response |
Retrieve metafields that belong to a Shop resource
GET /admin/api/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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/2019-10/metafields.json?since_id=721389482
View Response
HTTP/1.1 200 OK
{
"metafields": [
{
"id": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
Retrieve a list of metafields that belong to a Product resource
GET /admin/api/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
Retrieve a list of metafields that belong to a Product Image resource
GET /admin/api/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
Retrieve a count of metafields that belong to a Shop resource
GET /admin/api/2019-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/2019-10/products/632910392/metafields/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
fields
|
Show only certain fields, specified by a comma-separated list of field names. |
Retrieve a single metafield by its ID
GET /admin/api/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/721389482"
}
}
Retrieve a single metafield by its ID
GET /admin/api/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
Create a new metafield for a Shop resource
POST /admin/api/2019-10/metafields.json
{
"metafield": {
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer"
}
}
View Response
HTTP/1.1 201 Created
{
"metafield": {
"id": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
Create a new metafield for a Product resource
POST /admin/api/2019-10/products/632910392/metafields.json
{
"metafield": {
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer"
}
}
View Response
HTTP/1.1 201 Created
{
"metafield": {
"id": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
Update a metafield. The namespace and key of an existing metafield can't be changed.
PUT /admin/api/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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/2019-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:08-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
Delete a metafield by its ID
DELETE /admin/api/2019-10/metafields/721389482.json
View Response
HTTP/1.1 200 OK
{
}
Delete a metafield by its ID
DELETE /admin/api/2019-10/products/632910392/metafields/845366454.json
View Response
HTTP/1.1 200 OK
{
}
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 |
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 |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
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
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
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": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:08-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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
{
}
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 |
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 |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
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
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
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": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:08-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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
{
}
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 |
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 |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
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
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
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": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:08-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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
{
}
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 |
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 |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
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
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
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": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:08-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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
{
}
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 |
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 |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
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
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
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": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:08-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
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
{
}
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 |
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-04/metafields.json Retrieves a list of metafields that belong to a resource
- GET /admin/api/2021-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/2021-04/metafields/count.json Retrieves a count of a resource's metafields
- GET /admin/api/2021-04/metafields/{metafield_id}.json Retrieves a single metafield from a resource by its ID
- POST /admin/api/2021-04/metafields.json Creates a new metafield for a resource
- PUT /admin/api/2021-04/metafields/{metafield_id}.json Updates a metafield
- DELETE /admin/api/2021-04/metafields/{metafield_id}.json Deletes a metafield by its ID
Metafield properties
created_at
read-only |
The date and time (ISO 8601 format) when the metafield was created. |
updated_at
read-only |
The date and time (ISO 8601 format) when the metafield was last updated. |
description |
A description of the information that the metafield contains. |
id
read-only |
The unique ID of the metafield. |
key
required |
The name of the metafield. Minimum length: 3 characters. Maximum length: 30 characters. |
namespace
required |
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. Minimum length: 2 characters. Maximum length: 20 characters. |
owner_id |
The unique ID of the resource that the metafield is attached to. |
owner_resource |
The type of resource that the metafield is attached to. |
value
required |
The information to be stored as metadata. Maximum length: 512 characters when metafield namespace is equal to The maximum length of
|
value_type
required |
The metafield's information type. Valid values: |
Endpoints
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
|
|
fields
|
comma-separated list of fields to include in the response |
Retrieve metafields that belong to a Shop resource
GET /admin/api/2021-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-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-04/metafields.json?since_id=721389482
View Response
HTTP/1.1 200 OK
{
"metafields": [
{
"id": 1063298186,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:47:45-05:00",
"updated_at": "2021-02-05T22:47:45-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298186"
}
]
}
Retrieve a list of metafields that belong to a Product resource
GET /admin/api/2021-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
]
}
Retrieve a list of metafields that belong to a Product Image resource
GET /admin/api/2021-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product_image",
"admin_graphql_api_id": "gid://shopify/Metafield/625663657"
}
]
}
Retrieve a count of metafields that belong to a Shop resource
GET /admin/api/2021-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/2021-04/products/632910392/metafields/count.json
View Response
HTTP/1.1 200 OK
{
"count": 1
}
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-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/721389482"
}
}
Retrieve a single metafield by its ID
GET /admin/api/2021-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T20:59:20-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/845366454"
}
}
Create a new metafield for a Shop resource
POST /admin/api/2021-04/metafields.json
{
"metafield": {
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer"
}
}
View Response
HTTP/1.1 201 Created
{
"metafield": {
"id": 1063298187,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 690933842,
"created_at": "2021-02-05T22:48:01-05:00",
"updated_at": "2021-02-05T22:48:01-05:00",
"owner_resource": "shop",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298187"
}
}
Create a new metafield for a Product resource
POST /admin/api/2021-04/products/632910392/metafields.json
{
"metafield": {
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer"
}
}
View Response
HTTP/1.1 201 Created
{
"metafield": {
"id": 1063298188,
"namespace": "inventory",
"key": "warehouse",
"value": 25,
"value_type": "integer",
"description": null,
"owner_id": 632910392,
"created_at": "2021-02-05T22:48:03-05:00",
"updated_at": "2021-02-05T22:48:03-05:00",
"owner_resource": "product",
"admin_graphql_api_id": "gid://shopify/Metafield/1063298188"
}
}
Creating a metafield without a key will fail and return an error
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"
]
}
}
Update a metafield. The namespace and key of an existing metafield can't be changed.
PUT /admin/api/2021-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": "2021-02-05T20:59:20-05:00",
"updated_at": "2021-02-05T22:48:06-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-04/products/632910392/metafields/845366454.json
{
"metafield": {
"id": 845366454,
"value": &q