Skip to main content

The REST Admin API is a legacy API as of October 1, 2024. Starting April 1, 2025, all new public apps must be built exclusively with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Metafield

Metafields are a flexible way to attach additional information to a Shopify resource (e.g. Product, Collection, etc.). Some examples of data stored using metafields include specifications, size charts, downloadable documents, release dates, images, or part numbers. Metafields are identified by an owner resource, a namespace, and a key and they store a value along with type information for that context.

Resources that can have metafields

Was this section helpful?
#

Endpoints

Anchor to

The Metafield resource

Anchor to

Properties

created_at
read-only
->
createdAt

The date and time (ISO 8601 format) when the metafield was created.

description
->
description

The description of the metafield.

id
read-only
->
id

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

key
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

namespace
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

owner_id
->
owner

The unique ID of the resource that the metafield is attached to.

owner_resource
->
ownerType

The type of resource that the metafield is attached to.

updated_at
read-only
->
updatedAt

The date and time (ISO 8601 format) when the metafield was last updated.

value
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

type
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

Was this section helpful?
{}

The Metafield resource

{
"created_at": "2012-03-13T16:09:54-04:00",
"description": "The number of units at the warehouse.",
"id": 915396206,
"key": "warehouse",
"namespace": "inventory",
"owner_id": 548380009,
"owner_resource": "product",
"updated_at": "2012-08-24T14:02:15-04:00",
"value": "25",
"type": "single_line_text_field"
}

Anchor to POST request, Create a metafield
post
Create a metafield

metafieldsSet

You can create any number of metafields for a resource. To create metafields, use the corresponding resource's endpoint as listed on the examples.

Anchor to Parameters of Create a metafieldParameters

api_version
string
required
blog_id
string
required
Was this section helpful?

Anchor to post-blogs-blog-id-metafields-examplesExamples

Create a metafield for a blog

Path parameters
blog_id=382285388
string
required
Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"sponsor"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"Shopify"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for a collection

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"discount"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"25%"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for a customer

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"discounts"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"special"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.value:"yes"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

Create a metafield for a draft order

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"purchase_order"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"97453"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for a page

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"subtitle"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"A subtitle for my page"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for a product

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"inventory"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"warehouse"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.value:25
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"number_integer"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

Create a metafield for a product image

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"translation"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"title_spanish"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"botas"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for a product variant

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"liner_material"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"synthetic leather"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for an article

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"category"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"outdoors"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for an order

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"purchase_order"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.type:"single_line_text_field"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

metafield.value:"123"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

Create a metafield for the Shop resource

Request body
metafield
Metafield resource
Show metafield properties
metafield.namespace:"my_fields"
->
namespace

The container for a group of metafields that the metafield is or will be associated with. Used in tandem with key to lookup a metafield on a resource, preventing conflicts with other metafields with the same key.
Must be 3-255 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.key:"my_items"
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

metafield.value:"{\"items\":[\"some item\"]}"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"json"
->
type

The type of data that is stored in the metafield. Refer to the list of supported types.

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

Request body
metafield
Metafield resource
Show metafield properties
metafield.key:null
->
key

The unique identifier for a metafield within its namespace.
Must be 3-64 characters long and can contain alphanumeric, hyphen, and underscore characters.

Was this section helpful?
post

/admin/api/2025-07/blogs/382285388/metafields.json

curl -d '{"metafield":{"namespace":"my_fields","key":"sponsor","type":"single_line_text_field","value":"Shopify"}}' \
-X POST "https://your-development-store.myshopify.com/admin/api/2025-07/blogs/382285388/metafields.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 201 Created
{
"metafield": {
"id": 1069228952,
"namespace": "my_fields",
"key": "sponsor",
"value": "Shopify",
"description": null,
"owner_id": 382285388,
"created_at": "2025-07-01T14:29:35-04:00",
"updated_at": "2025-07-01T14:29:35-04:00",
"owner_resource": "blog",
"type": "single_line_text_field",
"admin_graphql_api_id": "gid://shopify/Metafield/1069228952"
}
}

Anchor to GET request, Retrieve a list of metafields from the resource's endpoint
get
Retrieve a list of metafields from the resource's endpoint

product

Retrieves a list of metafields attached to a particular resource by using the resource's endpoint.

