Queek docs
Merchant endpoint reference

Apps

PUT
/app/setup

Requires scope merchant-app_setup-update.

Stores the merchant-visible setup values for the calling installation (status plus the items sheet): the app calls this once its installation key is active. Full-body PUT — send the whole sheet every time.

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.

Store the calling installation's merchant-visible setup values (PUT app/setup). Call it once the installation's key is active.

Full-body PUT — send status plus the whole items sheet every time, so a retry replays instead of merging. Length limits apply per field; values that look like URLs must be https (a token-bearing http URL would train the merchant to paste secrets into cleartext).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/app/setup" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "status": "incomplete",    "items": [      {        "key": "webhook_url",        "label": "Example Kitchen webhook URL",        "value": "https://example-channel.apps.queek.app/hooks/1095",        "sensitive": false,        "copyable": true,        "instructions": "Paste this into the Example Kitchen vendor portal → Settings → Webhooks."      }    ]  }'
{  "status": "success",  "message": "Setup notice saved.",  "data": {    "setup": {      "status": "incomplete",      "items": [        {          "key": "webhook_url",          "label": "Example Kitchen webhook URL",          "value": "https://example-channel.apps.queek.app/hooks/1095",          "sensitive": false,          "copyable": true,          "instructions": "Paste this into the Example Kitchen vendor portal → Settings → Webhooks."        }      ],      "updated_at": "2026-09-24T12:00:00+01:00"    }  }}
POST
/app/payment-provider/signing-secret

Requires scope merchant-app_payment_secret-create.

Answers the signing secret (qcs_…) of the payment provider this private app runs for its store, ONCE: the app calls it after its install handoff answered 2xx and keeps the secret in its own secret store. It verifies every request Queek signs and signs every answer with it (the custom payment provider contract). The call never changes the provider; a second call answers 409 custom_gateway_secret_already_issued until the store owner re-issues the secret in Payments or the app is installed again, and a provider that is switched off answers 409 custom_gateway_secret_unavailable. Only the private app that wrote the provider can call it (every other caller answers 404). The same Idempotency-Key replays the first answer for 24 hours, even after the store owner re-issues the secret, so send a new Idempotency-Key on every pull and keep the secret you were given. The installation is the calling key’s; the scope is granted to every installation key.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/app/payment-provider/signing-secret" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Signing secret issued.",  "data": {    "signing_secret": "qcs_0123456789abcdef0123456789abcdef0123456789abcdef0123456789abcdef"  }}
GET
/app/metafields

Requires scope merchant-app_metafields-read.

Answers the calling installation’s own metafield values (app-data metafields): the app’s settings and state, stored in Queek instead of the app’s own database. Each value lives under an installation metafield definition the app created in its own app_{slug} namespace (POST metafield-definitions with owner_type installation). Only the installation that wrote them reads them: never the merchant’s dashboard, webhooks, the AI or another app. The one exception is a link-button link, which the storefront shows as the button’s href. They are deleted when the app is uninstalled; a reinstall starts empty. The installation is the calling key’s; the scope is granted to every installation key.

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.

Response Body

application/json

application/json

application/json

application/json

curl -X GET "https://example.com/app/metafields" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "App metafields",  "data": {    "metafields": {      "app_example_channel.busy_season_starts": "2026-12-01",      "app_example_channel.default_lead_days": 4    }  }}
PATCH
/app/metafields

Requires scope merchant-app_metafields-update.

Writes the calling installation’s own metafield values: metafields is a list of {namespace, key, value}. Each handle needs an installation metafield definition in the app’s own app_{slug} namespace (POST metafield-definitions with owner_type installation), values are type-checked against it (a date for a season start, an integer for a lead time), a handle you leave out keeps its value and "value": null deletes one. Not for secrets: keep credentials in the app’s own secret store. Answers every value the installation holds, as GET app/metafields does. The installation is the calling key’s; the scope is granted to every installation key.

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.

The calling installation's own data (GET / PATCH app/metafields): app-data metafields on the installation. The installation is the calling key's, never named in the request. A write is partial like every metafield write (a handle left out keeps its value, "value": null deletes it) and each handle needs an installation definition in the app's own app_{slug} namespace (POST metafield-definitions).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/app/metafields" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "metafields": [      {        "namespace": "app_example_channel",        "key": "default_lead_days",        "value": 4      },      {        "namespace": "app_example_channel",        "key": "busy_season_starts",        "value": "2026-12-01"      }    ]  }'
{  "status": "success",  "message": "App metafields saved.",  "data": {    "metafields": {      "app_example_channel.busy_season_starts": "2026-12-01",      "app_example_channel.default_lead_days": 4    }  }}
POST
/app/alerts

Requires scope merchant-app_alerts-create.

