Metafield

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

#

Metafields can be added to:

  • Blogs
  • Custom Collections
  • Customers
  • Orders
  • Pages
  • Products
  • Product Variants

Metafields have four required properties: a key, a namespace, a value and a value_type. The key is the identifier for a metafield. The namespace functions a a container for a set of metafields which help to distinguish between metadata that you created and metadata created by others with a similair namespace. The value is the content of the metafield. The value_type describe the state of the value, whether it is a 'string' or an 'integer.' There also exists an optional description property that provides additional information about the metafield.

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 can you 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 metadata. Namespaces help distinguish between metadata you created against metadata created by another individual with a similar namespace (maximum of 20 characters).

owner_id
{ "owner_id" : 690933842}

A unique numeric identifier for the metafield's owner.

owner_resource
{ "owner_resource" : "shop"}

Unique id for that particular resource.

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: 2008-01-01 03:00)

created_at_max

Show metafields created before date (format: 2008-01-01 03:00)

updated_at_min

Show metafields last updated after date (format: 2008-01-01 03:00)

updated_at_max

Show metafields last updated before date (format: 2008-01-01 03:00)

namepace

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 that belong to a store

GET /admin/metafields.json
View Response
HTTP/1.1 200 OK

{
  "metafields": [
    {
      "created_at": "2014-04-17T16:36:27-04:00",
      "description": null,
      "id": 721389482,
      "key": "app_key",
      "namespace": "affiliates",
      "owner_id": 690933842,
      "updated_at": "2014-04-17T16:36:27-04:00",
      "value": "app_key",
      "value_type": "string",
      "owner_resource": "shop"
    }
  ]
}

Get all metafields after the specified ID

GET /admin/metafields.json?since_id=721389482
View Response
HTTP/1.1 200 OK

{
  "metafields": [
    {
      "created_at": "2014-04-17T16:36:31-04:00",
      "description": null,
      "id": 915396092,
      "key": "warehouse",
      "namespace": "inventory",
      "owner_id": 690933842,
      "updated_at": "2014-04-17T16:36:31-04:00",
      "value": 25,
      "value_type": "integer",
      "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": [
    {
      "created_at": "2014-04-17T16:36:27-04:00",
      "description": "French product title",
      "id": 845366454,
      "key": "title_fr",
      "namespace": "translations",
      "owner_id": 632910392,
      "updated_at": "2014-04-17T16:36:27-04:00",
      "value": "produit",
      "value_type": "string",
      "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": [
    {
      "created_at": "2014-04-17T16:36:27-04:00",
      "description": "French product image title",
      "id": 625663657,
      "key": "title_fr",
      "namespace": "translation",
      "owner_id": 850703190,
      "updated_at": "2014-04-17T16:36:27-04:00",
      "value": "tbn",
      "value_type": "string",
      "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": {
    "created_at": "2014-04-17T16:36:27-04:00",
    "description": null,
    "id": 721389482,
    "key": "app_key",
    "namespace": "affiliates",
    "owner_id": 690933842,
    "updated_at": "2014-04-17T16:36:27-04:00",
    "value": "app_key",
    "value_type": "string",
    "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": {
    "created_at": "2014-04-17T16:36:27-04:00",
    "description": "French product title",
    "id": 845366454,
    "key": "title_fr",
    "namespace": "translations",
    "owner_id": 632910392,
    "updated_at": "2014-04-17T16:36:27-04:00",
    "value": "produit",
    "value_type": "string",
    "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": {
    "created_at": "2014-04-17T16:36:30-04:00",
    "description": null,
    "id": 915396091,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 690933842,
    "updated_at": "2014-04-17T16:36:30-04:00",
    "value": 25,
    "value_type": "integer",
    "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"
    ]
  }
}
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": {
    "created_at": "2014-04-17T16:36:30-04:00",
    "description": null,
    "id": 915396090,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 632910392,
    "updated_at": "2014-04-17T16:36:30-04:00",
    "value": 25,
    "value_type": "integer",
    "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": {
    "created_at": "2014-04-17T16:36:27-04:00",
    "description": null,
    "id": 721389482,
    "key": "app_key",
    "namespace": "affiliates",
    "owner_id": 690933842,
    "updated_at": "2014-04-17T16:36:32-04:00",
    "value": "something new",
    "value_type": "string",
    "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": {
    "created_at": "2014-04-17T16:36:27-04:00",
    "description": "French product title",
    "id": 845366454,
    "key": "title_fr",
    "namespace": "translations",
    "owner_id": 632910392,
    "updated_at": "2014-04-17T16:36:32-04:00",
    "value": "titre",
    "value_type": "string",
    "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

{}

Ready to put what you've learned into action?

Build an online store with Shopify Try it Free

Experience the future of retail now

Shopify Point of Sale Try it Free