Queek docs
Merchant endpoint reference

Metaobjects

GET
/metaobject-definitions

Requires scope merchant-metaobjects-read.

Lists the store’s metaobject definitions: its custom content types.

Authorization

merchantKey
X-Client-Key<token>

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

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 100
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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"}
POST
/metaobject-definitions

Requires scope merchant-metaobjects-create.

Creates a metaobject definition.

Authorization

merchantKey
X-Client-Key<token>

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

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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"  }}
GET
/metaobjects

Requires scope merchant-metaobjects-read.

Lists the store’s metaobject entries.

Authorization

merchantKey
X-Client-Key<token>

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

limit?|

Maximum number of items to return in one page.

Range1 <= value <= 50
starting_after?|

Cursor for the next page: pass next_cursor from the previous response unchanged. Keep walking while has_more is true.

type?|

Only entries of this metaobject type: the type handle of one of the store's definitions.

status?|

Only items with this status.

search?|

Free-text filter: only items matching this text are returned.

Header Parameters

X-Client-Key*string

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.

X-Request-Id?string

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"}
POST
/metaobjects

Requires scope merchant-metaobjects-create.

Creates a metaobject entry.

Authorization

merchantKey
X-Client-Key<token>

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

X-Client-Key*string

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.

X-Request-Id?string

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.

Idempotency-Key?string

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"  }}