Metafield definitions

Read-only discovery. Metafield values are read and written on their owner resources (/products/{id}/metafields, variants, customers) addressed by namespace.key; this endpoint answers the prior question — which definitions exist that my app may use? The visibility matrix is the same one that governs value reads and webhook delivery: your app always sees its own definitions, merchant definitions with app_access: shared, and other apps' shared definitions; private definitions never appear.

Definitions cannot be created or modified through the Store API. An app's definitions are declared in its dev-portal configuration and materialize automatically on install under the app's slug as namespace; merchants author theirs in the admin. The scope must match the requested owner_type: product and variant require read_products, customer requires read_customers.

Endpoints#

List metafield definitions

GET read_products

List the metafield definitions visible to the calling app (paginated).

Read-only discovery: returns every definition the caller may read under the access matrix — the app's own (declared in the dev portal, materialized on install), merchant definitions with app_access=shared, and other apps' shared definitions. Private definitions never appear. owner_type selects the owner surface; the scope must match it: product and variant require read_products, customer requires read_customers. Definitions cannot be created or modified through the Store API — an app's definitions come from its reviewed declaration.

Query parameters

Name	Type	Description
`owner_type` required	`string`	Owner surface: product, variant, or customer.
`page`	`integer`	Page number (default 1).
`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, or customer.
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",
        "description": "Primary material of the product.",
        "key": "material",
        "merchant_access": "read_write",
        "name": "Material",
        "namespace": "specs",
        "owned_by": "merchant",
        "owner_type": "product",
        "type": "single_line_text",
        "validation_rules": null
      }
    ],
    "limit": 50,
    "page": 1,
    "total": 1,
    "total_pages": 1
  },
  "success": true
}