Metaobjects
Requires scope merchant-metaobjects-read.
Lists the store’s metaobject definitions: its custom content types.
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.
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/metaobject-definitions?limit=2" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "p_id": 61, "type": "chef", "name": "Chef", "description": "The chefs behind our dishes.", "display_field": "name", "storefront_visible": true, "has_pages": true, "data_class": "content", "app_owned": false, "entry_cap_override": null, "retention_days": null, "fields": [ { "key": "name", "name": "Name", "type": "single_line_text", "required": true, "validations": [] }, { "key": "speciality", "name": "Speciality", "type": "single_line_text", "required": false, "validations": [] }, { "key": "bio", "name": "Bio", "type": "multi_line_text", "required": false, "validations": [] } ], "created_at": "2026-08-10T08:00:00.000000Z", "updated_at": "2026-08-10T08:00:00.000000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6NjEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}Requires scope merchant-metaobjects-create.
Creates a metaobject definition.
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 a metaobject definition on the REST developer surface.
type is immutable after creation: entries carry it, and reference values
resolve through it, so changing one would silently orphan every entry and
link already written against it. The field SET may be replaced on update,
but removing a field (or retyping one) while entries still hold values for
it is a 422.
The same rules back every surface that writes definitions, so all of them accept exactly the same legal types.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/metaobject-definitions" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "type": "chef", "name": "Chef", "description": "The chefs behind our dishes.", "display_field": "name", "storefront_visible": true, "has_pages": true, "fields": [ { "key": "name", "name": "Name", "type": "single_line_text", "required": true }, { "key": "speciality", "name": "Speciality", "type": "single_line_text", "required": false }, { "key": "bio", "name": "Bio", "type": "multi_line_text", "required": false } ] }'{ "status": "success", "message": "Metaobject definition created", "data": { "p_id": 61, "type": "chef", "name": "Chef", "description": "The chefs behind our dishes.", "display_field": "name", "storefront_visible": true, "has_pages": true, "data_class": "content", "app_owned": false, "entry_cap_override": null, "retention_days": null, "fields": [ { "key": "name", "name": "Name", "type": "single_line_text", "required": true, "validations": [] }, { "key": "speciality", "name": "Speciality", "type": "single_line_text", "required": false, "validations": [] }, { "key": "bio", "name": "Bio", "type": "multi_line_text", "required": false, "validations": [] } ], "created_at": "2026-08-10T08:00:00.000000Z", "updated_at": "2026-08-10T08:00:00.000000Z" }}Requires scope merchant-metaobjects-read.
Lists the store’s metaobject entries.
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 <= 50Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.
Only entries of this metaobject type: the type handle of one of the store's definitions.
Only items with this status.
Free-text filter: only items matching this text are returned.
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/metaobjects?limit=2&type=chef&status=active" \ -H "X-Client-Key: {{merchantKey}}"{ "data": [ { "p_id": 1201, "type": "chef", "handle": "chef-morgan", "display_name": "Chef Morgan Ellis", "status": "active", "fields": { "name": "Chef Morgan Ellis", "speciality": "Smoked meats and slow-cooked sides", "bio": "Twenty years of New York party kitchens." }, "created_at": "2026-08-10T08:30:00.000000Z", "updated_at": "2026-09-02T16:45:00.000000Z" }, { "p_id": 1202, "type": "chef", "handle": "chef-priya", "display_name": "Chef Priya Shah", "status": "active", "fields": { "name": "Chef Priya Shah", "speciality": "Grills and street food", "bio": "Chicago-born grill master." }, "created_at": "2026-08-12T09:15:00.000000Z", "updated_at": "2026-08-12T09:15:00.000000Z" } ], "has_more": true, "next_cursor": "eyJpZCI6MTIwMiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ"}Requires scope merchant-metaobjects-create.
Creates a metaobject entry.
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 a metaobject entry on the REST developer surface.
Shape is checked first (type exists, handle is slug-shaped, status is
known). Each field value is then validated against its definition — an
unknown key or a wrong-typed value fails with a fields.{key} error.
Response Body
application/json
application/json
application/json
application/json
application/json
application/json
curl -X POST "https://example.com/metaobjects" \ -H "X-Client-Key: {{merchantKey}}" \ -H "Content-Type: application/json" \ -d '{ "type": "chef", "handle": "chef-morgan", "status": "active", "fields": { "name": "Chef Morgan Ellis", "speciality": "Smoked meats and slow-cooked sides", "bio": "Twenty years of New York party kitchens." } }'{ "status": "success", "message": "Metaobject entry created", "data": { "p_id": 1201, "type": "chef", "handle": "chef-morgan", "display_name": "Chef Morgan Ellis", "status": "active", "fields": { "name": "Chef Morgan Ellis", "speciality": "Smoked meats and slow-cooked sides", "bio": "Twenty years of New York party kitchens." }, "created_at": "2026-08-10T08:30:00.000000Z", "updated_at": "2026-08-10T08:30:00.000000Z" }}