Metafields
Requires scope merchant-metafields-read.
Lists the store’s metafield definitions: its custom-field schema.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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
1 <= value <= 100Header Parameters
A private API key (sk_live_…, sk_test_… on a dev store) minted under Dashboard → Settings → API keys. 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, "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, "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.
Authorization
merchantKey The store's private API key (sk_live_…, sk_test_… on a dev store) from Dashboard → Settings → API keys. 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 under Dashboard → Settings → API keys. 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 a metafield definition on the REST developer surface.
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, "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, "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" }}