Anchor to Parameters of Retrieve a list of metafields from the resource's endpointParameters

api_version
string
required
blog_id
string
required
created_at_max

Show metafields created before date (format: 2022-02-25T16:15:47-04:00)

created_at_min

Show metafields created after date (format: 2022-02-25T16:15:47-04:00)

fields

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

key

Show metafields with given key

limit
≤ 250
default 50

The maximum number of results to show on a page.

namespace

Show metafields with given namespace

since_id

Show metafields created after the specified ID.

type

The type of data that the metafield stores in the value field. Refer to the list of supported types.

updated_at_max

Show metafields last updated before date (format: 2022-02-25T16:15:47-04:00)

updated_at_min

Show metafields last updated after date (format: 2022-02-25T16:15:47-04:00)

Was this section helpful?

Anchor to get-blogs-blog-id-metafields-examplesExamples

Retrieve metafields attached to a Blog

Path parameters
blog_id=382285388
string
required

Retrieve metafields attached to a Collection

Retrieve metafields attached to a Customer

Retrieve metafields attached to a Draft Order

Retrieve metafields attached to a Page

Retrieve metafields attached to a Product

Retrieve metafields attached to a Product Image

Retrieve metafields attached to a Product Variant

Retrieve metafields attached to an Article

Retrieve metafields attached to an Order

Retrieve metafields attached to the Shop

Retrieve metafields attached to the Shop after the specified ID

Query parameters
since_id=721389482

Show metafields created after the specified ID.

Was this section helpful?
get

/admin/api/2025-07/blogs/382285388/metafields.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/blogs/382285388/metafields.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"metafields": [
{
"id": 1069228940,
"namespace": "my_fields",
"key": "sponsor",
"value": "Shopify",
"description": null,
"owner_id": 382285388,
"created_at": "2025-07-01T14:28:43-04:00",
"updated_at": "2025-07-01T14:28:43-04:00",
"owner_resource": "blog",
"type": "single_line_text_field",
"admin_graphql_api_id": "gid://shopify/Metafield/1069228940"
}
]
}

Anchor to GET request, Retrieve a specific metafield
get
Retrieve a specific metafield

product

Retrieve a metafield by specifying the ID. All fields of a metafield are returned unless specific fields are named.

Anchor to Parameters of Retrieve a specific metafieldParameters

api_version
string
required
blog_id
string
required
metafield_id
string
required
fields

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

Was this section helpful?

Anchor to get-blogs-blog-id-metafields-metafield-id-examplesExamples

Retrieve a single metafield by its ID attached to a Blog

Retrieve a single metafield by its ID attached to a Collection

Retrieve a single metafield by its ID attached to a Customer

Retrieve a single metafield by its ID attached to a Draft Order

Retrieve a single metafield by its ID attached to a Page

Retrieve a single metafield by its ID attached to a Product

Retrieve a single metafield by its ID attached to a Product Image

Retrieve a single metafield by its ID attached to a Product Variant

Retrieve a single metafield by its ID attached to an Article

Retrieve a single metafield by its ID attached to an Order

Retrieve a single metafield by its ID attached to the Shop resource

Was this section helpful?
get

/admin/api/2025-07/blogs/382285388/metafields/534526895.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/blogs/382285388/metafields/534526895.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"metafield": {
"id": 534526895,
"namespace": "translation",
"key": "title_fr",
"value": "Le iPod",
"description": "Blog French title translation",
"owner_id": 241253187,
"created_at": "2025-07-01T14:28:21-04:00",
"updated_at": "2025-07-01T14:28:21-04:00",
"owner_resource": "blog",
"type": "single_line_text_field",
"admin_graphql_api_id": "gid://shopify/Metafield/534526895"
}
}

Anchor to GET request, Retrieve a count of a resource's metafields.
get
Retrieve a count of a resource's metafields.

metafieldDefinition

Get a count of all metafields that belong to a particular resource.

Anchor to Parameters of Retrieve a count of a resource's metafields.Parameters

api_version
string
required
blog_id
string
required
Was this section helpful?

Anchor to get-blogs-blog-id-metafields-count-examplesExamples

Retrieve a count of metafields attached to a Blog

