Metafields
Requires scope merchant-metafields-read.
Lists the store’s metafield definitions: its custom-field schema, the merchant’s own and, for an installed app, its own app-owned ones (never another app’s). Each carries app_owned and merchant_access.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Query Parameters
Maximum number of items to return in one page.
1 <= value <= 100Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only definitions for this kind of record: product, order, customer, collection, post or variant.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Response Body
application/json
application/json
application/json
application/json
application/json
curl -X GET "https://example.com/metafield-definitions?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "p_id": 413, "handle": "custom.event_date", "owner_type": "order", "namespace": "custom", "key": "event_date", "type": "date", "storefront_visible": false, "customer_visible": false, "app_owned": false, "merchant_access": "read_write", "pinned": false, "pinned_position": null, "name": "Event date", "description": "The day a party order is for.", "validations": {}, "created_at": "2026-08-02T10:05:00.000000Z", "updated_at": "2026-08-02T10:05:00.000000Z" }, { "p_id": 412, "handle": "custom.spice_level", "owner_type": "product", "namespace": "custom", "key": "spice_level", "type": "single_line_text", "storefront_visible": true, "customer_visible": false, "app_owned": false, "merchant_access": "read_write", "pinned": true, "pinned_position": 1, "name": "Spice level", "description": "How hot the dish is: mild, medium or hot.", "validations": { "choices": [ "mild", "medium", "hot" ] }, "created_at": "2026-08-02T10:00:00.000000Z", "updated_at": "2026-08-02T10:00:00.000000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6NDEyLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9"}Requires scope merchant-metafields-create.
Creates a metafield definition. An installed app that creates one in its own app_{slug} namespace (the slug with hyphens as underscores, exactly: app_{slug}_… is another app’s) owns it: the definition is hidden from the storefront unless storefront_visible is true, merchant_access is read (the merchant sees the values, the app alone writes them) or read_write, and only that app reads or writes its values through the API (another app and a plain store key cannot). Any other namespace creates the merchant’s own definition, exactly as before; the app and app_… namespace form is reserved for apps and refused to anyone else. merchant_access is refused on a definition that is not app-owned. Uninstalling the app hands its definitions and values to the merchant. owner_type installation is an app’s own data on its installation (read and written with GET and PATCH app/metafields): only an installed app creates one, in its own app_{slug} namespace, without storefront_visible or merchant_access; at most 50 per installation, outside the store’s definition limit; they are deleted, not handed over, at uninstall.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Create/update/delete a metafield definition on the REST developer surface.
Over the Merchant API a key changes or deletes only its OWN installation fields
(owner type installation, PATCH|DELETE metafield-definitions/{definition}); the
merchant's and other apps' definitions answer 404 there.
namespace, key, owner_type and type are immutable after creation: a
stored value denormalises all four, so changing one would silently orphan
every value already written against it. Only presentation (name,
description) and validations may change, and a tightened validation is
documented as applying to future writes only.
The same rules back every surface that writes definitions, so all of them accept exactly the same legal definitions.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/metafield-definitions" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "owner_type": "product", "namespace": "custom", "key": "spice_level", "type": "single_line_text", "name": "Spice level", "description": "How hot the dish is: mild, medium or hot.", "storefront_visible": true, "customer_visible": false, "pinned": true, "pinned_position": 1, "validations": { "choices": [ "mild", "medium", "hot" ] } }'{ "status": "success", "message": "Metafield definition created", "data": { "p_id": 412, "handle": "custom.spice_level", "owner_type": "product", "namespace": "custom", "key": "spice_level", "type": "single_line_text", "storefront_visible": true, "customer_visible": false, "app_owned": false, "merchant_access": "read_write", "pinned": true, "pinned_position": 1, "name": "Spice level", "description": "How hot the dish is: mild, medium or hot.", "validations": { "choices": [ "mild", "medium", "hot" ] }, "created_at": "2026-08-02T10:00:00.000000Z", "updated_at": "2026-08-02T10:00:00.000000Z" }}Requires scope merchant-app_metafields-update.
Changes the name, description or validations of one of the calling installation’s own installation definitions (namespace, key, owner_type and type are fixed: delete and recreate to change them; a tightened validation applies to later writes). {definition} is the definition’s p_id. The merchant’s definitions and another app’s answer 404 here. The installation is the calling key’s; the scope is granted to every installation key.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the definition, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Request Body
application/json
TypeScript Definitions
Use the request body type in TypeScript.
Create/update/delete a metafield definition on the REST developer surface.
Over the Merchant API a key changes or deletes only its OWN installation fields
(owner type installation, PATCH|DELETE metafield-definitions/{definition}); the
merchant's and other apps' definitions answer 404 there.
namespace, key, owner_type and type are immutable after creation: a
stored value denormalises all four, so changing one would silently orphan
every value already written against it. Only presentation (name,
description) and validations may change, and a tightened validation is
documented as applying to future writes only.
The same rules back every surface that writes definitions, so all of them accept exactly the same legal definitions.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
application/json
curl -X PATCH "https://example.com/metafield-definitions/418" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "name": "Default lead time (days)", "validations": { "min": 0, "max": 60 } }'{ "status": "success", "message": "Metafield definition updated", "data": { "p_id": 418, "handle": "app_example_channel.default_lead_days", "owner_type": "installation", "namespace": "app_example_channel", "key": "default_lead_days", "type": "integer", "storefront_visible": false, "customer_visible": false, "app_owned": true, "merchant_access": "read", "pinned": false, "pinned_position": null, "name": "Default lead time (days)", "description": null, "validations": { "min": 0, "max": 60 }, "created_at": "2026-10-23T08:00:00.000000Z", "updated_at": "2026-10-23T08:30:00.000000Z" }}Requires scope merchant-app_metafields-update.
Deletes one of the calling installation’s own installation definitions and the value written against it, and frees its place in the 50-per-installation limit. {definition} is the definition’s p_id. The merchant’s definitions and another app’s answer 404 here. Answers deleted_values, the number of values deleted.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). It is bound to one store and carries the scopes the merchant granted; each operation names the scope it needs. Server-side only — never ship it to a browser or an app bundle.
In: header
Path Parameters
Identifier of the definition, as returned by the Merchant API.
Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted by a Server connection under Dashboard → Channels → Headless API (keys are also listed in Settings → Connections). The key is bound to ONE store, so no vendor header or vendor_id is sent; its scopes decide which operations it may call. pk_ public keys never reach this API. Keep it on your server.
Your own correlation id (8–128 chars, ^[A-Za-z0-9_.:-]+$). Echoed back on the response and on every log line of the request; one is generated when you omit it.
Retry-safe write key. The same key with the same body replays the stored response for 24h with Idempotent-Replayed: true; with a different body it is 409 idempotency_key_reuse; while the first call is still running it is 409 idempotency_key_in_progress.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X DELETE "https://example.com/metafield-definitions/418" \ -H "X-Client-Key: {{merchantKey}}"{ "status": "success", "message": "Metafield definition deleted", "data": { "deleted_values": 1 }}