Metafield definitions

Discover available custom-data fields, their types, access rules, and value limits.

Discover the custom-data definitions available to your token before reading or writing values. Choose an owner_type and use its resource read scope. Values are addressed by namespace and key on the owning resource. Your token's scopes and each definition's access rules determine which entries are returned. App tokens can read their own definitions, merchant definitions within their granted resource scopes, and definitions shared by other apps. Apps can write values only for their own definitions.

This endpoint is read-only. Use the returned type, validation rules, max_value_length, and max_list_items when preparing values. Numeric strings preserve precision across clients. Datetime values accept RFC 3339 offsets; values without an offset use the store timezone. Store API datetime responses use UTC. Assigning a nonempty file_reference or list.file_reference additionally requires read_files.

Follow returned cursors unchanged, and restart pagination when the owner or token changes. App-owned definitions are declared through the app's metafield configuration; see App metafields in the apps documentation.

Endpoints#

List metafield definitions

GET The read scope required by owner_type

List the metafield definitions visible to this token (paginated).

Read-only discovery uses the same access rules as metafield value reads. tpat_ and tast_ tokens see merchant-owned definitions, all definitions owned by their app, and definitions owned by another app only when app_access is shared. A tsat_ token sees merchant-owned definitions and app-owned definitions unless merchant_access is hidden. owner_type selects the owner surface and its matching read scope. Definitions cannot be created or modified through the Store API; app definitions come from the app's reviewed declaration. When a definition sets max_value_length or max_list_items, those caps are enforced on every value write; tightening them in Store Admin is blocked while stored values still exceed the new limit.

Value rules by type

Values are checked against their definition's type on every write. null or an empty string removes the stored value.

Type	Accepted value
`string`	Any text up to the platform string limit. The definition may add `min_length` and an RE2 `pattern` (at most 500 characters).
`integer`	A whole number in the signed 64-bit range, up to the platform integer digit limit, within the definition's `min` and `max`.
`decimal`	A finite decimal number up to the platform decimal length limit (counted written out in full, so an exponent cannot exceed it), within the definition's `min` and `max`.
`boolean`	`true` or `false`.
`date`	`YYYY-MM-DD`.
`datetime`	`YYYY-MM-DDTHH:mm`, `YYYY-MM-DDTHH:mm:ss`, or an RFC 3339 timestamp.
`json`	Valid JSON up to the platform JSON size limit. Links inside it must use http, https, mailto or tel.
`url`	An absolute `http` or `https` URL with a host, up to the platform URL limit.
`single_select`	One of the definition's choice keys.
`file_reference`	The UUID of an uploaded file in this store.
`product_reference`, `variant_reference`	The positive integer ID of a product or variant in this store.
`list.string`	A JSON array of non-blank strings, each up to the platform string limit. It may be empty.
`list.url`	A non-empty JSON array of `url` values, up to the platform list.url item limit, which is higher than the other lists' limit.
`list.single_select`	A non-empty JSON array of choice keys.
`list.file_reference`	A non-empty JSON array of `file_reference` values.
`list.product_reference`, `list.variant_reference`	A non-empty JSON array of positive integer IDs in this store.

Lists other than list.url hold at most the platform list item limit, and every value stays within the platform value size limit for its type. Duplicate list items are stored once. A definition's max_value_length and max_list_items can only lower these limits.

cart_line and wishlist_line values are written only by the storefront and App Bridge; the Store API has no endpoint that sets them.

Query parameters

Name	Type	Description
`owner_type` required	`string`	Owner surface. Supported values are product, variant, customer, order, order_item, cart_line, wishlist_line, collection, category, page, blog_post, blog_category, vendor, brand, and store. Each requires the matching resource read scope.
`cursor`	`string`	Opaque cursor from a previous response. Omit for the first page; use next_cursor or previous_cursor to move forward or backward. Reset the cursor whenever owner_type or the token changes.
`limit`	`integer`	Page size; capped by the definition list limit.

Headers

Name	Type	Description
`Authorization` required	`string`	Bearer Store API token.

Errors

400 METAFIELD_DEFINITION_INVALID_OWNER_TYPE
Owner_type must be product, variant, customer, order, order_item, cart_line, wishlist_line, collection, category, page, blog_post, blog_category, vendor, brand, or store.
401 UNAUTHORIZED
Missing or invalid token.
403 STORE_ADMIN_TOKEN_RUNTIME_FORBIDDEN
The token lacks the read scope matching owner_type.

curl 'https://api-store.tringify.com/api/2025-01/metafield-definitions' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN"

const res = await fetch("https://api-store.tringify.com/api/2025-01/metafield-definitions", {
  method: "GET",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
});
const data = await res.json();

import requests

res = requests.get(
    "https://api-store.tringify.com/api/2025-01/metafield-definitions",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "definitions": [
      {
        "app_access": "shared",
        "capabilities": {
          "allowed": true,
          "buyer_access": false,
          "filterable": false,
          "searchable": true,
          "storefront_visible": true,
          "translation": "value"
        },
        "description": "Primary material of the product.",
        "is_filterable": false,
        "is_searchable": true,
        "is_storefront_visible": true,
        "is_translatable": true,
        "key": "material",
        "max_list_items": null,
        "max_value_length": 128,
        "merchant_access": "read_write",
        "name": "Material",
        "namespace": "specs",
        "owned_by": "merchant",
        "owner_type": "product",
        "type": "string",
        "validation_rules": null
      }
    ],
    "has_next": false,
    "has_previous": false,
    "limit": 50,
    "total": 1
  },
  "success": true
}