List Shopify Metafield Definitions
GET/api/shopify/:integrationInstance/metafield-definitions
Lists the product and variant metafield definitions of this Shopify store. Each definition can be mapped as a listing field when publishing products to Shopify, using the same sources as any other channel field: a product field, a product attribute, a static value or combined fields.
integrations:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
Authentication: Requires Bearer token.
The store's definitions are refreshed from Shopify first when the local copy is missing or more than 24 hours old. If that refresh fails, the last good copy is returned and sync_error says why.
Query parameters (all optional):
- owner_type:
productorvariant - search: matches name, namespace or key (partial)
- status:
active(default),retired(no longer defined in Shopify) orall - page, per_page: pagination (default 50, max 500)
Response fields per definition:
- field_name: the listing field name the metafield maps under (
metafield.{namespace}.{key}, orvariant_metafield.{namespace}.{key}for variant metafields) - type / type_label: the Shopify metafield type
- supported: false for types that cannot be sent yet (file references are sent from an image or file URL; page, customer, company and mixed references are not supported)
- choices: allowed values when the definition restricts them
- mapping: the channel-wide source the field resolves from, or null
Top-level extras: last_synced_at, sales_channel_id, sync_error. Category (taxonomy) metafields in the shopify namespace and app-reserved namespaces are not listed.
Request
Responses
- 200
- 401
- 403
- 404
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.