Metafields

The Metafields API reads metafields from storefront JavaScript. It covers what Liquid cannot: Liquid resolves metafields while the page renders, and only for the objects that page already has, such as product.metafields on a product page. These endpoints run at any moment in the browser and take object ids, so you can read the metafields of any product, collection or the shop itself — after the page has loaded, in a script that never sees the Liquid context, or for several objects in one request.

For what metafields are and how to define them, see Metafields overview. For the Liquid side, see Use metafields in Liquid.

Both endpoints are open to anonymous visitors.

All Ajax API requests should use locale-aware URLs to give visitors a consistent experience.

List the metafields of one kind of object

GET /{locale}/api/front/metafields/{owner_resource}/list

Read the metafields of one kind of object as a flat list. owner_resource takes shop, product, product_variant or collection.

What comes back depends on how many owner_ids you send and whether you narrow the field with namespace and key:

To read	owner_ids	namespace + key
One metafield	one id	one pair
All metafields of one object	one id	leave out
The same field on several objects	repeat the parameter once per id	one pair
All metafields of several objects	repeat the parameter once per id	leave out

limit and page only page through the result; they do not change which metafields are selected.

Example request

const params = new URLSearchParams({
  namespace: 'custom',
  key: 'manual_test',
  limit: '10'
});
params.append('owner_ids', '14a309ec-b966-4cf9-a9bb-33baa821fdbc');
params.append('owner_ids', 'f934ce3e-02c2-4e97-8412-19221eedbffd');

fetch(window.SHOPLAZZA.routes.root + '/api/front/metafields/product/list?' + params)
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

Request parameters

owner_resourcestring

The kind of object: shop, product, product_variant or collection.

owner_idsstring

The id of the object to read. Repeat the parameter to read several objects. For shop, this is the store id.

namespacestring

Return only metafields in this namespace.

keystring

Return only the metafield with this key. Use it together with namespace.

definition_idstring

Return only the metafields created from this metafield definition. It is the same id that definition_ids takes on the batch query endpoint.

limitnumber

The number of metafields to return.

pagenumber

The page of metafields to return, starting at 1. 0 is treated as 1.

Response

The total, remain, page, total_page and have_next fields stay at their zero values even when metafields are returned.

Schema

data object

The response payload.

metafields object[]

List of metafields.

Array [

idstring

ID of the metafield.

store_idnumber

ID of the store the object belongs to.

owner_idstring

ID of the resource the metafield is attached to.

owner_resourcestring

Resource type the metafield is attached to, for example product.

namespacestring

Namespace that groups the metafield.

keystring

Key of the metafield, unique within its namespace.

valuestring

Value of the metafield; its data type is decided by type.

typestring

Value type of the metafield, for example single_line_text_field.

descriptionstring

Description of the metafield.

created_atstring

Creation time, in ISO-8601 format.

updated_atstring

Last update time, in ISO-8601 format.

]

totalnumber

Total number of metafields matched.

remainnumber

pagenumber

Current page number.

total_pagenumber

Total number of pages.

have_nextboolean

Whether a next page is available.

msgstring

Result message returned with the response.

statenumber

Request result flag; success or 0 means the request succeeded.

Example

{
  "data": {
    "metafields": [
      {
        "id": "676328500579297095",
        "store_id": 2446407,
        "owner_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc",
        "owner_resource": "product",
        "namespace": "custom",
        "key": "manual_test",
        "value": "222222222",
        "type": "single_line_text_field",
        "description": "",
        "created_at": "2026-08-10T07:28:25Z",
        "updated_at": "2026-08-10T07:28:25Z"
      },
      {
        "id": "686766315775468871",
        "store_id": 2446407,
        "owner_id": "f934ce3e-02c2-4e97-8412-19221eedbffd",
        "owner_resource": "product",
        "namespace": "custom",
        "key": "manual_test",
        "value": "333333333",
        "type": "single_line_text_field",
        "description": "",
        "created_at": "2026-09-08T02:44:09Z",
        "updated_at": "2026-09-08T02:44:09Z"
      }
    ],
    "total": 0,
    "remain": 0,
    "page": 0,
    "total_page": 0,
    "have_next": false
  },
  "msg": "请求成功",
  "state": 0
}

Read a single metafield