Path parameters
blog_id=382285388
string
required

Retrieve a count of metafields attached to a Collection

Retrieve a count of metafields attached to a Customer

Retrieve a count of metafields attached to a Draft Order

Retrieve a count of metafields attached to a Page

Retrieve a count of metafields attached to a Product

Retrieve a count of metafields attached to a Product Image

Retrieve a count of metafields attached to a Product Variant

Retrieve a count of metafields attached to an Article

Retrieve a count of metafields attached to an Order

Retrieve a count of metafields attached to the Shop resource

Was this section helpful?
get

/admin/api/2025-07/blogs/382285388/metafields/count.json

curl -X GET "https://your-development-store.myshopify.com/admin/api/2025-07/blogs/382285388/metafields/count.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{
"count": 0
}

Anchor to PUT request, Updates a metafield
put
Updates a metafield

metafieldsSet

Updates a metafield. The properties that can be updated are value and type.

Anchor to Parameters of Updates a metafieldParameters

api_version
string
required
blog_id
string
required
metafield_id
string
required
Was this section helpful?

Anchor to put-blogs-blog-id-metafields-metafield-id-examplesExamples

Update a metafield for a Blog

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:534526895
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"a translated blog title"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Collection

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:1010236510
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"seo title"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Customer

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:220591908
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"yes"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Draft Order

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:106172460
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"110000"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Page

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:290519330
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"An updated translation"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Product

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:1001077698
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"having fun"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Product Image

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:625663657
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"translated description"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Product Variant

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:323119633
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"Red"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for a Shop resource

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:721389482
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"[\"something new\"]"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"list.single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for an Article

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:838981074
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"a translated title"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Update a metafield for an Order

Request body
metafield
Metafield resource
Show metafield properties
metafield.id:915396079
read-only

The unique ID of the metafield.
Required when updating a metafield, but should not be included when creating as it's created automatically.

metafield.value:"Provided a discount code"
->
value

The data stored in the metafield. Always stored as a string, regardless of the metafield's type.

metafield.type:"single_line_text_field"

The type of data that is stored in the metafield. Refer to the list of supported types.

Was this section helpful?
put

/admin/api/2025-07/blogs/382285388/metafields/534526895.json

curl -d '{"metafield":{"id":534526895,"value":"a translated blog title","type":"single_line_text_field"}}' \
-X PUT "https://your-development-store.myshopify.com/admin/api/2025-07/blogs/382285388/metafields/534526895.json" \
-H "X-Shopify-Access-Token: {access_token}" \
-H "Content-Type: application/json"

{}

Response

JSON
HTTP/1.1 200 OK
{
"metafield": {
"value": "a translated blog title",
"owner_id": 241253187,
"namespace": "translation",
"key": "title_fr",
"id": 534526895,
"description": "Blog French title translation",
"created_at": "2025-07-01T14:28:21-04:00",
"updated_at": "2025-07-01T14:28:39-04:00",
"owner_resource": "blog",
"type": "single_line_text_field",
"admin_graphql_api_id": "gid://shopify/Metafield/534526895"
}
}

Anchor to DELETE request, Deletes a metafield by its ID
del
Deletes a metafield by its ID

metafieldsDelete

Deletes a metafield by its ID.

Anchor to Parameters of Deletes a metafield by its IDParameters

api_version
string
required
blog_id
string
required
metafield_id
string
required
Was this section helpful?

Anchor to delete-blogs-blog-id-metafields-metafield-id-examplesExamples

Delete a metafield by its ID for a Blog

Delete a metafield by its ID for a Collection

Delete a metafield by its ID for a Customer

Delete a metafield by its ID for a Draft Order

Delete a metafield by its ID for a Page

Delete a metafield by its ID for a Product

Delete a metafield by its ID for a Product Image

Delete a metafield by its ID for a Product Variant

Delete a metafield by its ID for an Article

Delete a metafield by its ID for an Order

Delete a metafield by its ID for the Shop resource

Was this section helpful?
del

/admin/api/2025-07/blogs/382285388/metafields/534526895.json

curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2025-07/blogs/382285388/metafields/534526895.json" \
-H "X-Shopify-Access-Token: {access_token}"

{}

Response

JSON
HTTP/1.1 200 OK
{}