Pages the merchant through the bell (in-app only) for the calling installation: severity, title, message and an optional dedupe key that collapses repeats. Rate-limited per installation with 429 + Retry-After past the caps.

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.

Send an in-app notice to the installing merchant from the calling installation (POST app/alerts). The installation comes from the calling key — the body carries no target, so one installation can never alert on another installation's behalf.

Titles and messages are bell content by design: plain text, length-capped like the manifest listing fields, rendered escaped on every surface. The optional dedupe_key lets the app collapse repeats of one problem (one failing import batch, one expired credential) inside the TTL.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/app/alerts" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "severity": "warning",    "title": "Example Kitchen menu out of sync",    "message": "Two items on Example Kitchen no longer match a product in your store. Open the app to relink them.",    "dedupe_key": "menu-sync-1095"  }'
{  "status": "success",  "message": "Alert sent.",  "data": {    "type": "app_alert",    "severity": "warning",    "deduped": false,    "notification_id": "019a3c51-07a2-7d3e-9a41-5b8c2f0e6d17"  }}
PUT
/app/requirements

Requires scope merchant-app-requirements-write.

Replaces the calling installation product requirements map: which products require line properties under the installation namespace and which exact claim key each requires. Products are addressed by p_id, scoped to the calling installation vendor.

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.

The requirements sheet for the calling installation (PUT app/requirements): the app replaces its own {product → required line-property prefix} map in one call.

Full-body PUT — send the whole sheet every time, so a retry replays instead of merging and removals are explicit. Products are addressed by p_id (never UUID) and must belong to the calling installation's store. Each prefix must live under the installation's own app.{slug}. namespace.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/app/requirements" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "product_p_id": 20418,        "prefix": "app.booking."      }    ]  }'
{  "status": "success",  "message": "Requirements sheet saved.",  "data": {    "requirements": [      {        "product_p_id": 20418,        "prefix": "app.booking."      }    ]  }}
PUT
/app/line-inputs

Requires scope merchant-app-requirements-write.

Replaces the calling installation map of which products take shopper text on a line, and under which of the line_text fields its manifest declares: per product up to 3 fields, each by key with optional required (true or false) and max_length (a whole number, 1 to 500, never above the manifest value, which is 100 when the manifest sets none). The label always comes from the manifest. Send the whole sheet every time: a product left out loses its declaration, an empty items list removes them all, and an identical retry changes nothing. Products are addressed by p_id, scoped to the calling installation vendor; an unknown product or key refuses the whole sheet and keeps the old one. A key the manifest does not declare as line_text in the extensions the merchant granted is refused.

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.

The line-input sheet for the calling installation (PUT app/line-inputs): the app replaces its own {product -> shopper text fields} map in one call.

Full-body PUT, like the requirements sheet: send the whole sheet every time, so a retry replays and removals are explicit (an empty items removes every declaration of this installation). Products are addressed by p_id and must belong to the calling installation's store.

The manifest owns what a field IS: a key must be a line_text field of a block in the installation's GRANTED extensions, and the label always comes from it, never the body. The body only chooses, per product, which declared fields apply and whether each is required or tighter than the manifest's max_length (an effective max_length is the request's value, else the manifest's, else the default, and never above the manifest's).

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PUT "https://example.com/app/line-inputs" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "items": [      {        "product_p_id": 20418,        "fields": [          {            "key": "engraving",            "required": true,            "max_length": 30          }        ]      }    ]  }'
{  "status": "success",  "message": "Line inputs saved.",  "data": {    "line_inputs": [      {        "product_p_id": 20418,        "fields": [          {            "key": "engraving",            "label": "Engraving text",            "required": true,            "max_length": 30          }        ]      }    ]  }}
GET
/collected-definitions

Requires scope merchant-collected-definitions-manage.

Lists the collected definitions owned by the calling installation: the form types it created, ordered by type like the dashboard. Another installation’s types and merchant-held types never appear.

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/collected-definitions?limit=2" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "p_id": 74,      "type": "app_forms_12_catering_enquiry",      "name": "Catering enquiry",      "description": "Enquiries from the catering form.",      "display_field": "name",      "storefront_visible": false,      "has_pages": false,      "data_class": "collected",      "app_owned": false,      "entry_cap_override": null,      "retention_days": null,      "fields": [        {          "key": "name",          "name": "Name",          "type": "single_line_text",          "required": true,          "validations": []        },        {          "key": "event_date",          "name": "Event date",          "type": "date",          "required": true,          "validations": []        },        {          "key": "guests",          "name": "Guests",          "type": "integer",          "required": true,          "validations": []        }      ],      "created_at": "2026-09-15T09:00:00.000000Z",      "updated_at": "2026-09-15T09:00:00.000000Z"    }  ],  "has_more": true,  "next_cursor": "eyJpZCI6NzQsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0"}
POST
/collected-definitions

