The REST Admin API is a legacy API as of October 1, 2024. All apps and integrations should be built with the GraphQL Admin API. For details and migration steps, visit our migration guide.

Anchor to section titled 'undefined'

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?
Anchor to section titled 'The Metafield resource'

The Metafield resource

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 section titled '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 section titled 'Parameters of Create a metafield'

Parameters

api_version
string
required
blog_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Create a metafield'

Examples

Path parameters
blogid=382285388
string
required
Request body
metafield
Metafield resource
Was this section helpful?
post
/admin/api/2024-10/blogs/382285388/metafields.json
Copy
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/2024-10/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": 1069228950,
    "namespace": "my_fields",
    "key": "sponsor",
    "value": "Shopify",
    "description": null,
    "owner_id": 382285388,
    "created_at": "2024-09-26T15:28:36-04:00",
    "updated_at": "2024-09-26T15:28:36-04:00",
    "owner_resource": "blog",
    "type": "single_line_text_field",
    "admin_graphql_api_id": "gid://shopify/Metafield/1069228950"
  }
}
Anchor to section titled '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 section titled 'Parameters of Retrieve a list of metafields from the resource's endpoint'

Parameters

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 section titled 'Examples of Retrieve a list of metafields from the resource's endpoint'

Examples

Path parameters
blogid=382285388
string
required
Was this section helpful?
get
/admin/api/2024-10/blogs/382285388/metafields.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/blogs/382285388/metafields.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1069228941,
      "namespace": "my_fields",
      "key": "sponsor",
      "value": "Shopify",
      "description": null,
      "owner_id": 382285388,
      "created_at": "2024-09-26T15:28:18-04:00",
      "updated_at": "2024-09-26T15:28:18-04:00",
      "owner_resource": "blog",
      "type": "single_line_text_field",
      "admin_graphql_api_id": "gid://shopify/Metafield/1069228941"
    }
  ]
}
Anchor to section titled '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 section titled 'Parameters of Retrieve a specific metafield'

Parameters

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 section titled 'Examples of Retrieve a specific metafield'

Examples

Was this section helpful?
get
/admin/api/2024-10/blogs/382285388/metafields/534526895.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/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": "2024-09-26T15:08:21-04:00",
    "updated_at": "2024-09-26T15:08:21-04:00",
    "owner_resource": "blog",
    "type": "single_line_text_field",
    "admin_graphql_api_id": "gid://shopify/Metafield/534526895"
  }
}
Anchor to section titled '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 section titled '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 section titled 'Examples of Retrieve a count of a resource's metafields.'

Examples

Path parameters
blogid=382285388
string
required
Was this section helpful?
get
/admin/api/2024-10/blogs/382285388/metafields/count.json
Copy
curl -X GET "https://your-development-store.myshopify.com/admin/api/2024-10/blogs/382285388/metafields/count.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{
  "count": 0
}
Anchor to section titled '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 section titled 'Parameters of Updates a metafield'

Parameters

api_version
string
required
blog_id
string
required
metafield_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Updates a metafield'

Examples

Request body
metafield
Metafield resource
Was this section helpful?
put
/admin/api/2024-10/blogs/382285388/metafields/534526895.json
Copy
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/2024-10/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": "2024-09-26T15:08:21-04:00",
    "updated_at": "2024-09-26T15:28:32-04:00",
    "owner_resource": "blog",
    "type": "single_line_text_field",
    "admin_graphql_api_id": "gid://shopify/Metafield/534526895"
  }
}
Anchor to section titled 'DELETE request, Deletes a metafield by its ID'

del
Deletes a metafield by its ID

metafieldsDelete
Deletes a metafield by its ID.
Anchor to section titled 'Parameters of Deletes a metafield by its ID'

Parameters

api_version
string
required
blog_id
string
required
metafield_id
string
required
Was this section helpful?
Anchor to section titled 'Examples of Deletes a metafield by its ID'

Examples

Was this section helpful?
del
/admin/api/2024-10/blogs/382285388/metafields/534526895.json
Copy
curl -X DELETE "https://your-development-store.myshopify.com/admin/api/2024-10/blogs/382285388/metafields/534526895.json" \
-H "X-Shopify-Access-Token: {access_token}"
{}Response
JSON
HTTP/1.1 200 OK
{}