Shop metafields

Read and write the store's shop-level custom-data values.

Shop metafields hold custom data for the store as a whole, such as a brand story or a support banner. The store has one set of values, so these endpoints take no owner ID: the token's store is always the owner. Reads require read_storefront; writes require write_storefront. Translation requests also require read_translations or write_translations.

Discover the available definitions with GET /metafield-definitions?owner_type=store, then address values by namespace and key. The access rules match every other owner: app tokens read their own definitions, merchant-owned definitions, and other apps' shared definitions, and write only definitions their app owns. Store Admin tokens follow the definition's merchant_access. URL-encode : when an app namespace such as app:<slug> appears in a path.

Endpoints#

List shop metafields

GET read_storefront

List the store's shop-level custom-data values visible to the token.

Returns the store's shop-level values, paginated, for definitions the token can read. App tokens see values of their own definitions, merchant-owned definitions, and other apps' definitions shared with app_access: shared.

Query parameters

Name	Type	Description
`page`	`integer`	Page number (default 1).
`limit`	`integer`	Page size; capped by the metafield list limit.

Headers

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

Errors

400 VALIDATION_LIST_INVALID_PAGE
Page must be a positive integer.
400 VALIDATION_LIST_INVALID_LIMIT
Limit must be a positive integer.

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

const res = await fetch("https://api-store.tringify.com/api/2025-01/store/metafields", {
  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/store/metafields",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "limit": 50,
    "metafields": [
      {
        "created_at": "2026-09-01T12:00:00Z",
        "definition": {
          "app_access": "private",
          "buyer_access": "hidden",
          "created_at": "2026-09-01T12:00:00Z",
          "id": "642a703a-9639-4d25-8d02-426f6f9f7d12",
          "is_filterable": false,
          "is_searchable": false,
          "is_storefront_visible": true,
          "is_translatable": true,
          "key": "subtitle",
          "merchant_access": "read_write",
          "name": "Subtitle",
          "namespace": "details",
          "owner_type": "store",
          "sort_order": 0,
          "type": "string",
          "updated_at": "2026-09-01T12:00:00Z",
          "usage_count": 0
        },
        "updated_at": "2026-09-01T12:00:00Z",
        "value": "Company news"
      }
    ],
    "page": 1,
    "total": 1,
    "total_pages": 1
  },
  "success": true
}

Set shop metafields

PUT write_storefront

Create, update, or delete shop-level custom-data values.