There is no endpoint that returns one metafield by its id. To read a single metafield of any object, call this endpoint with the object's owner_resource, one owner_ids value, and the metafield's namespace and key. data.metafields then holds exactly one entry. Compare it with the example request above, which reads the same field on two products. This example reads one metafield of one product; use shop, product_variant or collection in the path for the other kinds of object:

const params = new URLSearchParams({
  owner_ids: '14a309ec-b966-4cf9-a9bb-33baa821fdbc',
  namespace: 'custom',
  key: 'manual_test'
});

fetch(window.SHOPLAZZA.routes.root + '/api/front/metafields/product/list?' + params)
  .then((response) => response.json())
  .then((data) => {
    const metafield = data.data.metafields[0];
    console.log(metafield ? metafield.value : 'not set');
  });

The batch endpoint below does the same when unique_keys holds one namespace and key pair. Metafields cannot be created or changed from the storefront; use the Metafield REST API for that.

Query the metafields of several objects

POST /{locale}/api/front/v2/metafields/{owner_resource}/query

Read the metafields of several objects in one request and get them back grouped by object. owner_resource takes shop, product or collection; any other value is rejected with 422 and {"errors":["unsupported owner_resource"]}.

Pick the metafields either by namespace and key with unique_keys, or by definition with definition_ids. Exactly one of the two must be present: sending neither or both is rejected with 422 and {"errors":["exactly one of unique_keys or definition_ids is required"]}.

For owner_resource shop you can leave owner_ids out, because the store is the only possible owner.

Example request

const data = {
  owner_ids: ['14a309ec-b966-4cf9-a9bb-33baa821fdbc'],
  unique_keys: [
    { namespace: 'custom', key: 'manual_test' }
  ]
};

fetch(window.SHOPLAZZA.routes.root + '/api/front/v2/metafields/product/query', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json'
  },
  body: JSON.stringify(data)
})
  .then((response) => response.json())
  .then((data) => {
    // do something...
  });

Request parameters

Schema

owner_resourcestring

The kind of object: shop, product or collection.

owner_idsstring[]

The ids of the objects to read. Optional when owner_resource is shop.

unique_keys object[]
The metafields to read, each an object with a namespace and a key.
Array [
namespacestring
keystring
]
definition_idsstring[]

The metafield definitions to read. Send either this or unique_keys, not both.

Example

{
  "owner_ids": [
    "14a309ec-b966-4cf9-a9bb-33baa821fdbc"
  ],
  "unique_keys": [
    {
      "namespace": "custom",
      "key": "manual_test"
    }
  ]
}

Response

Schema

data object
The response payload.
owner_metafields object[]
Metafields grouped by the resource they are attached to.
Array [
owner_idstring
ID of the resource the metafield is attached to.
metafields object[]
List of metafields.
Array [
idstring
ID of the metafield.
store_idnumber
ID of the store the object belongs to.
owner_idstring
ID of the resource the metafield is attached to.
owner_resourcestring
Resource type the metafield is attached to, for example product.
namespacestring
Namespace that groups the metafield.
keystring
Key of the metafield, unique within its namespace.
valuestring
Value of the metafield; its data type is decided by type.
typestring
Value type of the metafield, for example single_line_text_field.
descriptionstring
Description of the metafield.
created_atstring
Creation time, in ISO-8601 format.
updated_atstring
Last update time, in ISO-8601 format.
definition_idstring
ID of the metafield definition the metafield is bound to.
]
]
msgstring

Result message returned with the response.

statenumber

Request result flag; success or 0 means the request succeeded.

Example

{
  "data": {
    "owner_metafields": [
      {
        "owner_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc",
        "metafields": [
          {
            "id": "676328500579297095",
            "store_id": 2446407,
            "owner_id": "14a309ec-b966-4cf9-a9bb-33baa821fdbc",
            "owner_resource": "product",
            "namespace": "custom",
            "key": "manual_test",
            "value": "222222222",
            "type": "single_line_text_field",
            "description": "",
            "created_at": "2026-08-10T07:28:25Z",
            "updated_at": "2026-08-10T07:28:25Z",
            "definition_id": "676319747943433287"
          }
        ]
      }
    ]
  },
  "msg": "请求成功",
  "state": 0
}