The Metafield resource allows you to add additional information to store's 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 Haravan apps.


Resources that can have metafields


Metafields can be added to the following resources:


Type of resource

Location of metafields

Page

https://apis.haravan.com/web/pages/#{id}/metafields.json

Blog

https://apis.haravan.com/web/blogs/#{id}/metafields.json

Article

https://apis.haravan.com/web/blogs/#{id}/articles/#{id}/metafields.json

CustomCollection and SmartCollection

https://apis.haravan.com/com/collections/#{id}/metafields.json

Customer

https://apis.haravan.com/com/customers/#{id}/metafields.json

Order

https://apis.haravan.com/com/orders/#{id}/metafields.json

Product

https://apis.haravan.com/com/products/#{id}/metafields.json

Product Variant

https://apis.haravan.com/com/variants/#{id}/metafields.json

Product Image

https://apis.haravan.com/com/images/#{id}/metafields.json

Shop

https://apis.haravan.com/com/metafields.json


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 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', an 'integer' or an 'json'. There also exists an optional description property that provides additional information about the metafield. 


What can you do with Metafield?


The Haravan 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": "2021-11-30T08:40:33.594Z" } read-only

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

updated_at

{ "updated_at": "2021-12-13T06:32:35.731Z" } read-only

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

description

{ "description" : "abc" } optional

Additional information about the metafield.

id

{ "id" : 915396206 } read-only

The unique ID of the metafield.

key

{ "key" : "warehouse" }

The name of the metafield. Minimum length: 3 characters. Maximum length: 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. Minimum length: 2 characters. 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" : "shop" }

The type of resource that the metafield is attached to.

value

{ "value" : "25" }

Information to be stored as metadata.

Minimum length: 1 characters. Maximum length: 80000 characters.

value_type

{ "value_type" : "integer" }

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


Metafield types

Each metafield and metafield definition has a value_type, which defines the type of information that it can store.

When using the API to read and write metafields, the value is always entered and stored as a string, regardless of value_type.

Metafields and definitions can have the following value types:

Value type

Description

Example value

string

A text field.

{"value": "This item contains dairy products."}

integer

A whole number in the range of +/-9,007,199,254,740,991.

{"value": "10"}

json

A JSON-formatted string.

{"value": "{\"price\":10000,\"stock\":\"instock\",\"meta\":[{\"k\":\"v1\"},{\"k\":\"v2\"}]}"}


Endpoints

GET   https://apis.haravan.com/com/metafields.json

Get metafields that belong to a store.

page

Page to show the result.

limit

Amount of results. (default: 50) (maximum: 50)

since_id

Restrict results to after the specified ID

created_at_min

Show metafields created after date (format: 2021-11-30T08:40:33.594Z)

created_at_max

Show metafields created before date (format: 2021-11-30T08:40:33.594Z)

updated_at_min

Show metafields last updated after date (format: 2021-11-30T08:40:33.594Z)

updated_at_max

Show metafields last updated before date (format: 2021-11-30T08:40:33.594Z)

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

json : Show only metafields with json value types

fields

comma-separated list of fields to include in the response

Get all metafields that belong to a store

GET https://apis.haravan.com/com/metafields.json

View response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "created_at": "2021-11-30T08:40:33.594Z",
      "description": null,
      "id": 721389482,
      "key": "Wash",
      "namespace": "instructions",
      "owner_id": 690933842,
      "updated_at": "2021-12-13T06:32:35.731Z",
      "value": "Cold",
      "value_type": "string",
      "owner_resource": "shop"
    }
  ]
}

Get all metafields after the specified ID

GET https://apis.haravan.com/com/metafields.json?since_id=721389482

View response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "created_at": "2021-12-15T10:37:38.363Z",
      "description": null,
      "id": 996577826,
      "key": "warehouse",
      "namespace": "inventory",
      "owner_id": 690933842,
      "updated_at": "2021-12-15T10:38:37.54Z",
      "value": 25,
      "value_type": "integer",
      "owner_resource": "shop"
    }
  ]
}
GET   https://apis.haravan.com/com/products/#{id}/metafields.json