Requires scope merchant-collected-definitions-manage.

Creates a collected definition owned by the calling installation. The type must carry the installation’s own app_{slug}_{installation} prefix — anything else is refused with a 403. The data class is always collected and ownership is always the calling installation; neither is sent in the body.

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.

Manage the calling installation's form types (GET + POST collected-definitions, PATCH collected-definitions/{definition}).

One request shape serves all three verbs, with the same field-type, reserved-name, display and budget rules the dashboard enforces — every surface accepts the same definitions. Installation types carry the app_ prefix and declare it here. The data class is always collected and every definition belongs to the calling installation; neither is sent in the body.

Definitions are addressed by p_id within the installation's store. Types owned by another installation are refused with a 403.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/collected-definitions" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "type": "app_forms_12_catering_enquiry",    "name": "Catering enquiry",    "description": "Enquiries from the catering form.",    "display_field": "name",    "fields": [      {        "key": "name",        "name": "Name",        "type": "single_line_text",        "required": true      },      {        "key": "event_date",        "name": "Event date",        "type": "date",        "required": true      },      {        "key": "guests",        "name": "Guests",        "type": "integer",        "required": true      }    ]  }'
{  "status": "success",  "message": "Collected definition created",  "data": {    "p_id": 74,    "type": "app_forms_12_catering_enquiry",    "name": "Catering enquiry",    "description": "Enquiries from the catering form.",    "display_field": "name",    "storefront_visible": false,    "has_pages": false,    "data_class": "collected",    "app_owned": false,    "entry_cap_override": null,    "retention_days": null,    "fields": [      {        "key": "name",        "name": "Name",        "type": "single_line_text",        "required": true,        "validations": []      },      {        "key": "event_date",        "name": "Event date",        "type": "date",        "required": true,        "validations": []      },      {        "key": "guests",        "name": "Guests",        "type": "integer",        "required": true,        "validations": []      }    ],    "created_at": "2026-09-15T09:00:00.000000Z",    "updated_at": "2026-09-15T09:00:00.000000Z"  }}
PATCH
/collected-definitions/{definition}

Requires scope merchant-collected-definitions-manage.

Updates one of the calling installation’s collected definitions, addressed by p_id. The type is immutable; a type another installation or the merchant holds 403s.

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

Path Parameters

definition*string

Identifier of the definition, as returned by the Merchant API.

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.

Manage the calling installation's form types (GET + POST collected-definitions, PATCH collected-definitions/{definition}).

One request shape serves all three verbs, with the same field-type, reserved-name, display and budget rules the dashboard enforces — every surface accepts the same definitions. Installation types carry the app_ prefix and declare it here. The data class is always collected and every definition belongs to the calling installation; neither is sent in the body.

Definitions are addressed by p_id within the installation's store. Types owned by another installation are refused with a 403.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/collected-definitions/74" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "description": "Enquiries from the catering form on northwindgoods.example."  }'
{  "status": "success",  "message": "Collected definition updated",  "data": {    "p_id": 74,    "type": "app_forms_12_catering_enquiry",    "name": "Catering enquiry",    "description": "Enquiries from the catering form on northwindgoods.example.",    "display_field": "name",    "storefront_visible": false,    "has_pages": false,    "data_class": "collected",    "app_owned": false,    "entry_cap_override": null,    "retention_days": null,    "fields": [      {        "key": "name",        "name": "Name",        "type": "single_line_text",        "required": true,        "validations": []      },      {        "key": "event_date",        "name": "Event date",        "type": "date",        "required": true,        "validations": []      },      {        "key": "guests",        "name": "Guests",        "type": "integer",        "required": true,        "validations": []      }    ],    "created_at": "2026-09-15T09:00:00.000000Z",    "updated_at": "2026-09-24T15:40:00.000000Z"  }}
GET
/records

Requires scope merchant-collected-records-read.

Lists the calling installation's collected records newest submitted first, filterable by definition p_id, status and contact search.

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

definition?string

Only records of this definition: the integer id the definition carries. An unknown id, or one that belongs to another app, answers 404.

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.

status?|

Only items with this status.

search?|

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

