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

/admin/metafields.json?metafield[owner_id]=#{id}&metafield[owner_resource]=product_image

This endpoint will let you view the metafields for a product image. To add or change product image metafields, use the product image endpoint.

Shop /admin/metafields.json

What you can do with Metafield

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

Metafield properties

created_at
"created_at": "2012-03-13T16:09:54-04:00"

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

description
"description": null

A description of the information that the metafield contains.

id
"id": 915396206

The unique ID of the metafield.

key
required
"key": "warehouse"

The name of the metafield. Maximum length: 30 characters.

namespace
required
"namespace": "inventory"

A container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from the metafields used by other apps. Maximum length: 20 characters.

owner_id
"owner_id": 690933842

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

owner_resource
"owner_resource": "product"

The type of resource that the metafield is attached to.

value
required
"value": 25

The information to be stored as metadata.

value_type
required
"value_type": "integer"

The metafield's information type. Valid values: string or integer.

updated_at
"updated_at": "2012-08-24T14:02:15-04:00"

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

Endpoints

GET /admin/metafields.json
Retrieves a list of metafields that belong to a resource.
limit

Amount of results

(default: 50) (maximum: 250)
since_id

Restrict results to after the specified ID

created_at_min

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

created_at_max

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

updated_at_min

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

updated_at_max

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

namespace

Show metafields with given namespace

key

Show metafields with given key

value_type
  • string: Show only metafields with string value types
  • integer: Show only metafields with integer value types
fields

comma-separated list of fields to include in the response

Retrieve metafields that belong to a Shop resource

GET /admin/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": "2018-05-07T15:33:38-04:00",
      "updated_at": "2018-05-07T15:33:38-04:00",
      "owner_resource": "shop"
    }
  ]
}

Retrieve a list of metafields that belong to a Product resource

GET /admin/products/#{product_id}/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": "2018-05-07T15:33:38-04:00",
      "updated_at": "2018-05-07T15:33:38-04:00",
      "owner_resource": "product"
    }
  ]
}

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

GET /admin/metafields.json?since_id=721389482
View Response
HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 1063298180,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2018-05-07T15:48:32-04:00",
      "updated_at": "2018-05-07T15:48:32-04:00",
      "owner_resource": "shop"
    }
  ]
}
GET /admin/metafields.json
Retrieves a list of metafields that belong to a Product Image resource.

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

GET /admin/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": "2018-05-07T15:33:38-04:00",
      "updated_at": "2018-05-07T15:33:38-04:00",
      "owner_resource": "product_image"
    }
  ]
}
GET /admin/metafields/count.json
Retrieves a count of a resource's metafields.

Retrieve a count of metafields that belong to a Shop resource

GET /admin/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/products/#{product_id}/metafields/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/metafields/721389482.json
Retrieves a single metafield from a resource by its ID.
fields

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

Retrieve a single metafield by its ID

GET /admin/metafields/#{metafield_id}.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": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:33:38-04:00",
    "owner_resource": "shop"
  }
}

Retrieve a single metafield by its ID

GET /admin/products/#{product_id}/metafields/#{metafield_id}.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": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:33:38-04:00",
    "owner_resource": "product"
  }
}
POST /admin/products/632910392/metafields.json
Creates a new metafield for a resource.

Create a new metafield for a Product resource

POST /admin/products/#{product_id}/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298181,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2018-05-07T15:48:34-04:00",
    "updated_at": "2018-05-07T15:48:34-04:00",
    "owner_resource": "product"
  }
}

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

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

Create a new metafield for a Shop resource

POST /admin/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 1063298182,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2018-05-07T15:48:35-04:00",
    "updated_at": "2018-05-07T15:48:35-04:00",
    "owner_resource": "shop"
  }
}
PUT /admin/metafields/721389482.json
Updates a metafield.

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

PUT /admin/metafields/#{metafield_id}.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": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:48:34-04:00",
    "owner_resource": "shop"
  }
}

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

PUT /admin/products/#{product_id}/metafields/#{metafield_id}.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": "2018-05-07T15:33:38-04:00",
    "updated_at": "2018-05-07T15:48:34-04:00",
    "owner_resource": "product"
  }
}
DELETE /admin/metafields/721389482.json
Deletes a metafield by its ID.

Delete a metafield by its ID

DELETE /admin/metafields/#{metafield_id}.json
View Response
HTTP/1.1 200 OK
{
}

Delete a metafield by its ID

DELETE /admin/products/#{product_id}/metafields/#{metafield_id}.json
View Response
HTTP/1.1 200 OK
{
}