Get metafields that belong to a product.

Get all metafields that belong to a product.

GET https://apis.haravan.com/com/products/632910392/metafields.json

View response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "created_at": "2021-11-30T08:40:33.594Z",
      "description": "French product title",
      "id": 845366454,
      "key": "title_fr",
      "namespace": "translations",
      "owner_id": 632910392,
      "updated_at": "2021-12-13T06:32:35.731Z",
      "value": "produit",
      "value_type": "string",
      "owner_resource": "product"
    }
  ]
}
GET   https://apis.haravan.com/com/metafields.json

Get metafields that belong to a product image.

Get all metafields that belong to the images of a product.

GET https://apis.haravan.com/com/metafields.json?metafield[owner_id]=850703190&metafield[owner_resource]=product_image

View response

HTTP/1.1 200 OK
{
  "metafields": [
    {
      "created_at": "2021-11-30T08:40:33.594Z",
      "description": "French product image title",
      "id": 625663657,
      "key": "title_fr",
      "namespace": "translation",
      "owner_id": 850703190,
      "updated_at": "2021-12-13T06:32:35.731Z",
      "value": "tbn",
      "value_type": "string",
      "owner_resource": "product_image"
    }
  ]
}
GET   https://apis.haravan.com/com/metafields/count.json

Get a count of metafields that belong to a store.

Get a count of all metafields for a store.

GET https://apis.haravan.com/com/metafields/count.json

View response

HTTP/1.1 200 OK
{
  "count": 1
}
GET   https://apis.haravan.com/com/products/#{id}/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 https://apis.haravan.com/com/products/632910392/metafields/count.json

View response

HTTP/1.1 200 OK
{
  "count": 1
}
GET   https://apis.haravan.com/com/metafields/#{id}.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 https://apis.haravan.com/com/metafields/721389482.json

View response

HTTP/1.1 200 OK
{
  "metafield": {
    "created_at": "2021-11-30T08:40:33.594Z",
    "description": null,
    "id": 721389482,
    "key": "app_key",
    "namespace": "affiliates",
    "owner_id": 690933842,
    "updated_at": "2021-12-13T06:32:35.731Z",
    "value": "app_key",
    "value_type": "string",
    "owner_resource": "shop"
  }
}
GET   https://apis.haravan.com/com/products/#{id}/metafields/#{id}.json

Get a single product metafield by its ID.

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

GET https://apis.haravan.com/com/products/632910392/metafields/845366454.json

View response

HTTP/1.1 200 OK
{
  "metafield": {
    "created_at": "2021-11-30T08:40:33.594Z",
    "description": "French product title",
    "id": 845366454,
    "key": "title_fr",
    "namespace": "translations",
    "owner_id": 632910392,
    "updated_at": "2021-12-13T06:32:35.731Z",
    "value": "produit",
    "value_type": "string",
    "owner_resource": "product"
  }
}
POST   https://apis.haravan.com/com/metafields.json

Create a new metafield for a store.

Create a new metafield for a store.

POST https://apis.haravan.com/com/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View response

HTTP/1.1 201 Created
{
  "metafield": {
    "created_at": "2016-09-15T09:53:02.887Z",
    "description": null,
    "id": 1003594533,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 1000045110,
    "owner_resource": "shop",
    "value": "25",
    "value_type": "integer",
    "updated_at": "2021-12-21T06:58:17.290Z"
  }
}

Trying to create a metafield without a key will return an error.

POST https://apis.haravan.com/com/metafields.json

{
  "metafield": {
    "key": null
  }
}

View response

HTTP/1.1 422 Unprocessable Entity
{
    "errors": "Key can't be blank"
}
POST   https://apis.haravan.com/com/products/#{id}/metafields.json

