Metaobjects

List metaobject definitions

Requires scope merchant-metaobjects-read.

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

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

limit?|

Range1 <= value <= 100

starting_after?string|null

Header Parameters

X-Client-Key*string

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.

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`

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

Create a metaobject definition

Requires scope merchant-metaobjects-create.

Creates a metaobject definition.

Authorization

merchantKey

X-Client-Key<token>

In: header

Header Parameters

X-Client-Key*string

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.

type*string

Match^[a-z][a-z0-9_]{1,63}$

Lengthlength <= 64

name*string

Lengthlength <= 120

description?|

Lengthlength <= 1000

display_field*string

Lengthlength <= 64

storefront_visible?boolean|null

has_pages?|

Whether entries of this type get their own public page at /{type}/{handle}. A type matching a reserved storefront route (cart, checkout, search and similar) is refused with a 422.

fields*array<>

Items1 <= items <= 20

data_class?|null

entry_cap_override?|

Range1 <= value <= 1000000

retention_days?|

Range1 <= value <= 3650

Response Body

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

List metaobjects

Requires scope merchant-metaobjects-read.

Lists the store’s metaobject entries.

Authorization

merchantKey

X-Client-Key<token>

In: header

Query Parameters

limit?|

Range1 <= value <= 50

starting_after?string|null

type?string|null

status?string|null

search?string|null

Header Parameters

X-Client-Key*string

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`

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-kemi",      "display_name": "Chef Kemi Adeyemi",      "status": "active",      "fields": {        "name": "Chef Kemi Adeyemi",        "speciality": "Party jollof and ofada",        "bio": "Twenty years of Lagos owambe kitchens."      },      "created_at": "2026-08-10T08:30:00.000000Z",      "updated_at": "2026-09-02T16:45:00.000000Z"    },    {      "p_id": 1202,      "type": "chef",      "handle": "chef-musa",      "display_name": "Chef Musa Bello",      "status": "active",      "fields": {        "name": "Chef Musa Bello",        "speciality": "Suya and grills",        "bio": "Kano-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"}

Create a metaobject

Requires scope merchant-metaobjects-create.

Creates a metaobject entry.

Authorization

merchantKey

X-Client-Key<token>

In: header

Header Parameters

X-Client-Key*string

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

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.

type*string

Lengthlength <= 64

handle?|

Match^[a-z0-9]+(?:-[a-z0-9]+)*$

Lengthlength <= 120

status?|

Value in

"active"
"draft"
null

fields*array<string>

Items1 <= items

Response Body

`application/json`

curl -X POST "https://example.com/metaobjects" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "type": "chef",    "handle": "chef-kemi",    "status": "active",    "fields": {      "name": "Chef Kemi Adeyemi",      "speciality": "Party jollof and ofada",      "bio": "Twenty years of Lagos owambe kitchens."    }  }'

{  "status": "success",  "message": "Metaobject entry created",  "data": {    "p_id": 1201,    "type": "chef",    "handle": "chef-kemi",    "display_name": "Chef Kemi Adeyemi",    "status": "active",    "fields": {      "name": "Chef Kemi Adeyemi",      "speciality": "Party jollof and ofada",      "bio": "Twenty years of Lagos owambe kitchens."    },    "created_at": "2026-08-10T08:30:00.000000Z",    "updated_at": "2026-08-10T08:30:00.000000Z"  }}

200application/json

401application/json

403application/json

422application/json

429application/json

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

200application/json

401application/json

403application/json

422application/json

429application/json

201application/json

401application/json

403application/json

409application/json

422application/json

429application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`