Lengthlength <= 120

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/records?definition=74&limit=2&starting_after=WzEsIjAyNTRiNDZlMWU2YTIxZmM3M2ZiZTVkMTQ1NTk5MDM4OGFjYzFmNWRkNzY3ZDY1OWM2YmJkOTIwNzliZjU3MWEiLCJleUp6ZFdKdGFYUjBaV1JmWVhRaU9pSXlNREkyTFRBNUxUSTBJREUxT2pJd09qQXdJaXdpY0Y5cFpDSTZOVFV6TUN3aVgzQnZhVzUwYzFSdlRtVjRkRWwwWlcxeklqcDBjblZsZlEiXQ&status=new" \  -H "X-Client-Key: {{merchantKey}}"
{  "data": [    {      "p_id": 5530,      "definition_p_id": 74,      "type": "app_forms_12_catering_enquiry",      "status": "new",      "source": "app",      "submitted_at": "2026-09-24T14:20:00.000000Z",      "values": {        "name": "Riley Chen",        "event_date": "2026-11-22",        "guests": 250      },      "created_at": "2026-09-24T14:20:00.000000Z",      "updated_at": "2026-09-24T14:20:00.000000Z"    }  ],  "has_more": true,  "next_cursor": "WzEsIjAyNTRiNDZlMWU2YTIxZmM3M2ZiZTVkMTQ1NTk5MDM4OGFjYzFmNWRkNzY3ZDY1OWM2YmJkOTIwNzliZjU3MWEiLCJleUp6ZFdKdGFYUjBaV1JmWVhRaU9pSXlNREkyTFRBNUxUSTBJREUxT2pJd09qQXdJaXdpY0Y5cFpDSTZOVFV6TUN3aVgzQnZhVzUwYzFSdlRtVjRkRWwwWlcxeklqcDBjblZsZlEiXQ"}
POST
/records

Requires scope merchant-collected-records-submit.

Submits one record under one of the calling installation’s collected types. Values run the same field validation entries use; every record is filed with source app. Send an Idempotency-Key to make a retry safe: the same key and body replays the first answer instead of filing the record twice, the same key with a different body is 409; the header is optional. Creates are capped per installation at 30 a minute and 2000 a day (429 + Retry-After past either), on top of the per-definition storage cap of 5000 records. This is a form-submission path, not a bulk store: keep many small items inside one record’s values (up to 64 KiB) instead of one record each. Records appear in the merchant’s Submissions inbox under their definition, which is flagged app_owned.

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.

Submit one record under one of the calling installation's collected types (POST records).

Values are validated against the type's fields — the same field rules the dashboard enforces — and the per-definition storage cap is checked before anything is written. Every record is filed under the calling installation with source app: the body carries no source, so a submission can never be misfiled under another source. Calls are rate-limited per installation, and a validation failure (422) never consumes budget.

Types owned by another installation are refused with a 403. The Idempotency-Key header is optional: sent, a retry replays the first answer.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/records" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "definition": "app_forms_12_catering_enquiry",    "values": {      "name": "Riley Chen",      "event_date": "2026-11-22",      "guests": 250    }  }'
{  "status": "success",  "message": "Collected record submitted",  "data": {    "p_id": 5530,    "definition_p_id": 74,    "type": "app_forms_12_catering_enquiry",    "status": "new",    "source": "app",    "submitted_at": "2026-09-24T14:20:00.000000Z",    "values": {      "name": "Riley Chen",      "event_date": "2026-11-22",      "guests": 250    },    "created_at": "2026-09-24T14:20:00.000000Z",    "updated_at": "2026-09-24T14:20:00.000000Z"  }}
GET
/records/{record}

Requires scope merchant-collected-records-read.

Returns one record under a collected definition owned by the calling installation.

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

Path Parameters

record*string

Identifier of the metaobject record, as returned by the Merchant API.

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/records/5530" \  -H "X-Client-Key: {{merchantKey}}"
{  "status": "success",  "message": "Collected record",  "data": {    "p_id": 5530,    "definition_p_id": 74,    "type": "app_forms_12_catering_enquiry",    "status": "new",    "source": "app",    "submitted_at": "2026-09-24T14:20:00.000000Z",    "values": {      "name": "Riley Chen",      "event_date": "2026-11-22",      "guests": 250    },    "created_at": "2026-09-24T14:20:00.000000Z",    "updated_at": "2026-09-24T14:20:00.000000Z"  }}
PATCH
/records/{record}

Requires scope merchant-collected-records-update.

Replaces supplied values in full and/or triages a record under a collected definition owned by the calling installation.

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

Path Parameters

record*string

Identifier of the metaobject record, as returned by the Merchant API.

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.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X PATCH "https://example.com/records/5530" \  -H "X-Client-Key: {{merchantKey}}" \  -H "Content-Type: application/json" \  -d '{    "values": {      "name": "Riley Chen",      "event_date": "2026-11-22",      "guests": 250    }  }'
{  "status": "success",  "message": "Collected record updated",  "data": {    "p_id": 5530,    "definition_p_id": 74,    "type": "app_forms_12_catering_enquiry",    "status": "new",    "source": "app",    "submitted_at": "2026-09-24T14:20:00.000000Z",    "values": {      "name": "Riley Chen",      "event_date": "2026-11-22",      "guests": 250    },    "created_at": "2026-09-24T14:20:00.000000Z",    "updated_at": "2026-09-24T14:20:00.000000Z"  }}