Create a new metafield for a product.

Create a new metafield for a product.

POST https://apis.haravan.com/com/products/1037394594/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": 25,
    "value_type": "integer"
  }
}

View response

HTTP/1.1 201 Created
{
  "metafield": {
    "created_at": "2021-12-21T07:41:41.298Z",
    "description": null,
    "id": 1015890158,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 1037394594,
    "owner_resource": "product",
    "value": "25",
    "value_type": "integer",
    "updated_at": "2021-12-21T07:41:41.298Z"
  }
}

Create a new metafield for a product with "value_type": "json". A JSON-formatted string.

POST https://apis.haravan.com/com/products/1037394594/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": "[{\"k\":\"v1\"},{\"k\":\"v2\"}]",
    "value_type": "json"
  }
}

View response

HTTP/1.1 201 Created
{
  "metafield": {
    "created_at": "2021-12-22T04:33:44.121Z",
    "description": null,
    "id": 1015892658,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 1037394594,
    "owner_resource": "product",
    "value": "[{\"k\":\"v1\"},{\"k\":\"v2\"}]",
    "value_type": "json",
    "updated_at": "2021-12-22T04:33:44.121Z"
  }
}

Another example JSON-formatted string.

POST https://apis.haravan.com/com/products/1037394594/metafields.json

{
  "metafield": {
    "namespace": "inventory",
    "key": "warehouse",
    "value": "{\"price\":10000,\"stock\":\"instock\",\"meta\":[{\"k\":\"v1\"},{\"k\":\"v2\"}]}",
    "value_type": "json"
  }
}

View response

HTTP/1.1 201 Created
{
  "metafield": {
    "created_at": "2021-12-22T04:33:44.121Z",
    "description": null,
    "id": 1015892658,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 1037394594,
    "owner_resource": "product",
    "value": "{\"price\":10000,\"stock\":\"instock\",\"meta\":[{\"k\":\"v1\"},{\"k\":\"v2\"}]}",
    "value_type": "json",
    "updated_at": "2021-12-22T04:46:38.624Z"
  }
}
PUT   https://apis.haravan.com/com/metafields/#{id}.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 https://apis.haravan.com/com/metafields/1003594533.json

{
  "metafield": {
    "id": 1003594533,
    "value": "something new",
    "value_type": "string"
  }
}

View response

HTTP/1.1 200 OK
{
  "metafield": {
    "created_at": "2016-09-15T09:53:02.887Z",
    "description": null,
    "id": 1003594533,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 1000045110,
    "owner_resource": "shop",
    "value": "something new",
    "value_type": "string",
    "updated_at": "2021-12-21T07:47:01.191Z"
  }
}
PUT   https://apis.haravan.com/com/products/#{id}/metafields/#{id}.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 https://apis.haravan.com/com/products/1037394594/metafields/1015890158.json

{
  "metafield": {
    "id": 1015890158,
    "value": "titre",
    "value_type": "string"
  }
}

View response

HTTP/1.1 200 OK
{
  "metafield": {
    "created_at": "2021-12-21T07:41:41.298Z",
    "description": null,
    "id": 1015890158,
    "key": "warehouse",
    "namespace": "inventory",
    "owner_id": 1037394594,
    "owner_resource": "product",
    "value": "titre",
    "value_type": "string",
    "updated_at": "2021-12-21T07:52:47.536Z"
  }
}
DELETE   https://apis.haravan.com/com/metafields/#{id}.json

Delete a store metafield.

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

DELETE https://apis.haravan.com/com/metafields/721389482.json

View response

HTTP/1.1 200 OK
{}
DELETE   https://apis.haravan.com/com/products/#{id}/metafields/#{id}.json

Delete a product metafield.

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

DELETE https://apis.haravan.com/com/products/632910392/metafields/845366454.json

View response

HTTP/1.1 200 OK
{}