Your safety is important to us. If you notice any suspicious emails that appear to come from Shopify, please forward them to safety@shopify.com. Visit the Help Center page on phishing for more information.

Metafield

Metafields allow you to attach metadata, which is additional information, to a store's resources.

Metafields can be added to the following resources:

Type of resource Location of metafields
Articles /admin/blogs/#{id}/articles/#{id}/metafields.json
Blogs /admin/blogs/#{id}/metafields.json
Collections /admin/collections/#{id}/metafields.json
Customers /admin/customers/#{id}/metafields.json
Draft orders /admin/draft_orders/#{id}/metafields.json
Orders /admin/orders/#{id}/metafields.json
Pages /admin/pages/#{id}/metafields.json
Products /admin/products/#{id}/metafields.json
Product variants /admin/products/#{id}/variants/#{id}/metafields.json
Shop /admin/metafields.json
Smart collections /admin/collections/#{id}/metafields.json

Metafields have four required properties: key, namespace, value and value_type.

Metafields have various use cases. For example, they can be used to further describe products or to store a "teaser" or "summary" for a blog post. You can also use metafields to share information between multiple Shopify applications.

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 when the metafield was created. The API returns this value in ISO 8601 format.

description
"description": null

Additional information about the metafield. This property is optional.

id
"id": 915396206

Unique numeric identifier for the metafield.

key
"key": "warehouse"

Identifier for the metafield (maximum of 30 characters).

namespace
"namespace": "inventory"

Container for a set of metafields. You need to define a custom namespace for your metafields to distinguish them from metafields used by other apps (maximum of 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
"value": 25

Information to be stored as metadata.

value_type
"value_type": "integer"

States whether the information in the value is stored as a 'string' or 'integer.'

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

The date and time when the metafield was published. The API returns this value in ISO 8601 format.

Endpoints

GET /admin/metafields.json
Get metafields that belong to a store
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

Get all metafields after the specified ID

GET /admin/metafields.json?since_id=721389482
View Response
HTTP/1.1 200 OK
{
  "metafields": [
    {
      "id": 915396087,
      "namespace": "inventory",
      "key": "warehouse",
      "value": 25,
      "value_type": "integer",
      "description": null,
      "owner_id": 690933842,
      "created_at": "2017-03-07T17:16:51-05:00",
      "updated_at": "2017-03-07T17:16:51-05:00",
      "owner_resource": "shop"
    }
  ]
}

Get all metafields that belong to a store

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": "2017-03-07T17:16:11-05:00",
      "updated_at": "2017-03-07T17:16:11-05:00",
      "owner_resource": "shop"
    }
  ]
}
GET /admin/products/632910392/metafields.json
Get metafields that belong to a product

Get all metafields that belong to a product

GET /admin/products/#{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": "2017-03-07T17:16:11-05:00",
      "updated_at": "2017-03-07T17:16:11-05:00",
      "owner_resource": "product"
    }
  ]
}
GET /admin/metafields.json
Get metafields that belong to a product image

Get all metafields that belong to the images of a product

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": "2017-03-07T17:16:11-05:00",
      "updated_at": "2017-03-07T17:16:11-05:00",
      "owner_resource": "product_image"
    }
  ]
}
GET /admin/metafields/count.json
Get a count of metafields that belong to a store

Get a count of all metafields for a store

GET /admin/metafields/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/products/632910392/metafields/count.json
Get a count of metafields that belong to a product

Get a count of all metafields that belong to a product

GET /admin/products/#{id}/metafields/count.json
View Response
HTTP/1.1 200 OK
{
  "count": 1
}
GET /admin/metafields/721389482.json
Get a single store metafield by its ID
fields

comma-separated list of fields to include in the response

Get a single store metafield by ID. A metafield belonging to any resource can be found this way.

GET /admin/metafields/#{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": "2017-03-07T17:16:11-05:00",
    "updated_at": "2017-03-07T17:16:11-05:00",
    "owner_resource": "shop"
  }
}
GET /admin/products/632910392/metafields/845366454.json
Get a single product metafield by its ID

Get a single product metafield using the metafield's nested resource path

GET /admin/products/#{id}/metafields/#{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": "2017-03-07T17:16:11-05:00",
    "updated_at": "2017-03-07T17:16:11-05:00",
    "owner_resource": "product"
  }
}
POST /admin/metafields.json
Create a new metafield for a store

Create a new metafield for a store.

POST /admin/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 915396088,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2017-03-07T17:16:51-05:00",
    "updated_at": "2017-03-07T17:16:51-05:00",
    "owner_resource": "shop"
  }
}

Trying to create a metafield without a key will 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 store.

POST /admin/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 915396084,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 690933842,
    "created_at": "2017-02-27T17:52:42-05:00",
    "updated_at": "2017-02-27T17:52:42-05:00",
    "owner_resource": "shop"
  }
}
POST /admin/products/632910392/metafields.json
Create a new metafield for a product

Create a new metafield for a product.

POST /admin/products/#{id}/metafields.json
{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}
View Response
HTTP/1.1 201 Created
{
  "metafield": {
    "id": 915396086,
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer",
    "description": null,
    "owner_id": 632910392,
    "created_at": "2017-03-07T17:16:46-05:00",
    "updated_at": "2017-03-07T17:16:46-05:00",
    "owner_resource": "product"
  }
}
PUT /admin/metafields/721389482.json
Update a store metafield

Update an existing store metafield. A metafield belonging to any resource can be updated this way. Namespace and key of an existing metafield cannot be changed.

PUT /admin/metafields/#{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": "2017-03-07T17:16:11-05:00",
    "updated_at": "2017-03-07T17:16:49-05:00",
    "owner_resource": "shop"
  }
}
PUT /admin/products/632910392/metafields/845366454.json
Update a product metafield

Update an existing metafield belonging to a product using the metafield's nested resource path. Namespace and key of an existing metafield cannot be changed.

PUT /admin/products/#{id}/metafields/#{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": "2017-03-07T17:16:11-05:00",
    "updated_at": "2017-03-07T17:16:55-05:00",
    "owner_resource": "product"
  }
}
DELETE /admin/metafields/721389482.json
Delete a store metafield

Delete an existing store metafield by id. A metafield belonging to any resource can be deleted this way.

DELETE /admin/metafields/#{id}.json
View Response
HTTP/1.1 200 OK
{}
DELETE /admin/products/632910392/metafields/845366454.json
Delete a product metafield

Delete existing metafield belonging to a product using the nested resource path.

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