Send namespace-and-key entries. A string value creates or replaces a value; null or an empty string deletes it. App tokens can write only definitions their app owns. The complete value change succeeds or fails together, and omitted entries are preserved. Each change sends the matching store_metafields/* webhook.

Headers

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

Body parameters

Name	Type	Description
`metafields` required	`array<object>`	Entries shaped as `{namespace, key, value}`. `value` is required in every entry; send `null` or an empty string to delete the stored value. Example: `[{"namespace":"details","key":"subtitle","value":"Handmade in Lisbon"}]`

Errors

400 STORE_API_INVALID_REQUEST_BODY
The body or entry shape is invalid. Each entry requires an explicit value, including null for deletion.
400 METAFIELD_NO_WRITES
Provide at least one metafield entry.
400 METAFIELD_DUPLICATE_WRITE
A namespace and key occur more than once.
400 PRODUCT_METAFIELD_DEF_NOT_FOUND
The namespace and key do not identify a definition this token can write. For an app token that is a definition its app owns; merchant-owned and other apps' definitions return this code too.
403 METAFIELD_WRITE_MERCHANT_READ_ONLY
A non-app token addressed an app-owned definition whose merchant_access is not read_write.
403 STORE_API_SCOPE_REQUIRED
Binding a nonempty file_reference or list.file_reference also requires read_files. Clearing a reference does not.
400 METAFIELD_VALUE_TOO_LONG
The value exceeds its size limit: the definition's max_value_length, or the platform value size limit for the type.
400 METAFIELD_VALUE_STRING_TOO_LONG
A string value exceeds the definition's max_value_length or the platform string limit.
400 METAFIELD_VALUE_TOO_SHORT
A string value is shorter than the definition's min_length rule.
400 METAFIELD_VALUE_PATTERN_MISMATCH
A string value does not match the definition's pattern rule.
400 METAFIELD_VALUE_INTEGER_INVALID
An integer value is not a whole number in the 64-bit range.
400 METAFIELD_VALUE_INTEGER_TOO_LONG
An integer value has more digits than the definition or the platform integer limit allows.
400 METAFIELD_VALUE_DECIMAL_INVALID
A decimal value is not a finite decimal number.
400 METAFIELD_VALUE_DECIMAL_TOO_LONG
A decimal value, written out in full, is longer than the definition or the platform decimal limit allows.
400 METAFIELD_VALUE_BELOW_MIN
An integer or decimal value is below the definition's min rule.
400 METAFIELD_VALUE_ABOVE_MAX
An integer or decimal value is above the definition's max rule.
400 METAFIELD_VALUE_BOOLEAN_INVALID
A boolean value is not true or false.
400 METAFIELD_VALUE_DATE_INVALID
A date value is not a calendar date in YYYY-MM-DD form.
400 METAFIELD_VALUE_DATETIME_INVALID
A datetime value is not YYYY-MM-DDTHH:mm, YYYY-MM-DDTHH:mm:ss or an RFC 3339 timestamp.
400 METAFIELD_VALUE_JSON_INVALID
A json value is not valid JSON.
400 METAFIELD_VALUE_JSON_UNSAFE_LINK
A json value contains a link whose scheme is not http, https, mailto or tel.
400 METAFIELD_VALUE_URL_INVALID
A url value, or an item of a list.url value, is not an absolute URL with a host.
400 METAFIELD_VALUE_URL_SCHEME
A url value, or an item of a list.url value, does not use http or https.
400 METAFIELD_VALUE_URL_TOO_LONG
A url value, or an item of a list.url value, exceeds the definition's max_value_length or the platform URL limit.
400 METAFIELD_VALUE_NOT_IN_CHOICES
A single_select value is not one of the definition's choice keys.
400 METAFIELD_LIST_CHOICE_INVALID
An item of a list.single_select value is not one of the definition's choice keys; the message names the item.
400 METAFIELD_LIST_STRINGS_INVALID
A list.string or list.single_select value is not a JSON array of strings.
400 METAFIELD_LIST_URLS_INVALID
A list.url value is not a JSON array of strings.
400 METAFIELD_LIST_FILES_INVALID
A list.file_reference value is not a JSON array of strings.
400 METAFIELD_LIST_IDS_INVALID
A list.product_reference or list.variant_reference value is not a JSON array of integers.
400 METAFIELD_LIST_EMPTY
A list value other than list.string is an empty array. Send null or an empty string to remove the value instead.
400 METAFIELD_LIST_TOO_MANY
A list value has more items than the definition's max_list_items or the platform list limit for the type.
400 METAFIELD_LIST_ITEM_EMPTY
An item of a list.string value is empty or only whitespace; the message names the item.
400 METAFIELD_LIST_ITEM_TOO_LONG
An item of a list.string value exceeds the definition's max_value_length or the platform string limit; the message names the item.
400 METAFIELD_VALUE_FILE_UUID_INVALID
A file_reference value, or an item of a list.file_reference value, is not a file UUID.
400 METAFIELD_VALUE_ID_INVALID
A product_reference or variant_reference value is not an integer ID.
400 METAFIELD_VALUE_ID_POSITIVE
A product_reference or variant_reference value is not a positive integer.
400 METAFIELD_VALUE_ID_TOO_LONG
A product_reference or variant_reference value exceeds the platform reference ID limit.
400 METAFIELD_LIST_ITEMS_POSITIVE
An item of a list.product_reference or list.variant_reference value is not a positive integer.
400 METAFIELD_REFERENCE_PRODUCT_MISSING
A product reference names a product that does not exist in this store.
400 METAFIELD_REFERENCE_VARIANT_MISSING
A variant reference names a variant that does not exist in this store.
404 NOT_FOUND
A file reference names a file that does not exist in this store.
400 INVALID_INPUT
A file reference names a file that is not an uploaded file.

curl -X PUT 'https://api-store.tringify.com/api/2025-01/store/metafields' \
  -H "Authorization: Bearer YOUR_STORE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
  "metafields": [
    {
      "key": "subtitle",
      "namespace": "details",
      "value": "Handmade in Lisbon"
    }
  ]
}'

const res = await fetch("https://api-store.tringify.com/api/2025-01/store/metafields", {
  method: "PUT",
  headers: {"Authorization":"Bearer YOUR_STORE_API_TOKEN","Content-Type":"application/json"},
  body: JSON.stringify({
    "metafields": [
      {
        "key": "subtitle",
        "namespace": "details",
        "value": "Handmade in Lisbon"
      }
    ]
  }),
});
const data = await res.json();

import requests

res = requests.put(
    "https://api-store.tringify.com/api/2025-01/store/metafields",
    headers={"Authorization":"Bearer YOUR_STORE_API_TOKEN"},
    json={
        "metafields": [{
            "key": "subtitle",
            "namespace": "details",
            "value": "Handmade in Lisbon",
        }],
    },
)
data = res.json()

Response

200

Sample response

{
  "data": {
    "limit": 50,
    "metafields": [
      {
        "created_at": "2026-09-01T12:00:00Z",
        "definition": {
          "app_access": "private",
          "buyer_access": "hidden",
          "created_at": "2026-09-01T12:00:00Z",
          "id": "642a703a-9639-4d25-8d02-426f6f9f7d12",
          "is_filterable": false,
          "is_searchable": false,
          "is_storefront_visible": true,
          "is_translatable": true,
          "key": "subtitle",
          "merchant_access": "read_write",
          "name": "Subtitle",
          "namespace": "details",
          "owner_type": "store",
          "sort_order": 0,
          "type": "string",
          "updated_at": "2026-09-01T12:00:00Z",
          "usage_count": 0
        },
        "updated_at": "2026-09-01T12:00:00Z",
        "value": "Company news"
      }
    ],
    "page": 1,
    "total": 1,
    "total_pages": 1
  },
  "success": true
}

Webhook events#

Subscribe to these events when your integration mirrors shop-level values. Each write sends one event per created, updated, or deleted value, after the change commits. Events follow definition access, like every other metafield event.

Store metafield value created

EVENT store_metafields/create App scope: read_storefront Staff permission: settings.metafield_definitions:write

Fired when a store metafield value is created.

Payload fields

Field	Type	Description
`store.name`	`string`	Selectable in the Payload builder
`metafield.definition.id`	`string`	Selectable in the Payload builder
`metafield.definition.owner_type`	`string`	Selectable in the Payload builder
`metafield.definition.namespace`	`string`	Selectable in the Payload builder
`metafield.definition.key`	`string`	Selectable in the Payload builder
`metafield.definition.name`	`string`	Selectable in the Payload builder
`metafield.definition.description`	`string`	Selectable in the Payload builder
`metafield.definition.type`	`string`	Selectable in the Payload builder
`metafield.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`metafield.definition.max_value_length`	`integer`	Selectable in the Payload builder
`metafield.definition.max_list_items`	`integer`	Selectable in the Payload builder
`metafield.definition.sort_order`	`integer`	Selectable in the Payload builder
`metafield.definition.app_id`	`string`	Selectable in the Payload builder
`metafield.definition.app_access`	`string`	Selectable in the Payload builder
`metafield.definition.merchant_access`	`string`	Selectable in the Payload builder
`metafield.definition.created_at`	`string`	Selectable in the Payload builder
`metafield.definition.updated_at`	`string`	Selectable in the Payload builder
`metafield.definition.usage_count`	`integer`	Selectable in the Payload builder
`metafield.value`	`string`	Selectable in the Payload builder
`metafield.display_value`	`string`	Selectable in the Payload builder
`metafield.display_value_map`	`object`	Selectable in the Payload builder
`metafield.created_at`	`string`	Selectable in the Payload builder
`metafield.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "metafield": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": null,
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": null,
      "id": "...",
      "is_translatable": false,
      "key": "...",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "...",
      "namespace": "...",
      "owner_type": "store",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "..."
  },
  "store": {
    "name": "..."
  }
}

Store metafield value updated

EVENT store_metafields/update App scope: read_storefront Staff permission: settings.metafield_definitions:write

Fired when a store metafield value changes.

Possible `changed_fields` values

The changed_fields array names exactly which of these changed in this event — use it to skip processing updates your integration doesn't care about.

value

Payload fields

Field	Type	Description
`store.name`	`string`	Selectable in the Payload builder
`previous.definition.id`	`string`	Selectable in the Payload builder
`previous.definition.owner_type`	`string`	Selectable in the Payload builder
`previous.definition.namespace`	`string`	Selectable in the Payload builder
`previous.definition.key`	`string`	Selectable in the Payload builder
`previous.definition.name`	`string`	Selectable in the Payload builder
`previous.definition.description`	`string`	Selectable in the Payload builder
`previous.definition.type`	`string`	Selectable in the Payload builder
`previous.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`previous.definition.max_value_length`	`integer`	Selectable in the Payload builder
`previous.definition.max_list_items`	`integer`	Selectable in the Payload builder
`previous.definition.sort_order`	`integer`	Selectable in the Payload builder
`previous.definition.app_id`	`string`	Selectable in the Payload builder
`previous.definition.app_access`	`string`	Selectable in the Payload builder
`previous.definition.merchant_access`	`string`	Selectable in the Payload builder
`previous.definition.created_at`	`string`	Selectable in the Payload builder
`previous.definition.updated_at`	`string`	Selectable in the Payload builder
`previous.definition.usage_count`	`integer`	Selectable in the Payload builder
`previous.value`	`string`	Selectable in the Payload builder
`previous.display_value`	`string`	Selectable in the Payload builder
`previous.display_value_map`	`object`	Selectable in the Payload builder
`previous.created_at`	`string`	Selectable in the Payload builder
`previous.updated_at`	`string`	Selectable in the Payload builder
`current.definition.id`	`string`	Selectable in the Payload builder
`current.definition.owner_type`	`string`	Selectable in the Payload builder
`current.definition.namespace`	`string`	Selectable in the Payload builder
`current.definition.key`	`string`	Selectable in the Payload builder
`current.definition.name`	`string`	Selectable in the Payload builder
`current.definition.description`	`string`	Selectable in the Payload builder
`current.definition.type`	`string`	Selectable in the Payload builder
`current.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`current.definition.max_value_length`	`integer`	Selectable in the Payload builder
`current.definition.max_list_items`	`integer`	Selectable in the Payload builder
`current.definition.sort_order`	`integer`	Selectable in the Payload builder
`current.definition.app_id`	`string`	Selectable in the Payload builder
`current.definition.app_access`	`string`	Selectable in the Payload builder
`current.definition.merchant_access`	`string`	Selectable in the Payload builder
`current.definition.created_at`	`string`	Selectable in the Payload builder
`current.definition.updated_at`	`string`	Selectable in the Payload builder
`current.definition.usage_count`	`integer`	Selectable in the Payload builder
`current.value`	`string`	Selectable in the Payload builder
`current.display_value`	`string`	Selectable in the Payload builder
`current.display_value_map`	`object`	Selectable in the Payload builder
`current.created_at`	`string`	Selectable in the Payload builder
`current.updated_at`	`string`	Selectable in the Payload builder
`changed_fields`	`array`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "changed_fields": [
    "title",
    "status"
  ],
  "current": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": null,
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": null,
      "id": "...",
      "is_translatable": false,
      "key": "...",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "...",
      "namespace": "...",
      "owner_type": "store",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "..."
  },
  "previous": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": null,
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": null,
      "id": "...",
      "is_translatable": false,
      "key": "...",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "...",
      "namespace": "...",
      "owner_type": "store",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "..."
  },
  "store": {
    "name": "..."
  }
}

Store metafield value deleted

EVENT store_metafields/delete App scope: read_storefront Staff permission: settings.metafield_definitions:write

Fired when a store metafield value is deleted.

Payload fields

Field	Type	Description
`store.name`	`string`	Selectable in the Payload builder
`metafield.definition.id`	`string`	Selectable in the Payload builder
`metafield.definition.owner_type`	`string`	Selectable in the Payload builder
`metafield.definition.namespace`	`string`	Selectable in the Payload builder
`metafield.definition.key`	`string`	Selectable in the Payload builder
`metafield.definition.name`	`string`	Selectable in the Payload builder
`metafield.definition.description`	`string`	Selectable in the Payload builder
`metafield.definition.type`	`string`	Selectable in the Payload builder
`metafield.definition.is_translatable`	`boolean`	Selectable in the Payload builder
`metafield.definition.max_value_length`	`integer`	Selectable in the Payload builder
`metafield.definition.max_list_items`	`integer`	Selectable in the Payload builder
`metafield.definition.sort_order`	`integer`	Selectable in the Payload builder
`metafield.definition.app_id`	`string`	Selectable in the Payload builder
`metafield.definition.app_access`	`string`	Selectable in the Payload builder
`metafield.definition.merchant_access`	`string`	Selectable in the Payload builder
`metafield.definition.created_at`	`string`	Selectable in the Payload builder
`metafield.definition.updated_at`	`string`	Selectable in the Payload builder
`metafield.definition.usage_count`	`integer`	Selectable in the Payload builder
`metafield.value`	`string`	Selectable in the Payload builder
`metafield.display_value`	`string`	Selectable in the Payload builder
`metafield.display_value_map`	`object`	Selectable in the Payload builder
`metafield.created_at`	`string`	Selectable in the Payload builder
`metafield.updated_at`	`string`	Selectable in the Payload builder

Payload shape

Sample payload

{
  "metafield": {
    "created_at": "2026-06-09T12:00:00+05:30",
    "definition": {
      "app_access": "shared",
      "app_id": null,
      "created_at": "2026-06-09T12:00:00+05:30",
      "description": null,
      "id": "...",
      "is_translatable": false,
      "key": "...",
      "max_list_items": null,
      "max_value_length": null,
      "merchant_access": "read_write",
      "name": "...",
      "namespace": "...",
      "owner_type": "store",
      "sort_order": 0,
      "type": "string",
      "updated_at": "2026-06-09T12:00:00+05:30",
      "usage_count": 0
    },
    "display_value": null,
    "display_value_map": "...",
    "updated_at": "2026-06-09T12:00:00+05:30",
    "value": "..."
  },
  "store": {
    "name": "..."
  }
}

Endpoints#

Query parameters

Headers

Errors

Headers

Body parameters

Errors

Webhook events#

Payload fields

Possible changed_fields values

Payload fields

Payload fields

Possible `changed_fields` values