{ "openapi": "3.1.0", "info": { "title": "Queek Merchant API", "version": "v1", "description": "Merchant API \u2014 Queek.\n\n## Errors\n\nEvery error answers `{\"error\": {\"code\", \"message\", \"field\"?, \"errors\"?, \"doc_url\", \"request_id\"}}`.\nSwitch on `error.code`, never on the message. Codes: `ai_unavailable_in_test_mode`, `api_key_expired`, `api_key_mode_mismatch`, `api_key_revoked`, `app_embed_not_ready`, `app_grant_insufficient`, `app_handoff_failed`, `app_installation_gone`, `app_installation_pending`, `app_ip_not_allowed`, `app_proxy_failed`, `app_proxy_gone`, `app_token_revoked`, `bad_request`, `channel_gateway_unreachable`, `client_key_required`, `conflict`, `custom_domain_provisioning_failed`, `custom_gateway_forbidden`, `custom_gateway_kyc_required`, `custom_gateway_not_configured`, `custom_gateway_not_verified`, `custom_gateway_plan_required`, `custom_gateway_store_ineligible`, `custom_gateway_verification_failed`, `forbidden`, `gone`, `idempotency_key_in_progress`, `idempotency_key_reuse`, `insufficient_scope`, `invalid_client`, `invalid_client_key`, `metafield_definition_missing`, `metafield_filter_unsupported_type`, `metafield_namespace_reserved`, `metafield_value_invalid`, `metaobject_definition_missing`, `metaobject_field_invalid`, `metaobject_reference_invalid`, `metaobject_type_reserved`, `method_not_allowed`, `not_found`, `origin_not_allowed`, `origin_required`, `payload_too_large`, `payment_amount_mismatch`, `plan_inactive`, `private_key_required`, `requires_slot`, `resync_cooldown`, `route_not_available`, `server_error`, `service_unavailable`, `subscription_feature_locked`, `too_many_requests`, `translation_digest_stale`, `translation_locale_is_primary`, `translation_max_published_locales`, `translation_unknown_key`, `translation_unknown_locale`, `unauthenticated`, `unknown_product_ref`, `unknown_service`, `unknown_variant_ref`, `unsupported_media_type`, `validation_failed`, `vendor_access_denied`, `vendor_mail_sender_forbidden`, `vendor_mail_sender_not_configured`, `vendor_mail_sender_plan_required`, `vendor_mail_sender_verification_failed`.\nEach error carries `doc_url` pointing at its own entry in the error reference, and `request_id` \u2014 always a\nstring \u2014 matching the `X-Request-Id` response header. Quote it in support.\n\n## Legacy top-level keys\n\nAdditive only, never a second contract: on error bodies the runtime still emits the pre-contract\ntop-level keys shipped clients read. `error_code` and `message` ride top-level on helper-produced refusals\n(the shared controller and ApiError error helpers, plus the client-auth handler branches);\n`request_id` and `doc_url` ride top-level ONLY on non-reissued controller-helper bodies (storefront, client,\ndeveloper and dashboard surfaces) \u2014 the Merchant API reissues refusals, so there they live inside `error`.\nThey are documented separately under `QueekLegacyErrorKeys`, which no operation references. New integrations\nswitch on `error.*`.\n\n## Request ids\n\nSend `X-Request-Id` (8\u2013128 chars matching `^[A-Za-z0-9_.:-]+$`) to correlate your trace with ours,\nor read the one we generate \u2014 it is echoed on every response, error bodies included, and appears on every log line\nof the request. `X-Queek-Api-Version` carries the API version (`v1`).\n\n## Idempotency\n\nSend `Idempotency-Key` on a write and a retry cannot execute twice. Same key + same body replays the stored\nresponse verbatim with `Idempotent-Replayed: true` for 24h. Same key + a different body is\n`409 idempotency_key_reuse`. A concurrent duplicate waits 15s for the first to finish, then replays;\npast that it is `409 idempotency_key_in_progress`. Responses \u2265 400 are not stored, so a failure stays retryable.\nThe slot is vendor + caller + METHOD:path + key. The body is the fingerprint, not part of the slot. Operations that accept the header document it as a parameter.\n\n## Rate limits\n\n180 requests/min per API key + IP, or storefront origin + IP when no key is sent. On top of that, a private (`sk_live_`) key carries its\nstore's plan quota: `free` 60/min, `social_media` 120/min, `starter` 120/min, `growth` 240/min, `scale` 1200/min, `enterprise` 2400/min. sk_live_ private keys only. A pk_live_ public key is shared by every visitor of the store, so it gets no per-store bucket.\nExceeding either is `too_many_requests` with `Retry-After`.\n\n## Webhooks\n\nSubscribe an endpoint per store and Queek posts the signed event to it. Topics are listed under `webhooks`\nin this document; the body is signed with the Standard Webhooks scheme \u2014 HMAC-SHA256 over the base64-decoded secret, value `v1,` \u2014\nover `{webhook-id}.{webhook-timestamp}.{raw body}`, tolerance 300s. A rotation keeps the previous secret valid for\n24h and sends both signatures, space delimited. Delivery is 8 attempts on a published backoff;\nan endpoint failing for 24h is disabled and the merchant notified. Every operation names the one scope it requires. A write scope also returns, in that write's own response, the record it wrote \u2014 listing or reading records needs the matching read scope. A key acts for its whole store, never only for the records one person created. Additive-only under v1: new operations, fields and enum values may be added, but existing operations, fields, values and auth behaviour never change incompatibly. A breaking change ships as v2 alongside v1, never in place.\n\n## Money\n\nEvery amount is a major-unit decimal string (`\"1500.00\"`), never a JSON float, always beside its `currency` code (ISO-4217).\n\n## Dates\n\nEvery `*_at` field is an ISO-8601 timestamp with numeric offset (`format: date-time`); the platform timezone is Africa/Lagos.\n\n## Deletes and creates\n\nDELETE answers `200` with the envelope (`{status, message, data}`), never `204`. Existing creates answer `200` and new creates answer `201` \u2014 both statuses are documented per operation and neither will change under you.", "x-queek-spec-sha": "3045fd9746859ca1d1ac7ac324be5133cf9ce940581e36c29c3dad7b85bebc8b" }, "servers": [ { "url": "https://api.usequeek.com/api/v1/merchant", "description": "Live \u2014 the base URL every example and Try-It call uses. Test keys (`sk_test_\u2026`) call this same base URL: a test key only ever reaches its dev store, a live key only its live store." } ], "tags": [ { "name": "Store" }, { "name": "Products" }, { "name": "Variants" }, { "name": "Images" }, { "name": "Collections" }, { "name": "Inventory" }, { "name": "Orders" }, { "name": "Customers" }, { "name": "Team" }, { "name": "Discounts" }, { "name": "Coupons" }, { "name": "Shipping zones" }, { "name": "Metafields" }, { "name": "Metaobjects" }, { "name": "Translations" }, { "name": "Content" }, { "name": "Apps" }, { "name": "Reviews" }, { "name": "Files" }, { "name": "Analytics" }, { "name": "Payments" } ], "security": [ { "merchantKey": [] } ], "paths": { "/analytics/traffic": { "get": { "operationId": "analytics.retrieve_traffic", "description": "Requires scope `merchant-analytics-traffic-read`.\n\nReads up to 30 days of anonymous storefront traffic for this store: daily views and visits, bot request count, and measurement metadata. Visits are not unique visitors because shared mobile networks can group shoppers. Bot requests count requests and are not views. Figures can lag live traffic by up to about ten minutes (daily totals refresh every five minutes and responses are cached for up to five); only the installed app's own key with this grant can use this route.", "summary": "Retrieve traffic analytics", "tags": [ "Analytics" ], "parameters": [ { "name": "days", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 30 }, "example": 30 }, { "name": "app_id", "in": "query", "schema": { "type": "string" } }, { "name": "installation_id", "in": "query", "schema": { "type": "string" } }, { "name": "source", "in": "query", "schema": { "type": "string" } }, { "name": "source_app_id", "in": "query", "schema": { "type": "string" } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Traffic retrieved." }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Traffic retrieved.", "data": { "range": { "days": 3, "start": "2026-10-01T00:00:00+01:00", "end": "2026-10-03T23:59:59+01:00" }, "cards": { "views": 31, "visits": 21, "bot_requests": 4 }, "charts": { "views_trend": [ { "date": "2026-10-01", "views": 10, "visits": 7 }, { "date": "2026-10-02", "views": 12, "visits": 8 }, { "date": "2026-10-03", "views": 9, "visits": 6 } ] }, "meta": { "collecting_since": "2026-09-20T00:00:00+01:00", "raw_retention_days": 14, "dedupe_window_minutes": 30 } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-analytics-traffic-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The days field must be at least 1.", "field": "days", "errors": { "days": [ "The days field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/app/setup": { "put": { "operationId": "app.setup_update", "description": "Requires scope `merchant-app_setup-update`.\n\nStores 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 \u2014 send the whole sheet every time.", "summary": "Update the installation setup notice", "tags": [ "Apps" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateAppSetupNoticeRequest" }, "example": { "status": "incomplete", "items": [ { "key": "webhook_url", "label": "Chowdeck webhook URL", "value": "https://apps.usequeek.com/chowdeck/hooks/1095", "sensitive": false, "copyable": true, "instructions": "Paste this into Chowdeck Vendor Portal \u2192 Settings \u2192 Webhooks." } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Setup notice saved." }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Setup notice saved.", "data": { "setup": { "status": "incomplete", "items": [ { "key": "webhook_url", "label": "Chowdeck webhook URL", "value": "https://apps.usequeek.com/chowdeck/hooks/1095", "sensitive": false, "copyable": true, "instructions": "Paste this into Chowdeck Vendor Portal \u2192 Settings \u2192 Webhooks." } ], "updated_at": "2026-09-24T12:00:00+01:00" } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-app_setup-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected status is invalid.", "field": "status", "errors": { "status": [ "The selected status is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/app/alerts": { "post": { "operationId": "app.alerts_create", "description": "Requires scope `merchant-app_alerts-create`.\n\nPages 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.", "summary": "Send a merchant alert", "tags": [ "Apps" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendAppAlertRequest" }, "example": { "severity": "warning", "title": "Chowdeck menu out of sync", "message": "Two items on Chowdeck no longer match a product in your store. Open the app to relink them.", "dedupe_key": "menu-sync-1095" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "enum": [ "Alert already sent.", "Alert sent." ] }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Alert sent.", "data": { "type": "app_alert", "severity": "warning", "deduped": false, "notification_id": "019a3c51-07a2-7d3e-9a41-5b8c2f0e6d17" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-app_alerts-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected severity is invalid.", "field": "severity", "errors": { "severity": [ "The selected severity is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/app/requirements": { "put": { "operationId": "app.requirements_write", "description": "Requires scope `merchant-app-requirements-write`.\n\nReplaces 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.", "summary": "Replace the installation requirements sheet", "tags": [ "Apps" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppRequirementStoreRequest" }, "example": { "items": [ { "product_p_id": 20418, "prefix": "app.booking." } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Requirements sheet saved." }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Requirements sheet saved.", "data": { "requirements": [ { "product_p_id": 20418, "prefix": "app.booking." } ] } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-app-requirements-write' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The prefix must live under the calling installation app namespace.", "field": "items.0.prefix", "errors": { "items.0.prefix": [ "The prefix must live under the calling installation app namespace." ], "items.0.product_p_id": [ "Product p_id 999999 was not found on this store." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/collected-definitions": { "get": { "operationId": "app.collected_definitions_list", "description": "Requires scope `merchant-collected-definitions-manage`.\n\nLists the collected definitions owned by the calling installation: the form types it created, ordered by type like the dashboard. Another installation\u2019s types and merchant-held types never appear.", "summary": "List the installation\u2019s collected definitions", "tags": [ "Apps" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MetaobjectDefinitionResource" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more", "next_cursor" ] }, "example": { "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", "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" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-definitions-manage' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "app.collected_definitions_create", "description": "Requires scope `merchant-collected-definitions-manage`.\n\nCreates a collected definition owned by the calling installation. The type must carry the installation\u2019s own app_{slug}_{installation} prefix \u2014 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.", "summary": "Create a collected definition", "tags": [ "Apps" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectedDefinitionRequest" }, "example": { "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 } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MetaobjectDefinitionResource" } }, "required": [ "status", "message", "data" ] }, "example": { "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", "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" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-definitions-manage' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The fields field is required.", "field": "fields", "errors": { "fields": [ "The fields field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/collected-definitions/{definition}": { "patch": { "operationId": "app.collected_definitions_update", "description": "Requires scope `merchant-collected-definitions-manage`.\n\nUpdates one of the calling installation\u2019s collected definitions, addressed by p_id. The type is immutable; a type another installation or the merchant holds 403s.", "summary": "Update a collected definition", "tags": [ "Apps" ], "parameters": [ { "name": "definition", "in": "path", "required": true, "schema": { "type": "string" }, "example": 74 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectedDefinitionRequest" }, "example": { "description": "Enquiries from the catering form on adeyemifoods.com." } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MetaobjectDefinitionResource" } }, "required": [ "status", "message", "data" ] }, "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 adeyemifoods.com.", "display_field": "name", "storefront_visible": false, "has_pages": false, "data_class": "collected", "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" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-definitions-manage' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Collected definition not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "A definition's type is immutable \u2014 delete and recreate it instead.", "field": "type", "errors": { "type": [ "A definition's type is immutable \u2014 delete and recreate it instead." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/records": { "post": { "operationId": "app.records_submit", "description": "Requires scope `merchant-collected-records-submit`.\n\nSubmits one record under one of the calling installation\u2019s collected types. Values run the same field validation entries use; every record is filed with source `app`. Rate-limited per installation with 429 + Retry-After past the caps, on top of the per-definition storage cap.", "summary": "Submit a collected record", "tags": [ "Apps" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollectedRecordSubmitRequest" }, "example": { "definition": "app_forms_12_catering_enquiry", "values": { "name": "Funmilayo Ogunleye", "event_date": "2026-11-22", "guests": 250 } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/CollectedRecordResource" } }, "required": [ "status", "message", "data" ] }, "example": { "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": "Funmilayo Ogunleye", "event_date": "2026-11-22", "guests": 250 }, "created_at": "2026-09-24T14:20:00.000000Z", "updated_at": "2026-09-24T14:20:00.000000Z" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-records-submit' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The values field must be an array.", "field": "values", "errors": { "values": [ "The values field must be an array." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "get": { "operationId": "app.records_list", "description": "Requires scope `merchant-collected-records-read`.\n\nLists the calling installation's collected records newest submitted first, filterable by definition p_id, status and contact search.", "summary": "List own collected records", "tags": [ "Apps" ], "parameters": [ { "name": "definition", "in": "query", "schema": { "type": "string" }, "example": 74 }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "WzEsIjAyNTRiNDZlMWU2YTIxZmM3M2ZiZTVkMTQ1NTk5MDM4OGFjYzFmNWRkNzY3ZDY1OWM2YmJkOTIwNzliZjU3MWEiLCJleUp6ZFdKdGFYUjBaV1JmWVhRaU9pSXlNREkyTFRBNUxUSTBJREUxT2pJd09qQXdJaXdpY0Y5cFpDSTZOVFV6TUN3aVgzQnZhVzUwYzFSdlRtVjRkRWwwWlcxeklqcDBjblZsZlEiXQ" }, { "name": "status", "in": "query", "schema": { "anyOf": [ { "$ref": "#/components/schemas/CollectedRecordStatus" }, { "type": "null" } ] }, "example": "new" }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 120 } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantCollectedRecord" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "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": "Funmilayo Ogunleye", "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" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-records-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The starting after cursor is invalid.", "field": "starting_after", "errors": { "starting_after": [ "The starting after cursor is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/records/{record}": { "get": { "operationId": "app.records_show", "description": "Requires scope `merchant-collected-records-read`.\n\nReturns one record under a collected definition owned by the calling installation.", "summary": "Read own collected record", "tags": [ "Apps" ], "parameters": [ { "name": "record", "in": "path", "required": true, "schema": { "type": "string" }, "example": 5530 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Collected record" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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": "Funmilayo Ogunleye", "event_date": "2026-11-22", "guests": 250 }, "created_at": "2026-09-24T14:20:00.000000Z", "updated_at": "2026-09-24T14:20:00.000000Z" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-records-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Collected record not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "patch": { "operationId": "app.records_update", "description": "Requires scope `merchant-collected-records-update`.\n\nReplaces supplied values in full and/or triages a record under a collected definition owned by the calling installation.", "summary": "Update own collected record", "tags": [ "Apps" ], "parameters": [ { "name": "record", "in": "path", "required": true, "schema": { "type": "string" }, "example": 5530 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AppCollectedRecordUpdateRequest" }, "example": { "values": { "name": "Funmilayo Ogunleye", "event_date": "2026-11-22", "guests": 250 } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Collected record updated" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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": "Funmilayo Ogunleye", "event_date": "2026-11-22", "guests": 250 }, "created_at": "2026-09-24T14:20:00.000000Z", "updated_at": "2026-09-24T14:20:00.000000Z" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collected-records-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Collected record not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The values field must be an array.", "field": "values", "errors": { "values": [ "The values field must be an array." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/collections": { "get": { "operationId": "collections.list", "description": "Requires scope `merchant-collections-read`.\n\nLists the store\u2019s collections.", "summary": "List collections", "tags": [ "Collections" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "eyJpZCI6MzEwOSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" }, { "name": "collection_mode", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "all" }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "sort_order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantCollection" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 3108, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "name": "Party Packs", "slug": "party-packs", "description": "Trays that feed a crowd.", "image": "https://media.usequeek.com/uploads/stores/1095/collections/party-packs.jpg", "logo": null, "featured": true, "position": 1, "collection_mode": "manual", "parent_uid": null, "products_count": 6, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-09-20T09:15:00+01:00" }, { "id": 3109, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b22", "name": "Drinks", "slug": "drinks", "description": "Chapman, zobo and fresh juices.", "image": null, "logo": null, "featured": false, "position": 2, "collection_mode": "smart", "parent_uid": null, "products_count": 3, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-09-20T09:15:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6MzEwOSwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collections-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected sort order is invalid.", "field": "sort_order", "errors": { "sort_order": [ "The selected sort order is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/collections/bulk": { "post": { "operationId": "collections.bulk_create", "description": "Requires scope `merchant-collections-create`.\n\nCreates several collections in one call.", "summary": "Create collections in bulk", "tags": [ "Collections" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCreateVendorCollectionsRequest" }, "example": { "collections": [ { "name": "On sale", "description": "Products currently on sale.", "collection_mode": "smart", "collection_rules": { "match": "all", "conditions": [ { "field": "compare_at_price", "operator": "gt", "value": 0 }, { "field": "on_sale", "operator": "eq", "value": true } ], "sort": "price_low", "limit": 50 } } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantCollection" } } }, "required": [ "success", "message", "data" ] }, "example": { "data": [ { "id": 3109, "uid": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b22", "name": "Drinks", "slug": "drinks", "description": "Chapman, zobo and fresh juices.", "image": null, "logo": null, "featured": false, "position": 2, "collection_mode": "smart", "parent_uid": null, "products_count": 3, "children": [], "created_at": "2026-07-01T12:00:00+01:00", "updated_at": "2026-07-01T12:00:00+01:00" } ], "success": true, "message": "Collections created successfully" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collections-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The collections field is required.", "field": "collections", "errors": { "collections": [ "The collections field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/collections/{collection}/products/pin": { "post": { "operationId": "collections.pin_product", "description": "Requires scope `merchant-collections-update`.\n\nPins a product to the top of a manual collection.", "summary": "Pin a product in a collection", "tags": [ "Collections" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" }, "example": 3108 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PinCollectionProductRequest" }, "example": { "product_id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "pinned": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "enum": [ "Product pinned in collection.", "Product unpinned from collection." ] }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Product pinned in collection.", "data": { "collection_id": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "product_id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "pinned": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collections-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Collection not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The product id field is required.", "field": "product_id", "errors": { "product_id": [ "The product id field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/collections/{collection}/products/reorder": { "post": { "operationId": "collections.reorder_products", "description": "Requires scope `merchant-collections-update`.\n\nReorders the products of a manual collection.", "summary": "Reorder products in a collection", "tags": [ "Collections" ], "parameters": [ { "name": "collection", "in": "path", "required": true, "schema": { "type": "string" }, "example": 3108 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReorderCollectionProductsRequest" }, "example": { "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b23" ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Collection products reordered successfully." }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Collection products reordered successfully.", "data": { "collection_id": "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21", "ordered_count": 2 } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-collections-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Collection not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The product ids field is required.", "field": "product_ids", "errors": { "product_ids": [ "The product ids field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/posts": { "get": { "operationId": "posts.list", "description": "Requires scope `merchant-posts-read`.\n\nLists the store\u2019s posts.", "summary": "List posts", "tags": [ "Content" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "page", "post", "gallery", null ] } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "draft", "published", null ] }, "example": "published" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantPost" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a2d11-5a6b-7c7d-8e9f-0a1b2c3d4e01", "parent_id": null, "blog_category_ids": [], "type": "post", "template": null, "slug": "how-we-smoke-our-party-jollof", "title": "How we smoke our party jollof", "content": [ { "type": "content", "data": { "markdown": "Every tray starts over firewood at 5am in our Lekki kitchen." } } ], "excerpt": "Firewood, patience and a lot of tomatoes.", "cover_image_url": "https://media.usequeek.com/uploads/stores/1095/posts/party-jollof.jpg", "status": "published", "tags": [ "jollof", "kitchen" ], "seo": { "title": "How we smoke our party jollof | Adeyemi Foods", "description": "Inside the Adeyemi Foods kitchen." }, "position": 1, "is_home": false, "chrome": "full", "show_page_title": true, "published_at": "2026-09-12T08:00:00+01:00", "created_at": "2026-09-10T16:20:00+01:00", "updated_at": "2026-09-12T08:00:00+01:00" }, { "id": "019a2d11-5a6b-7c7d-8e9f-0a1b2c3d4e02", "parent_id": null, "blog_category_ids": [], "type": "page", "template": null, "slug": "catering", "title": "Catering", "content": [ { "type": "content", "data": { "markdown": "We cater events of 50 to 2,000 guests across Lagos." } } ], "excerpt": "Owambe, office and wedding catering across Lagos.", "cover_image_url": "https://media.usequeek.com/uploads/stores/1095/posts/catering.jpg", "status": "published", "tags": [], "seo": { "title": "Event catering in Lagos | Adeyemi Foods", "description": "Owambe, office and wedding catering for 50 to 2,000 guests." }, "position": 2, "is_home": false, "chrome": "full", "show_page_title": true, "published_at": "2026-07-20T10:00:00+01:00", "created_at": "2026-07-19T18:00:00+01:00", "updated_at": "2026-08-30T12:10:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEyZDExLTVhNmItN2M3ZC04ZTlmLTBhMWIyYzNkNGUwMiIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-posts-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected type is invalid.", "field": "type", "errors": { "type": [ "The selected type is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "posts.create", "description": "Requires scope `merchant-posts-create`.\n\nCreates a markdown-body blog post (title required; draft unless published).", "summary": "Create post", "tags": [ "Content" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantStorePostRequest" }, "example": { "title": "How we smoke our party jollof", "body": "Every tray starts over firewood at 5am in our Lekki kitchen.", "excerpt": "Firewood, patience and a lot of tomatoes.", "status": "draft", "tags": [ "jollof", "kitchen" ], "cover_image_url": "https://adeyemifoods.com/images/posts/party-jollof.jpg", "seo": { "title": "How we smoke our party jollof | Adeyemi Foods", "description": "Inside the Adeyemi Foods kitchen." } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantPost" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Storefront post created", "data": { "id": "019a2d11-5a6b-7c7d-8e9f-0a1b2c3d4e01", "parent_id": null, "blog_category_ids": [], "type": "post", "template": null, "slug": "how-we-smoke-our-party-jollof", "title": "How we smoke our party jollof", "content": [ { "type": "content", "data": { "markdown": "Every tray starts over firewood at 5am in our Lekki kitchen." } } ], "excerpt": "Firewood, patience and a lot of tomatoes.", "cover_image_url": "https://media.usequeek.com/uploads/stores/1095/posts/party-jollof.jpg", "status": "published", "tags": [ "jollof", "kitchen" ], "seo": { "title": "How we smoke our party jollof | Adeyemi Foods", "description": "Inside the Adeyemi Foods kitchen." }, "position": 1, "is_home": false, "chrome": "full", "show_page_title": true, "published_at": "2026-09-12T08:00:00+01:00", "created_at": "2026-09-10T16:20:00+01:00", "updated_at": "2026-09-10T16:20:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-posts-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The title field is required.", "field": "title", "errors": { "title": [ "The title field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/posts/{post}": { "get": { "operationId": "posts.get", "description": "Requires scope `merchant-posts-detail`.\n\nGets one blog post by UUID or slug. {post} is a UUID or slug of this store.", "summary": "Get post", "tags": [ "Content" ], "parameters": [ { "name": "post", "in": "path", "required": true, "schema": { "type": "string" }, "example": "how-we-smoke-our-party-jollof" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantPost" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Storefront post retrieved", "data": { "id": "019a2d11-5a6b-7c7d-8e9f-0a1b2c3d4e01", "parent_id": null, "blog_category_ids": [], "type": "post", "template": null, "slug": "how-we-smoke-our-party-jollof", "title": "How we smoke our party jollof", "content": [ { "type": "content", "data": { "markdown": "Every tray starts over firewood at 5am in our Lekki kitchen." } } ], "excerpt": "Firewood, patience and a lot of tomatoes.", "cover_image_url": "https://media.usequeek.com/uploads/stores/1095/posts/party-jollof.jpg", "status": "published", "tags": [ "jollof", "kitchen" ], "seo": { "title": "How we smoke our party jollof | Adeyemi Foods", "description": "Inside the Adeyemi Foods kitchen." }, "position": 1, "is_home": false, "chrome": "full", "show_page_title": true, "published_at": "2026-09-12T08:00:00+01:00", "created_at": "2026-09-10T16:20:00+01:00", "updated_at": "2026-09-12T08:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-posts-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Post not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "put": { "operationId": "posts.update", "description": "Requires scope `merchant-posts-update`.\n\nUpdates a markdown-body blog post by UUID or slug (publish/unpublish via status). {post} is a UUID or slug of this store.", "summary": "Update post", "tags": [ "Content" ], "parameters": [ { "name": "post", "in": "path", "required": true, "schema": { "type": "string" }, "example": "how-we-smoke-our-party-jollof" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantUpdatePostRequest" }, "example": { "title": "How we smoke our party jollof", "body": "Every tray starts over firewood at 5am in our Lekki kitchen, and serves fifty.", "tags": [ "jollof", "kitchen" ], "status": "published" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantPost" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Storefront post updated", "data": { "id": "019a2d11-5a6b-7c7d-8e9f-0a1b2c3d4e01", "parent_id": null, "blog_category_ids": [], "type": "post", "template": null, "slug": "how-we-smoke-our-party-jollof", "title": "How we smoke our party jollof", "content": [ { "type": "content", "data": { "markdown": "Every tray starts over firewood at 5am in our Lekki kitchen." } } ], "excerpt": "Firewood, patience and a lot of tomatoes.", "cover_image_url": "https://media.usequeek.com/uploads/stores/1095/posts/party-jollof.jpg", "status": "published", "tags": [ "jollof", "kitchen" ], "seo": { "title": "How we smoke our party jollof | Adeyemi Foods", "description": "Inside the Adeyemi Foods kitchen." }, "position": 1, "is_home": false, "chrome": "full", "show_page_title": true, "published_at": "2026-09-12T08:00:00+01:00", "created_at": "2026-09-10T16:20:00+01:00", "updated_at": "2026-09-12T08:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-posts-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Post not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`. A state conflict answers code `conflict` with `data.reason` set to `slug_taken` (another post holds the slug), `rich_layout` (the rich editor owns this post) or `pending_draft` (unsynced draft changes).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected status is invalid.", "field": "status", "errors": { "status": [ "The selected status is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "delete": { "operationId": "posts.delete", "description": "Requires scope `merchant-posts-delete`.\n\nDeletes a blog post by UUID or slug. {post} is a UUID or slug of this store.", "summary": "Delete post", "tags": [ "Content" ], "parameters": [ { "name": "post", "in": "path", "required": true, "schema": { "type": "string" }, "example": "how-we-smoke-our-party-jollof" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "id": { "type": "string", "description": "The deleted post UUID." }, "slug": { "type": "string", "description": "The deleted post slug." }, "deleted": { "type": "boolean", "description": "Always true when this shape answers." } }, "required": [ "id", "slug", "deleted" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Storefront post deleted", "data": { "id": "019a2d11-5a6b-7c7d-8e9f-0a1b2c3d4e01", "slug": "how-we-smoke-our-party-jollof", "deleted": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-posts-delete' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Post not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`. A post with unsynced draft changes answers code `conflict` with `data.reason` set to `pending_draft`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/coupons": { "get": { "operationId": "coupons.list", "description": "Requires scope `merchant-coupons-read`.\n\nLists the store\u2019s coupons.", "summary": "List coupons", "tags": [ "Coupons" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 1 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "discount_type", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "percentage" }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "active" }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantCoupon" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01", "code": "LEKKI10", "title": "Lekki Launch 10% Off", "description": "10% off your first order from our Lekki kitchen.", "discount_type": "percentage", "discount_value": "10.00", "applies_to": "all_products", "target_product_ids": [], "target_category_ids": [], "minimum_order_amount": "5000.00", "capped_amount": null, "capped_amount_per_user": null, "usage_limit": 500, "usage_limit_per_user": 1, "used_count": 37, "is_active": true, "is_valid": true, "is_expired": false, "image_url": null, "starts_at": "2026-08-30T11:45:00+01:00", "expires_at": null, "created_at": "2026-08-30T11:45:00+01:00", "updated_at": "2026-09-24T09:10:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEyZTkxLTBiMWMtN2QyZS04ZjNhLTRiNWM2ZDdlOGYwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-coupons-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "coupons.create", "description": "Requires scope `merchant-coupons-create`.\n\nCreates a coupon.", "summary": "Create a coupon", "tags": [ "Coupons" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreCouponRequest" }, "example": { "title": "Lekki Launch 10% Off", "description": "10% off your first order from our Lekki kitchen.", "code": "LEKKI10", "discount_type": "percentage", "discount_value": 10, "minimum_order_amount": "5000.00", "applies_to": "all_products", "usage_limit": 500, "usage_limit_per_user": 1 } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantCoupon" } }, "required": [ "success", "message", "data" ] }, "example": { "success": true, "data": { "id": "019a2e91-0b1c-7d2e-8f3a-4b5c6d7e8f01", "code": "LEKKI10", "title": "Lekki Launch 10% Off", "description": "10% off your first order from our Lekki kitchen.", "discount_type": "percentage", "discount_value": "10.00", "applies_to": "all_products", "target_product_ids": [], "target_category_ids": [], "minimum_order_amount": "5000.00", "capped_amount": null, "capped_amount_per_user": null, "usage_limit": 500, "usage_limit_per_user": 1, "used_count": 0, "is_active": true, "is_valid": true, "is_expired": false, "image_url": null, "starts_at": "2026-08-30T11:45:00+01:00", "expires_at": null, "created_at": "2026-08-30T11:45:00+01:00", "updated_at": "2026-08-30T11:45:00+01:00" }, "message": "Coupon created successfully" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-coupons-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected discount type is invalid.", "field": "discount_type", "errors": { "discount_type": [ "The selected discount type is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/customers": { "get": { "operationId": "customers.list", "description": "Requires scope `merchant-customers-read`.\n\nLists customers with cursor pagination (`limit` up to 100 + `starting_after`, `has_more`/`next_cursor`); profile fields match customers/* webhooks and email_marketing_consent and sms_marketing_consent are present only with merchant-customers-contact-read. Use audience=campaign to include non-buyers; that mode requires the contact scope. not_opted_out means only that the person has not used Queek\u2019s email unsubscribe; it is not permission to send. An import that stores info.marketing_opt_in=false excludes that contact from campaign reachability.", "summary": "List customers", "tags": [ "Customers" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "from_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "to_date", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date" } }, { "name": "date_range", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "today", "this_week", "this_month", null ] } }, { "name": "audience", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "campaign", null ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "created_at", "updated_at", "joined_date", "name", "email", "phone", "p_id", "customer_orders_count", null ] }, "example": "created_at" }, { "name": "sort_order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] }, "example": "desc" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantCustomer" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 90342, "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a62", "name": "Tunde Bakare", "email": "tunde.bakare@yahoo.com", "phone": "+2348059876543", "avatar": null, "created_at": "2026-08-11T08:40:00+01:00", "updated_at": "2026-09-18T20:02:00+01:00", "email_marketing_consent": { "state": "not_opted_out", "consent_updated_at": null }, "sms_marketing_consent": { "state": "not_subscribed", "opt_in_level": null, "consent_updated_at": null } }, { "id": 90341, "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61", "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567", "avatar": null, "created_at": "2026-07-03T19:12:00+01:00", "updated_at": "2026-09-24T12:58:00+01:00", "email_marketing_consent": { "state": "not_opted_out", "consent_updated_at": null }, "sms_marketing_consent": { "state": "not_subscribed", "opt_in_level": null, "consent_updated_at": null } } ], "has_more": true, "next_cursor": "eyJpZCI6OTAzNDEsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-customers-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected date range is invalid.", "field": "date_range", "errors": { "date_range": [ "The selected date range is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/customers/followers": { "get": { "operationId": "customers.list_followers", "description": "Requires scope `merchant-customers-read`.\n\nLists the store\u2019s followers; a follower who is a customer carries its customer id. Contact shows only when shared or a customer, and is masked without the contact scope.", "summary": "List followers", "tags": [ "Customers" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantFollower" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a2f33-1a2b-7c3d-8e4f-5a6b7c8d9e02", "customer_id": null, "name": "Ngozi Eze", "email": "ngozi.eze@outlook.com", "phone": "+2348123456789", "avatar": "https://media.usequeek.com/uploads/avatars/ngozi-eze.jpg", "shared_contact": true, "is_customer": false, "followed_at": "2026-09-21T11:30:00+01:00" }, { "id": "019a2f33-1a2b-7c3d-8e4f-5a6b7c8d9e01", "customer_id": 90341, "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567", "avatar": "https://media.usequeek.com/uploads/avatars/chiamaka-obi.jpg", "shared_contact": false, "is_customer": true, "followed_at": "2026-07-03T19:15:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEyZjMzLTFhMmItN2MzZC04ZTRmLTVhNmI3YzhkOWUwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-customers-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/customers/{customer}": { "get": { "operationId": "customers.retrieve", "description": "Requires scope `merchant-customers-detail`.\n\nRetrieves one customer \u2014 the profile fields match customers/* webhooks; email_marketing_consent and sms_marketing_consent are present only with merchant-customers-contact-read. {customer} is this store\u2019s p_id, uid, or user id. Contact fields are masked without the contact scope.", "summary": "Retrieve a customer", "tags": [ "Customers" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "schema": { "type": "string" }, "example": 90341 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Customer retrieved" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Customer retrieved", "data": { "id": 90341, "uid": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a61", "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567", "avatar": null, "created_at": "2026-07-03T19:12:00+01:00", "updated_at": "2026-09-24T12:58:00+01:00", "email_marketing_consent": { "state": "not_opted_out", "consent_updated_at": null }, "sms_marketing_consent": { "state": "not_subscribed", "opt_in_level": null, "consent_updated_at": null } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-customers-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Customer not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/customers/{customer}/email-marketing-consent": { "post": { "operationId": "customers.update_email_marketing_consent", "description": "Requires scope `merchant-customers-consent-update`.\n\nRecords Queek email unsubscribe or app-reported opt-in evidence. Clearing a Queek unsubscribe re-enables the vendor\u2019s own campaign email. To clear it, send state=not_opted_out with source, opt_in_level and consent_updated_at strictly later than the stored unsubscribe and no later than the allowed clock skew; the customer must have a non-empty email. Otherwise the response is 422 with an email or consent_updated_at field error. state=unsubscribed needs no evidence fields. The 200 response contains only id and email_marketing_consent.", "summary": "Update customer email marketing consent", "tags": [ "Customers" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "schema": { "type": "string" }, "example": 90341 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateCustomerEmailMarketingConsentRequest" }, "example": { "state": "unsubscribed" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "email_marketing_consent": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unsubscribed", "not_opted_out" ] }, "opt_in_level": { "type": [ "string", "null" ] }, "consent_updated_at": { "type": "string" } }, "required": [ "state", "opt_in_level", "consent_updated_at" ] } }, "required": [ "id", "email_marketing_consent" ] }, "example": { "id": 90341, "email_marketing_consent": { "state": "unsubscribed", "opt_in_level": null, "consent_updated_at": "2026-10-04T10:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-customers-consent-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Customer not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. A missing email or consent_updated_at that is not strictly later than the stored unsubscribe or exceeds the allowed clock skew also returns 422 for state=not_opted_out.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected opt in level is invalid.", "field": "opt_in_level", "errors": { "opt_in_level": [ "The selected opt in level is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/customers/{customer}/sms-marketing-consent": { "post": { "operationId": "customers.update_sms_marketing_consent", "description": "Requires scope `merchant-customers-sms-consent-update`.\n\nRecords explicit app-reported SMS marketing consent for this customer. state=subscribed requires source, opt_in_level, consent_updated_at, and a valid phone number; state=unsubscribed needs no evidence fields or phone. Future unsubscribe timestamps are treated as the current time. The stored consent time never moves backward; an unsubscribe older than the existing time keeps the existing time. If an earlier subscribe time is still future-dated, the response may retain that time to preserve consent ordering. The 200 response contains only id and sms_marketing_consent. This operation does not send SMS.", "summary": "Update customer SMS marketing consent", "tags": [ "Customers" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "schema": { "type": "string" }, "example": 90341 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/UpdateCustomerSmsMarketingConsentRequest" }, { "type": "object", "properties": { "state": { "type": "string", "description": "Consent state: subscribed or unsubscribed. not_subscribed is read-only.", "examples": [ "unsubscribed" ] }, "source": { "type": "string", "description": "Source of explicit opt-in evidence. Required for subscribed; optional for unsubscribed. Accepted values: checkout, account, import, provider_sync, other.", "examples": [ "provider_sync" ] }, "consent_updated_at": { "type": "string", "description": "Required for subscribed. RFC3339 consent timestamp. Subscribe timestamps more than 120 seconds in the future are rejected. Future unsubscribe timestamps are treated as the current time; omitted time uses the current time except an unchanged unsubscribe is a no-op. The stored consent time never moves backward; an unsubscribe older than the existing time keeps the existing time.", "examples": [ "2026-10-04T10:00:00+01:00" ] }, "opt_in_level": { "type": "string", "description": "Required for subscribed: SINGLE_OPT_IN or CONFIRMED_OPT_IN. Not accepted for unsubscribed.", "examples": [ "SINGLE_OPT_IN" ] } }, "required": [ "state" ] } ] }, "example": { "state": "unsubscribed" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "id": { "type": "integer" }, "sms_marketing_consent": { "type": "string" } }, "required": [ "id", "sms_marketing_consent" ] }, "example": { "id": 90341, "sms_marketing_consent": { "state": "unsubscribed", "opt_in_level": null, "consent_updated_at": "2026-10-04T10:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-customers-sms-consent-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Customer not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. A missing or invalid phone and a consent time that exceeds the allowed clock skew or is not later than the existing consent also return 422.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected opt in level is invalid.", "field": "opt_in_level", "errors": { "opt_in_level": [ "The selected opt in level is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/customers/{customer}/wishlist-items": { "get": { "operationId": "customers.list_wishlist_items", "description": "Requires scope `merchant-customers-detail`.\n\nLists this store customer\u2019s saved products with cursor pagination at the price the storefront customer saw. The merchant and apps holding merchant-customers-detail can read these saved items.", "summary": "List customer wishlist items", "tags": [ "Customers" ], "parameters": [ { "name": "customer", "in": "path", "required": true, "schema": { "type": "string" }, "example": 90341 }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "eyJjdXN0b21lcl93aXNobGlzdF9pdGVtcy5jcmVhdGVkX2F0IjoiMjAyNi0wOS0yNCAxMjowMDowMCIsImN1c3RvbWVyX3dpc2hsaXN0X2l0ZW1zLmlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjI4IiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantWishlistItem" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "created_at": "2026-09-20T09:00:00.000000Z", "product": { "shop_id": "019a0b3a-af57-72d0-9c13-7036c3805892", "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "p_id": 20418, "title": "Homemade Chapman", "slug": "homemade-chapman", "excerpt": "Fresh Chapman with cucumber and orange slices.", "description": "Our house Chapman, mixed fresh every morning. Served chilled.", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "thumbnail_image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "video_url": null, "video_poster_url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "type": null, "commerce_mode": "shop", "currency": "NGN", "price": 2875, "discount_price": 2875, "compare_at_price": null, "is_price_from": true, "price_range": { "min": 2875, "max": 4830 }, "has_variants": true, "has_addons": false, "tax_inclusive": false, "discount": null, "discounts": [], "media": { "thumbnail": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "original": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "primary_variant_image": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } }, "primary_variant_image_variants": null, "images": [ { "id": 88220, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "alt": "Two bottles of chilled Chapman with cucumber slices", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "video_url": null, "video_poster_url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp" }, "inventory": { "in_stock": true, "tracking": true, "quantity": 60, "allow_backorder": false, "low_stock_threshold": 5, "updated_at": "2026-09-22 16:05:00" }, "variant_summary": { "count": 2, "min_price": 2875, "max_price": 4830, "total_stock": 60, "tracks_inventory": true, "in_stock": true }, "variants_count": 2, "rating": 4.8, "review_count": 14, "flags": { "featured": false, "is_marketplace": false, "is_new": false }, "metafields": {}, "created_at": "2026-07-15 11:30:00", "updated_at": "2026-09-22 16:05:00", "shop": { "id": "019a0b3a-af57-72d0-9c13-7036c3805892", "name": "Adeyemi Foods", "slug": "adeyemi-foods", "logo": "https://media.usequeek.com/uploads/stores/1095/logo.png", "rating": 4.8, "rating_count": 231 }, "addons": [], "taxonomy": { "categories": [], "tags": [], "brand": null, "collections": [] }, "purchase_limits": { "min_qty": 1, "max_qty": null, "step_qty": 1 }, "measurement": { "weight": null, "dimensions": null }, "specs": [], "options": [ { "name": "Size", "position": 0, "type": "size", "values": [ "50cl", "1 litre" ], "values_detailed": [ { "value": "50cl", "color_code": null, "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg" }, { "value": "1 litre", "color_code": null, "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg" } ] } ], "variants": [ { "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "ADF-CHP-50CL", "barcode": "6151101370016", "title": "50cl", "option_values": { "Size": "50cl" }, "price": 2875, "discount_price": 2875, "discount_amount": 0, "has_discount": false, "compare_at_price": null, "stock": 36, "track_inventory": true, "is_active": true, "in_stock": true, "weight": 0.55, "position": 0, "media": { "thumbnail": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "image_media_id": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } }, "images": [ { "id": 88220, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "alt": "Two bottles of chilled Chapman with cucumber slices", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "video_url": null, "source": "product" } }, { "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "barcode": "6151101370023", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": 4830, "discount_price": 4830, "discount_amount": 0, "has_discount": false, "compare_at_price": null, "stock": 24, "track_inventory": true, "is_active": true, "in_stock": true, "weight": 1.05, "position": 1, "media": { "thumbnail": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "image_media_id": null, "image_variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } }, "images": [ { "id": 88220, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "alt": "Two bottles of chilled Chapman with cucumber slices", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "video_url": null, "source": "product" } } ], "fulfillment": { "type": "delivery_or_pickup", "is_digital": false, "delivery_available": true, "pickup_available": true, "lead_time_min": null, "lead_time_max": null }, "compliance": { "warranty_months": 0, "country_of_origin": null, "safety_notes": null }, "seo": { "meta_title": null, "meta_description": null, "canonical_url": null, "keywords": [] }, "analytics": { "sales_count": 31, "view_count": 218, "favorite_count": 0, "review_count": 14 } }, "variant": { "id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "p_id": 7731, "title": "50cl", "option_values": { "Size": "50cl" } } } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWIwYzRkLTVlNmYtN2E4Yi05YzBkLTFlMmYzYTRiNWM5OSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-customers-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Customer not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must not be greater than 100.", "field": "limit", "errors": { "limit": [ "The limit field must not be greater than 100." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/discounts": { "get": { "operationId": "discounts.list", "description": "Requires scope `merchant-discounts-read`.\n\nLists the store\u2019s discounts with type, status and published filters.", "summary": "List discounts", "tags": [ "Discounts" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "percentage", "fixed", null ] } }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "active", "inactive", null ] }, "example": "active" }, { "name": "is_published", "in": "query", "schema": { "type": [ "boolean", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "campaign_type", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "all", "discount", "promotion", null ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantDiscount" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e02", "reference": "DSC-9P4R", "title": "Detty December \u20a62,000 Off", "description": "\u20a62,000 off party packs through December.", "type": "fixed", "value": "2000.00", "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21" ], "category_ids": [], "minimum_order_amount": "15000.00", "minimum_quantity": 1, "capped_amount": null, "capped_amount_per_user": null, "max_usage_total": null, "max_usage_per_user": 2, "usage_count": 0, "auto_apply": false, "status": "active", "is_active": true, "is_published": false, "image_url": null, "valid_from": "2026-12-01T00:00:00+01:00", "valid_until": "2026-12-31T23:59:00+01:00", "published_at": null, "created_at": "2026-09-24T10:00:00+01:00", "updated_at": "2026-09-24T10:00:00+01:00" }, { "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01", "reference": "DSC-8K2M", "title": "Party Pack Season 10% Off", "description": "10% off every party pack until the end of the year.", "type": "percentage", "value": "10.00", "product_ids": [], "category_ids": [ "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21" ], "minimum_order_amount": "10000.00", "minimum_quantity": 1, "capped_amount": "5000.00", "capped_amount_per_user": null, "max_usage_total": 1000, "max_usage_per_user": 5, "usage_count": 274, "auto_apply": true, "status": "active", "is_active": true, "is_published": true, "image_url": "https://media.usequeek.com/uploads/stores/1095/discounts/party-pack-season.jpg", "valid_from": "2026-09-01T00:00:00+01:00", "valid_until": "2026-12-31T23:59:00+01:00", "published_at": "2026-09-01T09:00:00+01:00", "created_at": "2026-08-29T15:20:00+01:00", "updated_at": "2026-09-01T09:00:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEyZTkwLTdhMWItN2MyZC05ZTNmLTRhNWI2YzdkOGUwMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-discounts-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must not be greater than 100.", "field": "limit", "errors": { "limit": [ "The limit field must not be greater than 100." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "discounts.create", "description": "Requires scope `merchant-discounts-create`.\n\nCreates a discount.", "summary": "Create a discount", "tags": [ "Discounts" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreDiscountRequest" }, "example": { "title": "Detty December \u20a62,000 Off", "description": "\u20a62,000 off party packs through December.", "type": "fixed", "value": "2000.00", "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21" ], "minimum_order_amount": "15000.00", "minimum_quantity": 1, "max_usage_per_user": 2, "valid_from": "2026-12-01T00:00:00+01:00", "valid_until": "2026-12-31T23:59:00+01:00", "is_active": true, "is_published": false, "auto_apply": false } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantDiscount" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Discount created successfully", "data": { "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e02", "reference": "DSC-9P4R", "title": "Detty December \u20a62,000 Off", "description": "\u20a62,000 off party packs through December.", "type": "fixed", "value": "2000.00", "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21" ], "category_ids": [], "minimum_order_amount": "15000.00", "minimum_quantity": 1, "capped_amount": null, "capped_amount_per_user": null, "max_usage_total": null, "max_usage_per_user": 2, "usage_count": 0, "auto_apply": false, "status": "active", "is_active": true, "is_published": false, "image_url": null, "valid_from": "2026-12-01T00:00:00+01:00", "valid_until": "2026-12-31T23:59:00+01:00", "published_at": null, "created_at": "2026-09-24T10:00:00+01:00", "updated_at": "2026-09-24T10:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-discounts-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "Discount type must be either percentage or fixed", "field": "type", "errors": { "type": [ "Discount type must be either percentage or fixed" ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/discounts/{discount}": { "get": { "operationId": "discounts.retrieve", "description": "Requires scope `merchant-discounts-detail`.\n\nRetrieves one discount: type, value, targeting, limits, usage and dates.", "summary": "Retrieve a discount", "tags": [ "Discounts" ], "parameters": [ { "name": "discount", "in": "path", "required": true, "schema": { "type": "string" }, "example": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantDiscount" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Discount retrieved successfully", "data": { "id": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01", "reference": "DSC-8K2M", "title": "Party Pack Season 10% Off", "description": "10% off every party pack until the end of the year.", "type": "percentage", "value": "10.00", "product_ids": [], "category_ids": [ "019a1c10-2b4d-7e8f-9a01-3c5d7e9f1b21" ], "minimum_order_amount": "10000.00", "minimum_quantity": 1, "capped_amount": "5000.00", "capped_amount_per_user": null, "max_usage_total": 1000, "max_usage_per_user": 5, "usage_count": 274, "auto_apply": true, "status": "active", "is_active": true, "is_published": true, "image_url": "https://media.usequeek.com/uploads/stores/1095/discounts/party-pack-season.jpg", "valid_from": "2026-09-01T00:00:00+01:00", "valid_until": "2026-12-31T23:59:00+01:00", "published_at": "2026-09-01T09:00:00+01:00", "created_at": "2026-08-29T15:20:00+01:00", "updated_at": "2026-09-01T09:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-discounts-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Discount not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/discounts/{discount}/publish": { "post": { "operationId": "discounts.publish", "description": "Requires scope `merchant-discounts-update`.\n\nPublishes a discount, making it usable.", "summary": "Publish a discount", "tags": [ "Discounts" ], "parameters": [ { "name": "discount", "in": "path", "required": true, "schema": { "type": "string" }, "example": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Discount published successfully" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Discount published successfully", "data": { "is_published": true, "published_at": "2026-09-01T09:00:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-discounts-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Discount not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/discounts/{discount}/unpublish": { "post": { "operationId": "discounts.unpublish", "description": "Requires scope `merchant-discounts-update`.\n\nUnpublishes a discount.", "summary": "Unpublish a discount", "tags": [ "Discounts" ], "parameters": [ { "name": "discount", "in": "path", "required": true, "schema": { "type": "string" }, "example": "019a2e90-7a1b-7c2d-9e3f-4a5b6c7d8e01" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Discount unpublished successfully" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Discount unpublished successfully", "data": { "is_published": false, "published_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-discounts-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Discount not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/files": { "get": { "operationId": "files.list", "description": "Requires scope `merchant-media-read`.\n\nLists original images uploaded by this app installation, newest first, with cursor pagination (`limit` + `starting_after`). Each image has the same `id`, `url` and `variants` shape as product images. Only this installation\u2019s uploads are visible.", "summary": "List app uploaded images", "tags": [ "Files" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 10 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantMedia" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 88214, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } }, "mime_type": "image/jpeg", "size": 0, "width": 1200, "height": 1200, "created_at": null } ], "has_more": true, "next_cursor": "eyJpZCI6ODgyMTQsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-media-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "files.create", "description": "Requires scope `merchant-media-create`.\n\nUploads one JPEG, PNG or WebP image as multipart/form-data using the `file` field. The image is added to the store media library and belongs to this app installation. Reuse its `id` with `media_id` on products/{product}/images. A same-byte retry without an Idempotency-Key returns the existing image.", "summary": "Upload an app image", "tags": [ "Files" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "description": "One JPEG, PNG or WebP image up to 10 MiB." } }, "required": [ "file" ] }, "example": { "file": "(binary image)" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MerchantMedia" } }, "required": [ "data" ] }, "example": { "data": { "id": 88214, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } }, "mime_type": "image/jpeg", "size": 0, "width": 1200, "height": 1200, "created_at": null } } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/MerchantMedia" } }, "required": [ "data" ] }, "example": { "data": { "id": 88214, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } }, "mime_type": "image/jpeg", "size": 0, "width": 1200, "height": 1200, "created_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-media-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The file field is required.", "field": "file", "errors": { "file": [ "The file field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products/{product}/images": { "get": { "operationId": "images.list", "description": "Requires scope `merchant-items-detail`.\n\nLists one product\u2019s images.", "summary": "List product images", "tags": [ "Images" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantProductImage" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } }, { "id": 88215, "is_primary": false, "position": 1, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides.jpg", "alt": "Grilled chicken and fried plantain on the side", "width": 1200, "height": 900, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-card.webp", "w": 480, "h": 360 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-card2x.webp", "w": 800, "h": 600 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-view.webp", "w": 1200, "h": 900 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-wa.jpg", "w": 1080, "h": 810 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides.jpg", "w": 1200, "h": 900 } } } ], "has_more": true, "next_cursor": "eyJpZCI6ODgyMTUsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "images.create", "description": "Requires scope `merchant-items-update`.\n\nAttaches a file-manager image to a product.", "summary": "Create a product image", "tags": [ "Images" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductImageRequest" }, "example": { "url": "https://adeyemifoods.com/images/jollof-rice-party-pack-sides.jpg", "primary": false } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantProductImage" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Image attached", "data": { "id": 88215, "is_primary": false, "position": 1, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides.jpg", "alt": "Grilled chicken and fried plantain on the side", "width": 1200, "height": 900, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-card.webp", "w": 480, "h": 360 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-card2x.webp", "w": 800, "h": 600 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-view.webp", "w": 1200, "h": 900 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-wa.jpg", "w": 1080, "h": 810 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides.jpg", "w": 1200, "h": 900 } } } } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantProductImage" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Image attached", "data": { "id": 88215, "is_primary": false, "position": 1, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides.jpg", "alt": "Grilled chicken and fried plantain on the side", "width": 1200, "height": 900, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-card.webp", "w": 480, "h": 360 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-card2x.webp", "w": 800, "h": 600 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-view.webp", "w": 1200, "h": 900 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides-wa.jpg", "w": 1080, "h": 810 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-sides.jpg", "w": 1200, "h": 900 } } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The media id field must be an integer.", "field": "media_id", "errors": { "media_id": [ "The media id field must be an integer." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products/{product}/images/{image}": { "patch": { "operationId": "images.update", "description": "Requires scope `merchant-items-update`.\n\nUpdates a product image, e.g. marking it primary.", "summary": "Update a product image", "tags": [ "Images" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "image", "in": "path", "required": true, "schema": { "type": "string" }, "example": 88214 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductImageRequest" }, "example": { "primary": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Primary image set" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Primary image set", "data": { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The primary field must be accepted.", "field": "primary", "errors": { "primary": [ "The primary field must be accepted." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Image not found on this product.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "delete": { "operationId": "images.delete", "description": "Requires scope `merchant-items-update`.\n\nDeletes a product image by media id, or `primary` for the primary image. Deleting the primary image makes the next image primary; the product is left without one only when it has no other images.", "summary": "Delete a product image", "tags": [ "Images" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "image", "in": "path", "required": true, "schema": { "type": "string" }, "example": 88215 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Image removed" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Image removed", "data": { "id": 88215, "deleted": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Image not found on this product.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/inventory": { "get": { "operationId": "inventory.overview", "description": "Requires scope `merchant-inventory-read`.\n\nRetrieves the store\u2019s inventory overview: product counts by stock state (tracked, in stock, out of stock, low, negative).", "summary": "Retrieve the inventory overview", "tags": [ "Inventory" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean" }, "data": { "$ref": "#/components/schemas/InventoryOverviewResource" } }, "required": [ "success", "data" ] }, "example": { "success": true, "data": { "total_products": 9, "tracked_products": 8, "untracked_products": 1, "in_stock": 8, "out_of_stock": 1, "low_stock": 2, "negative_stock": 0 } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-inventory-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/inventory/levels": { "get": { "operationId": "inventory.levels", "description": "Requires scope `merchant-inventory-read`.\n\nLists on-hand product and variant stock levels, ordered by product p_id. Filters product by p_id or slug and barcode by exact product OR variant barcode; when both are supplied they are ANDed. Unresolved product references return 404. Includes inactive variants and published or unpublished products; omits soft-deleted products. Each product lists all of its variants (no per-product cap); use a small `limit` for products with many variants. No per-location levels.", "summary": "List inventory levels", "tags": [ "Inventory" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "eyJwX2lkIjoyMDQxNywiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" }, { "name": "product", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "barcode", "in": "query", "schema": { "type": "string", "maxLength": 100 } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantInventoryLevels" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "p_id": 20418, "slug": "homemade-chapman", "barcode": null, "stock": 60, "effective_tracking": true, "variants": [ { "p_id": 7731, "sku": "ADF-CHP-50CL", "barcode": "615625300050", "title": "50cl", "stock": 36, "is_active": true, "effective_tracking": true }, { "p_id": 7732, "sku": "ADF-CHP-1L", "barcode": null, "title": "1 litre", "stock": 24, "is_active": true, "effective_tracking": true } ] } ], "has_more": true, "next_cursor": "eyJwX2lkIjoyMDQxOCwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-inventory-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/inventory/levels/adjustments": { "post": { "operationId": "inventory.adjust_level", "description": "Requires scope `merchant-inventory-update`.\n\nSets a tracked product or variant on-hand quantity with expected_stock compare-and-set, or applies a tracked delta, and writes an adjustment audit row with a configured reason code. Body product/variant references outside this store return 404. A stale expected_stock returns 409 with current_stock; refresh the level before retrying. Idempotency-Key is optional. One item per call; no per-location stock, bulk adjustments, purchase orders or forecasts, or check against open-order reservations.", "summary": "Adjust an inventory level", "tags": [ "Inventory" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantInventoryLevelAdjustmentRequest" }, "example": { "product": "20417", "mode": "set", "quantity": 44, "expected_stock": 42, "reason_code": "count" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantInventoryAdjustment" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Inventory level adjusted.", "data": { "result": "adjusted", "level": { "product_p_id": 20417, "variant_p_id": null, "mode": "set", "before": 42, "change": 2, "after": 44, "reason_code": "count" }, "adjustment": { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b13", "type": "adjustment", "quantity_before": 42, "quantity_change": 2, "quantity_after": 44, "reason": "Physical count", "reason_code": "count", "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack" }, "variant": null, "order": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-10-04T12:00:00+01:00" } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-inventory-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`. A stale `expected_stock` also answers 409, with `error.code` `conflict`: the level changed after you read it, and `data.current_stock` holds the current quantity. Read it, then retry with that value as `expected_stock`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected mode is invalid.", "field": "mode", "errors": { "mode": [ "The selected mode is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/inventory/products/{product}/history": { "get": { "operationId": "inventory.history", "description": "Requires scope `merchant-inventory-detail`.\n\nRetrieves the stock-movement history for one product.", "summary": "Retrieve product stock history", "tags": [ "Inventory" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantStockAdjustment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b11", "type": "sale", "quantity_before": 44, "quantity_change": -2, "quantity_after": 42, "reason": "Order 26-0924-58213", "reason_code": null, "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack" }, "variant": null, "order": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01" }, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T13:42:00+01:00" }, { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b10", "type": "restock", "quantity_before": 24, "quantity_change": 20, "quantity_after": 44, "reason": "Morning batch", "reason_code": null, "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack" }, "variant": null, "order": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T07:05:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEzYTBlLTZkMjEtN2I1NC04ZTkwLTJmNGE2YzhlMGIxMCIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-inventory-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found or not owned by your vendor", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/inventory/adjustments": { "post": { "operationId": "inventory.create_adjustment", "description": "Requires scope `merchant-inventory-update`.\n\nApplies a stock delta to products and writes the audit-trail entry. A single adjustment answers the stock-movement object (the history and audit rows list the same one); a bulk restock names each skipped product by id (p_id) and uid.", "summary": "Create a stock adjustment", "tags": [ "Inventory" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AdjustStockRequest" }, "example": { "product_ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22" ], "variant_id": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "quantity_change": 24, "type": "restock", "reason": "Afternoon batch" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "const": true }, "message": { "type": "string" }, "data": { "oneOf": [ { "$ref": "#/components/schemas/MerchantStockAdjustment" }, { "type": "object", "properties": { "requested_products": { "type": "integer" }, "adjusted_products": { "type": "integer" }, "skipped_products": { "type": "array", "items": { "type": "object", "properties": { "product": { "type": "object", "properties": { "id": { "type": "integer", "description": "The product p_id." }, "uid": { "type": "string", "description": "The product UUID." } }, "required": [ "id", "uid" ] }, "reason": { "type": "string" } }, "required": [ "product", "reason" ] } } }, "required": [ "requested_products", "adjusted_products", "skipped_products" ] } ] } }, "required": [ "success", "message", "data" ] }, "example": { "success": true, "message": "Stock adjusted successfully", "data": { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b12", "type": "restock", "quantity_before": 12, "quantity_change": 24, "quantity_after": 36, "reason": "Afternoon batch", "reason_code": null, "scope": "variant", "product": { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "slug": "homemade-chapman" }, "variant": { "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "title": "50cl", "option_values": { "Size": "50cl" } }, "order": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T15:30:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-inventory-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected type is invalid.", "field": "type", "errors": { "type": [ "The selected type is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "get": { "operationId": "inventory.list_adjustments", "description": "Requires scope `merchant-stock_adjustments-read`.\n\nLists stock adjustments: the store\u2019s stock audit trail.", "summary": "List stock adjustments", "tags": [ "Inventory" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "product_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "date_from", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" }, "example": "2026-09-24T00:00:00+01:00" }, { "name": "date_to", "in": "query", "schema": { "type": [ "string", "null" ], "format": "date-time" }, "example": "2026-09-24T23:59:59+01:00" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantStockAdjustment" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b12", "type": "restock", "quantity_before": 12, "quantity_change": 24, "quantity_after": 36, "reason": "Afternoon batch", "reason_code": null, "scope": "variant", "product": { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "slug": "homemade-chapman" }, "variant": { "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "title": "50cl", "option_values": { "Size": "50cl" } }, "order": null, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T15:30:00+01:00" }, { "id": "019a3a0e-6d21-7b54-8e90-2f4a6c8e0b11", "type": "sale", "quantity_before": 44, "quantity_change": -2, "quantity_after": 42, "reason": "Order 26-0924-58213", "reason_code": null, "scope": "product", "product": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack" }, "variant": null, "order": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01" }, "shortfall": { "captured": false, "quantity": 0 }, "created_at": "2026-09-24T13:42:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEzYTBlLTZkMjEtN2I1NC04ZTkwLTJmNGE2YzhlMGIxMSIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-stock_adjustments-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/metafield-definitions": { "get": { "operationId": "metafields.list_definitions", "description": "Requires scope `merchant-metafields-read`.\n\nLists the store\u2019s metafield definitions: its custom-field schema.", "summary": "List metafield definitions", "tags": [ "Metafields" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "owner_type", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Metafield definitions" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-metafields-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The owner type field must be a string.", "field": "owner_type", "errors": { "owner_type": [ "The owner type field must be a string." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "metafields.create_definition", "description": "Requires scope `merchant-metafields-create`.\n\nCreates a metafield definition.", "summary": "Create a metafield definition", "tags": [ "Metafields" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetafieldDefinitionRequest" }, "example": { "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" ] } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Metafield definition created" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-metafields-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected type is invalid.", "field": "type", "errors": { "type": [ "The selected type is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/metaobject-definitions": { "get": { "operationId": "metaobjects.list_definitions", "description": "Requires scope `merchant-metaobjects-read`.\n\nLists the store\u2019s metaobject definitions: its custom content types.", "summary": "List metaobject definitions", "tags": [ "Metaobjects" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Metaobject definitions" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-metaobjects-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "metaobjects.create_definition", "description": "Requires scope `merchant-metaobjects-create`.\n\nCreates a metaobject definition.", "summary": "Create a metaobject definition", "tags": [ "Metaobjects" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaobjectDefinitionRequest" }, "example": { "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 } ] } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Metaobject definition created" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-metaobjects-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "A type is lowercase letters, digits and underscores, starting with a letter (e.g. designer).", "field": "type", "errors": { "type": [ "A type is lowercase letters, digits and underscores, starting with a letter (e.g. designer)." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/metaobjects": { "get": { "operationId": "metaobjects.list", "description": "Requires scope `merchant-metaobjects-read`.\n\nLists the store\u2019s metaobject entries.", "summary": "List metaobjects", "tags": [ "Metaobjects" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 50 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "type", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "chef" }, { "name": "status", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "active" }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantMetaobject" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "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" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-metaobjects-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "metaobjects.create", "description": "Requires scope `merchant-metaobjects-create`.\n\nCreates a metaobject entry.", "summary": "Create a metaobject", "tags": [ "Metaobjects" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MetaobjectRequest" }, "example": { "type": "chef", "handle": "chef-kemi", "status": "active", "fields": { "name": "Chef Kemi Adeyemi", "speciality": "Party jollof and ofada", "bio": "Twenty years of Lagos owambe kitchens." } } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Metaobject entry created" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "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" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-metaobjects-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The type field is required.", "field": "type", "errors": { "type": [ "The type field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/orders": { "get": { "operationId": "orders.list", "description": "Requires scope `merchant-orders-read`.\n\nLists the store\u2019s orders using the same base object as orders/* webhooks; recorded payment transactions and Queek wallet-refund rows are present only with merchant-orders-read (webhooks include them only for active installations granted that scope). Order status, shipment, import, rider-assignment and patch responses do not include those finance arrays. Same filtering and search as the dashboard table with cursor pagination (`limit` + `starting_after`, `has_more`/`next_cursor`). Optional `updated_after` walks order rows changed after a timestamp, oldest change first; start each poll five minutes before the previous poll start, deduplicate ids, keep filters fixed and walk sequentially. With `updated_after`, `sort_by`, `sort_order`, `page` and `per_page` return 422; a cursor is bound to the same timestamp and filters. Item/property, shipment, metafield or customer-profile changes and deleted orders may be missed; long-running changes may appear late. The filter time is not returned and may differ from `updated_at`; this is not a snapshot or deletion feed. Provider-side, vendor-collected, offline and manual-review refunds without a recorded Queek refund row are omitted.", "summary": "List orders", "tags": [ "Orders" ], "parameters": [ { "name": "payment_status", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "paid", "unpaid", "refunded", "partial", "pending", "awaiting_confirmation", null ] }, "example": "paid" }, { "name": "delivery_method", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "delivery", "pickup", "instore", "shipping", null ] }, "example": "delivery" }, { "name": "registry_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "metafield[]", "in": "query", "schema": { "type": [ "array", "null" ], "items": { "type": "string" } } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "created_at", "updated_at", "status", "payment_status", "total", null ] } }, { "name": "sort_order", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "asc", "desc", null ] } }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "updated_after", "in": "query", "schema": { "type": "string" }, "example": "2026-10-03T11:55:00Z" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantOrder" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 58214, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a02", "order_number": "26-0924-58214", "status": "pending", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "third_party", "custom_channel": "chowdeck", "external_ref": "CD-7F3K2Q", "delivery_method": "delivery", "currency": "NGN", "subtotal": "5000.00", "discount_total": "0.00", "shipping_total": "1500.00", "tax_total": "0.00", "total": "6500.00", "customer": null, "shipping_address": { "address": null, "latitude": null, "longitude": null, "name": "Ifeoma Adebayo", "phone": "+2348091112233" }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "variant_title": "50cl", "quantity": 2, "unit_price": "2500.00", "total": "5000.00", "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-24T14:05:00+01:00", "updated_at": "2026-09-24T14:05:00+01:00", "fulfilled_at": null, "transactions": [ { "id": 992001, "type": "payment", "status": "success", "payment_method": "online", "payment_provider": "paystack", "amount": "35800.00", "currency": "NGN", "created_at": "2026-09-24T13:41:00+01:00" } ], "refunds": [ { "id": 992002, "transaction_id": 992001, "status": "success", "amount": "2500.00", "currency": "NGN", "created_at": "2026-09-24T14:20:00+01:00" } ] }, { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01", "order_number": "26-0924-58213", "status": "processing", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "custom_channel": null, "external_ref": null, "delivery_method": "delivery", "currency": "NGN", "subtotal": "37000.00", "discount_total": "3700.00", "shipping_total": "2500.00", "tax_total": "0.00", "total": "35800.00", "customer": { "id": 90341, "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567" }, "shipping_address": { "address": "7 Ologun Agbaje Street, Victoria Island, Lagos", "latitude": 6.4298, "longitude": 3.4219, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "variant_title": null, "quantity": 2, "unit_price": "18500.00", "total": "37000.00", "properties": { "gift.note": "Happy birthday, Tolu!" } } ], "note": "Leave with the gateman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null, "transactions": [ { "id": 992001, "type": "payment", "status": "success", "payment_method": "online", "payment_provider": "paystack", "amount": "35800.00", "currency": "NGN", "created_at": "2026-09-24T13:41:00+01:00" } ], "refunds": [ { "id": 992002, "transaction_id": 992001, "status": "success", "amount": "2500.00", "currency": "NGN", "created_at": "2026-09-24T14:20:00+01:00" } ] } ], "has_more": true, "next_cursor": "eyJpZCI6NTgyMTMsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. updated_after requires a real RFC3339 timestamp with an offset; February 31 and offsets beyond 23:59 are invalid. URL-encode `+` as `%2B` or use `Z`. Rows are returned oldest change first. With updated_after, sort_by, sort_order, page and per_page return 422; a cursor is bound to the same updated_after value and filters. For a previous poll started at 2026-10-03T12:00:00Z, begin the next poll at 2026-10-03T11:55:00Z and deduplicate by order id.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "sort_by must be one of: created_at, updated_at, status, payment_status, total.", "field": "sort_by", "errors": { "sort_by": [ "sort_by must be one of: created_at, updated_at, status, payment_status, total." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/orders/{order}": { "get": { "operationId": "orders.retrieve", "description": "Requires scope `merchant-orders-read`.\n\nRetrieves one order using the same base object as orders/* webhooks, with line items, customer, shipping address and shipment tracking. Recorded payment transactions and Queek wallet-refund rows are present only with merchant-orders-read (webhooks include them only for active installations granted that scope); status, shipment, import, rider-assignment and patch responses do not include those finance arrays. Provider-side, vendor-collected, offline and manual-review refunds without a recorded Queek refund row are omitted. {order} is a p_id or UUID of this store.", "summary": "Retrieve an order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "example": 58213 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Order retrieved" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Order retrieved", "data": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01", "order_number": "26-0924-58213", "status": "processing", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "custom_channel": null, "external_ref": null, "delivery_method": "delivery", "currency": "NGN", "subtotal": "37000.00", "discount_total": "3700.00", "shipping_total": "2500.00", "tax_total": "0.00", "total": "35800.00", "customer": { "id": 90341, "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567" }, "shipping_address": { "address": "7 Ologun Agbaje Street, Victoria Island, Lagos", "latitude": 6.4298, "longitude": 3.4219, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "variant_title": null, "quantity": 2, "unit_price": "18500.00", "total": "37000.00", "properties": { "gift.note": "Happy birthday, Tolu!" } } ], "note": "Leave with the gateman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null, "transactions": [ { "id": 992001, "type": "payment", "status": "success", "payment_method": "online", "payment_provider": "paystack", "amount": "35800.00", "currency": "NGN", "created_at": "2026-09-24T13:41:00+01:00" } ], "refunds": [ { "id": 992002, "transaction_id": 992001, "status": "success", "amount": "2500.00", "currency": "NGN", "created_at": "2026-09-24T14:20:00+01:00" } ] } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Order not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "patch": { "operationId": "orders.update", "description": "Requires scope `merchant-orders-update`.\n\nChanges an order\u2019s developer-extension fields only: metafields, metadata, and per-line properties (`line_items`: merged by key into each line\u2019s `properties`; a string sets a key, null deletes it, keys left out keep their value). `metafields` must reference an existing definition and never use an app-owned (`app.*`, `queek.*`) namespace here. `metadata` is free-form integrator bookkeeping \u2014 replaced wholesale (`null` clears it), capped in size and count, with no namespace rule and no definitions. Line-item property keys from an installation key must live under its own `app.{slug}.` namespace; any other key writes none under `app.*` or `queek.*`. Order state has its own endpoints. Answers the updated order.", "summary": "Update an order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "example": 58213 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VendorOrderExtensionRequest" }, "example": { "metadata": { "erp_id": "SO-104882" }, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "properties": { "gift.note": "Happy birthday, Tolu!", "gift.wrap": null } } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantOrder" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Order updated", "data": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01", "order_number": "26-0924-58213", "status": "processing", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "custom_channel": null, "external_ref": null, "delivery_method": "delivery", "currency": "NGN", "subtotal": "37000.00", "discount_total": "3700.00", "shipping_total": "2500.00", "tax_total": "0.00", "total": "35800.00", "customer": { "id": 90341, "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567" }, "shipping_address": { "address": "7 Ologun Agbaje Street, Victoria Island, Lagos", "latitude": 6.4298, "longitude": 3.4219, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "variant_title": null, "quantity": 2, "unit_price": "18500.00", "total": "37000.00", "properties": { "gift.note": "Happy birthday, Tolu!" } } ], "note": "Leave with the gateman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Order not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The metadata field must be an array.", "field": "metadata", "errors": { "metadata": [ "The metadata field must be an array." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/orders/import": { "post": { "operationId": "orders.import", "description": "Requires scope `merchant-orders-import`.\n\nRecords an order already charged by an outside platform: each item names its `product` (p_id, UUID or slug of this store) and, for a variant, its `variant` (p_id or UUID of a variant belonging to that product) \u2014 the old single `ref` is refused; totals are stored as charged with no commission, and a re-sent order returns the same record. The authenticated app installation supplies source attribution; apps other than the established Chowdeck and Glovo integrations omit `channel`, which is rejected if supplied. Chowdeck and Glovo keep their existing `channel` request contract. The customer (name + phone) becomes the order\u2019s `shipping_address` recipient, readable only with merchant-customers-contact-read like every contact \u2014 never `metadata`. Answers the order object orders/* webhooks send. Generic app installations derive source from the authenticated installation and omit `channel`; supplying it is a 422. An installed app with slug `chowdeck` or `glovo` must send its matching legacy `channel`; mismatches are 422. Human-key legacy imports still require `channel` and may choose either slug. Those slugs are not reserved.", "summary": "Import an order from a sales channel", "tags": [ "Orders" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportThirdPartyOrderRequest" }, "example": { "external_ref": "APP-7F3K2Q", "placed_at": "2026-09-24T13:05:00Z", "customer": { "name": "Ifeoma Adebayo", "phone": "+2348091112233" }, "items": [ { "product": "20418", "variant": "7731", "quantity": 2, "unit_price": 2500 } ], "delivery_fee": 1500, "discount": 0, "total": 6500, "fulfilment": "delivery" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Order already imported." }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Order already imported.", "data": { "id": 58214, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a02", "order_number": "26-0924-58214", "status": "pending", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "third_party", "custom_channel": "example-sales-app", "external_ref": "APP-7F3K2Q", "delivery_method": "delivery", "currency": "NGN", "subtotal": "5000.00", "discount_total": "0.00", "shipping_total": "1500.00", "tax_total": "0.00", "total": "6500.00", "customer": null, "shipping_address": { "address": null, "latitude": null, "longitude": null, "name": "Ifeoma Adebayo", "phone": "+2348091112233" }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "variant_title": "50cl", "quantity": 2, "unit_price": "2500.00", "total": "5000.00", "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-24T14:05:00+01:00", "updated_at": "2026-09-24T14:05:00+01:00", "fulfilled_at": null } } } } }, "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Example Sales App order imported.", "data": { "id": 58214, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a02", "order_number": "26-0924-58214", "status": "pending", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "third_party", "custom_channel": "example-sales-app", "external_ref": "APP-7F3K2Q", "delivery_method": "delivery", "currency": "NGN", "subtotal": "5000.00", "discount_total": "0.00", "shipping_total": "1500.00", "tax_total": "0.00", "total": "6500.00", "customer": null, "shipping_address": { "address": null, "latitude": null, "longitude": null, "name": "Ifeoma Adebayo", "phone": "+2348091112233" }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a12", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "variant_title": "50cl", "quantity": 2, "unit_price": "2500.00", "total": "5000.00", "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-24T14:05:00+01:00", "updated_at": "2026-09-24T14:05:00+01:00", "fulfilled_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-import' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. An item naming no product or variant of this store answers `unknown_product_ref` or `unknown_variant_ref` instead, with the reference in the message.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The items.0.quantity field must be at least 1.", "field": "items.0.quantity", "errors": { "items.0.quantity": [ "The items.0.quantity field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/orders/{order}/status": { "post": { "operationId": "orders.update_status", "description": "Requires scope `merchant-orders-status-update`.\n\nMoves an order to a new status and answers the updated order. `approve_payment` requires `payment_status` `awaiting_confirmation`, a payment method other than `online`/`wallet`, and a payment that is not already paid; cancelled or rejected orders cannot be updated. It marks the order paid but does not verify provider receipt or call a provider. `accept` and `rejected` need a paid, not-yet-accepted order; every later action needs a paid and accepted order.", "summary": "Update an order status", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "example": 58213 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorOrderStatusRequest" }, "example": { "status": "accept" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantOrder" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Order accepted", "data": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01", "order_number": "26-0924-58213", "status": "processing", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "custom_channel": null, "external_ref": null, "delivery_method": "delivery", "currency": "NGN", "subtotal": "37000.00", "discount_total": "3700.00", "shipping_total": "2500.00", "tax_total": "0.00", "total": "35800.00", "customer": { "id": 90341, "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567" }, "shipping_address": { "address": "7 Ologun Agbaje Street, Victoria Island, Lagos", "latitude": 6.4298, "longitude": 3.4219, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "variant_title": null, "quantity": 2, "unit_price": "18500.00", "total": "37000.00", "properties": { "gift.note": "Happy birthday, Tolu!" } } ], "note": "Leave with the gateman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-status-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected status is invalid.", "field": "status", "errors": { "status": [ "The selected status is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Order not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/orders/{order}/assign-rider": { "post": { "operationId": "orders.assign_rider", "description": "Requires scope `merchant-orders-status-update`.\n\nAssigns one of the store\u2019s active riders to a self-delivery order, or reassigns it. The order must be paid and confirmed with a rider delivery method; fleet and marketplace orders cannot be assigned here. Answers the updated order.", "summary": "Assign a rider to an order", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "example": 58213 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AssignOrderRiderRequest" }, "example": { "rider_id": "019a2b7c-4e11-7d90-a3b5-6c8d0e2f4a70" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantOrder" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Rider assigned", "data": { "id": 58213, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a01", "order_number": "26-0924-58213", "status": "processing", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "custom_channel": null, "external_ref": null, "delivery_method": "delivery", "currency": "NGN", "subtotal": "37000.00", "discount_total": "3700.00", "shipping_total": "2500.00", "tax_total": "0.00", "total": "35800.00", "customer": { "id": 90341, "name": "Chiamaka Obi", "email": "chiamaka.obi@gmail.com", "phone": "+2348031234567" }, "shipping_address": { "address": "7 Ologun Agbaje Street, Victoria Island, Lagos", "latitude": 6.4298, "longitude": 3.4219, "name": null, "phone": null }, "shipment": null, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a11", "product_id": 20417, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "variant_title": null, "quantity": 2, "unit_price": "18500.00", "total": "37000.00", "properties": { "gift.note": "Happy birthday, Tolu!" } } ], "note": "Leave with the gateman if no one answers.", "metafields": {}, "metadata": { "erp_id": "SO-104882" }, "created_at": "2026-09-24T13:40:00+01:00", "updated_at": "2026-09-24T13:52:00+01:00", "fulfilled_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-status-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The rider id field is required.", "field": "rider_id", "errors": { "rider_id": [ "The rider id field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Order not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/orders/{order}/shipment": { "patch": { "operationId": "orders.update_shipment", "description": "Requires scope `merchant-orders-update`.\n\nUpdates an order\u2019s shipment tracking (carrier, tracking number and URL, dates) and optionally advances it to shipped; answers the order with its `shipment` block.", "summary": "Update an order shipment", "tags": [ "Orders" ], "parameters": [ { "name": "order", "in": "path", "required": true, "schema": { "type": "string" }, "example": 58190 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateShipmentRequest" }, "example": { "carrier_name": "GIG Logistics", "tracking_number": "GIG-2026-0924-7719", "tracking_url": "https://giglogistics.com/track/GIG-2026-0924-7719", "status": "on_transit", "shipped_at": "2026-09-24T16:10:00+01:00", "estimated_delivery_at": "2026-09-26T18:00:00+01:00" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantOrder" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Shipment updated", "data": { "id": 58190, "uid": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a03", "order_number": "26-0923-58190", "status": "on_transit", "payment_status": "paid", "payment_method": "online", "fulfillment_status": "unfulfilled", "cancelled": false, "cancel_reason": null, "channel": null, "platform": "storefront", "custom_channel": null, "external_ref": null, "delivery_method": "shipping", "currency": "NGN", "subtotal": "25200.00", "discount_total": "0.00", "shipping_total": "6650.00", "tax_total": "0.00", "total": "31850.00", "customer": { "id": 90342, "name": "Tunde Bakare", "email": "tunde.bakare@yahoo.com", "phone": "+2348059876543" }, "shipping_address": { "address": "22 Bompai Road, Nassarawa, Kano", "latitude": 12.0107, "longitude": 8.5387, "name": null, "phone": null }, "shipment": { "carrier_name": "GIG Logistics", "tracking_number": "GIG-2026-0924-7719", "tracking_url": "https://giglogistics.com/track/GIG-2026-0924-7719", "zone_name": "Nationwide", "shipped_at": "2026-09-24T16:10:00+01:00", "estimated_delivery_at": "2026-09-26T18:00:00+01:00", "delivered_at": null }, "line_items": [ { "id": "019a3a0e-1c2d-7e3f-8a4b-5c6d7e8f9a13", "product_id": 20418, "product_uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "variant_title": "1 litre", "quantity": 6, "unit_price": "4200.00", "total": "25200.00", "properties": {} } ], "note": null, "metafields": {}, "metadata": {}, "created_at": "2026-09-23T18:22:00+01:00", "updated_at": "2026-09-24T16:10:00+01:00", "fulfilled_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-orders-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The tracking url field must be a valid URL.", "field": "tracking_url", "errors": { "tracking_url": [ "The tracking url field must be a valid URL." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Order not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/payouts": { "get": { "operationId": "payouts.list", "description": "Requires scope `merchant-payout-batches-read`.\n\nLists released daily seller settlement batches with cursor pagination. Each payout id is its YYYY-MM-DD settlement date. Only order settlement credits are included; bank withdrawals and rider settlements are not exposed.", "summary": "List seller settlement batches", "tags": [ "Payments" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 10 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantPayoutBatch" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "2026-09-24", "settlement_date": "2026-09-24", "total_amount": "33300.00", "currency": "NGN", "order_count": 1, "first_posted_at": "2026-09-24T15:00:00+01:00", "last_posted_at": "2026-09-24T15:00:00+01:00" } ], "has_more": true, "next_cursor": "WzEsImUzMDI2MWU4ZWQ5YzI4NWFlMDMwN2Q3M2RjOGQxMjgyNTU0NWQ5N2M5M2FkNWEyMGRmYmFlOWJmOGY0MjU1ZDAiLCJleUp6WlhSMGJHVnRaVzUwWDJSaGRHVWlPaUl5TURJMkxUQTVMVEkwSWl3aVgzQnZhVzUwYzFSdlRtVjRkRWwwWlcxeklqcDBjblZsZlEiXQ" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-payout-batches-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/payouts/{payout}": { "get": { "operationId": "payouts.retrieve", "description": "Requires scope `merchant-payout-batches-read`.\n\nRetrieves one released daily seller settlement batch and up to 100 of its order entries. `orders_has_more` is true when additional entries were omitted. The payout id is its YYYY-MM-DD settlement date. Batch timestamps and each entry\u2019s `posted_at` are ISO-8601. Bank withdrawals, individual bank-withdrawal payout ids and rider settlements are not exposed.", "summary": "Retrieve a seller settlement batch", "tags": [ "Payments" ], "parameters": [ { "name": "payout", "in": "path", "required": true, "schema": { "type": "string" }, "example": "2026-09-24" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Payout retrieved" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Payout retrieved", "data": { "id": "2026-09-24", "settlement_date": "2026-09-24", "total_amount": "33300.00", "currency": "NGN", "order_count": 1, "first_posted_at": "2026-09-24T15:00:00+01:00", "last_posted_at": "2026-09-24T15:00:00+01:00", "orders": [ { "order_id": 58213, "order_number": "26-0924-58213", "amount": "33300.00", "posted_at": "2026-09-24T15:00:00+01:00" } ], "orders_has_more": false } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-payout-batches-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Payout not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products": { "get": { "operationId": "products.list", "description": "Requires scope `merchant-items-read`.\n\nLists the store\u2019s products \u2014 the same object products/* webhooks send, with variants, images, the canonical URL and the storefront price. Same filtering as the dashboard table with cursor pagination (`limit` + `starting_after`, `has_more`/`next_cursor`); sorts limited to public fields. Optional `updated_after` walks product rows changed after a timestamp, oldest change first; start each poll five minutes before the previous poll start, deduplicate ids, keep filters fixed and walk sequentially. With `updated_after`, `sort_by`, `sort_order`, `page` and `per_page` return 422; a cursor is bound to the same timestamp and filters. Variant, image, metafield, stock, region, price, discount, bulk publish, unpublish, archive status or inventory-tracking changes and deleted products may be missed; long-running changes may appear late. The filter time is not returned and may differ from `updated_at`; this is not a snapshot or deletion feed.", "summary": "List products", "tags": [ "Products" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "sort_by", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "created_at", "updated_at", "title", "price", "stock", "published", null ] } }, { "name": "sort_order", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "category_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "taxonomy_category_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "collection_category_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "stock_status", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "in_stock" }, { "name": "import_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "batch_id", "in": "query", "schema": { "type": [ "string", "null" ], "format": "uuid" } }, { "name": "channel", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "is_marketplace", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "0", "1", "true", "false", null ] } }, { "name": "is_wholesale", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "0", "1", "true", "false", null ] } }, { "name": "metafield[]", "in": "query", "schema": { "type": [ "array", "null" ], "items": { "type": "string" } } }, { "name": "updated_after", "in": "query", "schema": { "type": "string" }, "example": "2026-10-03T11:55:00Z" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantProduct" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "slug": "homemade-chapman", "excerpt": "Fresh Chapman with cucumber and orange slices.", "description": "Our house Chapman, mixed fresh every morning. Served chilled.", "status": "active", "published": true, "in_stock": true, "price": "2500.00", "storefront_price": "2500.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "currency": "NGN", "sku": "ADF-CHP-000", "barcode": null, "stock": 60, "track_inventory": true, "is_digital": false, "has_variants": true, "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "variants": [ { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "ADF-CHP-50CL", "barcode": "6151101370016", "title": "50cl", "option_values": { "Size": "50cl" }, "price": "2500.00", "storefront_price": "2500.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 36, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 0.55, "position": 0, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" }, { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "barcode": "6151101370023", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": "4200.00", "storefront_price": "4200.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" } ], "options": [ { "name": "Size", "position": 0, "values": [ "50cl", "1 litre" ] } ], "images": [ { "id": 88220, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "alt": "Two bottles of chilled Chapman with cucumber slices", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }, { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "status": "active", "published": true, "in_stock": true, "price": "18500.00", "storefront_price": "16650.00", "storefront_compare_at_price": "18500.00", "url": "https://adeyemifoods.com/products/jollof-rice-party-pack", "currency": "NGN", "sku": "ADF-JRP-001", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "is_digital": false, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "variants": [], "options": [], "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null } ], "has_more": true, "next_cursor": "eyJpZCI6MjA0MTcsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. updated_after requires a real RFC3339 timestamp with an offset; February 31 and offsets beyond 23:59 are invalid. URL-encode `+` as `%2B` or use `Z`. Rows are returned oldest change first. With updated_after, sort_by, sort_order, page and per_page return 422; a cursor is bound to the same updated_after value and filters. For a previous poll started at 2026-10-03T12:00:00Z, begin the next poll at 2026-10-03T11:55:00Z and deduplicate by product id. Bulk publish, unpublish, archive status and inventory-tracking changes may not appear in this poll.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The starting after cursor is invalid.", "field": "starting_after", "errors": { "starting_after": [ "The starting after cursor is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "products.create", "description": "Requires scope `merchant-items-create`.\n\nCreates a product with variants, images, categories and metafields; answers the created product \u2014 the same object GET products/{product} and products/* webhooks send.", "summary": "Create a product", "tags": [ "Products" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "title": "Jollof Rice Party Pack", "price": "18500.00", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "metadata": { "erp_id": "ERP-20417" }, "image_url": "https://adeyemifoods.com/images/jollof-rice-party-pack.jpg" } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantProduct" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "product updated", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "status": "active", "published": true, "in_stock": true, "price": "18500.00", "storefront_price": "16650.00", "storefront_compare_at_price": "18500.00", "url": "https://adeyemifoods.com/products/jollof-rice-party-pack", "currency": "NGN", "sku": "ADF-JRP-001", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "is_digital": false, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "variants": [], "options": [], "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-07-14T10:20:00+01:00", "deleted_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The title field is required.", "field": "title", "errors": { "title": [ "The title field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/storefront/search": { "get": { "operationId": "products.search", "description": "Requires scope `merchant-items-read`.\n\nSearches this store\u2019s shopper-visible products by keyword, availability or metafields. Results use storefront prices and cursor pagination. Keyword matching is case-sensitive; percent and underscore are wildcards.", "summary": "Search storefront products", "tags": [ "Products" ], "parameters": [ { "name": "keyword", "in": "query", "schema": { "type": [ "string", "null" ], "minLength": 2, "maxLength": 100 }, "example": "jollof" }, { "name": "in_stock", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "0", "1", "true", "false", null ] }, "example": "1" }, { "name": "metafield[]", "in": "query", "description": "The handle itself contains a dot, so Laravel's `metafield.*`\nwildcard treats it as a nested path and does not reliably validate\nthe literal map key. Validate each handle/value at the map level.", "schema": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 5 } }, { "name": "sort", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "latest", "popular", "price_low", "price_high", null ] }, "example": "latest" }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "description": "StorefrontCursor's signed envelope is not Laravel's raw Cursor.", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantProduct" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 20418, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22", "title": "Homemade Chapman", "slug": "homemade-chapman", "excerpt": "Fresh Chapman with cucumber and orange slices.", "description": "Our house Chapman, mixed fresh every morning. Served chilled.", "status": "active", "published": true, "in_stock": true, "price": "2500.00", "storefront_price": "2500.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "currency": "NGN", "sku": "ADF-CHP-000", "barcode": null, "stock": 60, "track_inventory": true, "is_digital": false, "has_variants": true, "image": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "variants": [ { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "ADF-CHP-50CL", "barcode": "6151101370016", "title": "50cl", "option_values": { "Size": "50cl" }, "price": "2500.00", "storefront_price": "2500.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 36, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 0.55, "position": 0, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" }, { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "barcode": "6151101370023", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": "4200.00", "storefront_price": "4200.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" } ], "options": [ { "name": "Size", "position": 0, "values": [ "50cl", "1 litre" ] } ], "images": [ { "id": 88220, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "alt": "Two bottles of chilled Chapman with cucumber slices", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/homemade-chapman.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": {}, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null }, { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "status": "active", "published": true, "in_stock": true, "price": "18500.00", "storefront_price": "16650.00", "storefront_compare_at_price": "18500.00", "url": "https://adeyemifoods.com/products/jollof-rice-party-pack", "currency": "NGN", "sku": "ADF-JRP-001", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "is_digital": false, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "variants": [], "options": [], "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null } ], "has_more": true, "next_cursor": "WzEsIjQ4NWY2NTk0YzYxODA3NmVmMDYxZWIwZjc2MGZlNGFiOWY0MGE0NzE3MGYzZTU2N2I4NDUzZTYwNzQwNGNiODIiLCJleUp3Y205a2RXTjBjeTVqY21WaGRHVmtYMkYwSWpvaU1qQXlOaTB3TnkweE5DQXhNRG95TURvd01DSXNJbkJ5YjJSMVkzUnpMbWxrSWpvaU1ERTVZVEZrTlRJdE0yTTRaUzAzWmpReExXSXdaREl0Tm1FelpUbGpNV1kwWWpJeElpd2lYM0J2YVc1MGMxUnZUbVY0ZEVsMFpXMXpJanAwY25WbGZRIl0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. An undefined metafield handle also answers 422 with the metafield_definition_missing code and the handle in its error details.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The starting after cursor is invalid.", "field": "starting_after", "errors": { "starting_after": [ "The starting after cursor is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products/{product}": { "get": { "operationId": "products.retrieve", "description": "Requires scope `merchant-items-detail`.\n\nRetrieves one product \u2014 the same object products/* webhooks send, with variants, images, the canonical URL and the storefront price. {product} is a p_id, UUID or slug of this store.", "summary": "Retrieve a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "product" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "product", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "status": "active", "published": true, "in_stock": true, "price": "18500.00", "storefront_price": "16650.00", "storefront_compare_at_price": "18500.00", "url": "https://adeyemifoods.com/products/jollof-rice-party-pack", "currency": "NGN", "sku": "ADF-JRP-001", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "is_digital": false, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "variants": [], "options": [], "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "product not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "put": { "operationId": "products.update", "description": "Requires scope `merchant-items-update`.\n\nReplaces a product\u2019s fields; title and the core attributes are required. Answers the updated product \u2014 the same object GET products/{product} and products/* webhooks send.", "summary": "Update a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/ProductRequest" }, "example": { "title": "Jollof Rice Party Pack", "price": "18500.00", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "metadata": { "erp_id": "ERP-20417" } } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "$ref": "#/components/schemas/MerchantProduct" } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "product updated", "data": { "id": 20417, "uid": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "title": "Jollof Rice Party Pack", "slug": "jollof-rice-party-pack", "excerpt": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "description": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "status": "active", "published": true, "in_stock": true, "price": "18500.00", "storefront_price": "16650.00", "storefront_compare_at_price": "18500.00", "url": "https://adeyemifoods.com/products/jollof-rice-party-pack", "currency": "NGN", "sku": "ADF-JRP-001", "barcode": "6154000102417", "stock": 42, "track_inventory": true, "is_digital": false, "has_variants": false, "image": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "thumbnail_image": null, "primary_image_url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "variants": [], "options": [], "images": [ { "id": 88214, "is_primary": true, "position": 0, "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "alt": "Jollof rice party pack in a foil tray", "width": 1200, "height": 1200, "variants": { "thumb": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-thumb.webp", "w": null, "h": null }, "card": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card.webp", "w": 480, "h": 480 }, "card2x": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-card2x.webp", "w": 800, "h": 800 }, "view": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-view.webp", "w": 1200, "h": 1200 }, "wa": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack-wa.jpg", "w": 1080, "h": 1080 }, "original": { "url": "https://media.usequeek.com/uploads/stores/1095/jollof-rice-party-pack.jpg", "w": 1200, "h": 1200 } } } ], "metafields": {}, "metadata": { "erp_id": "ERP-20417" }, "created_at": "2026-07-14T10:20:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00", "deleted_at": null } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The stock field must be at least 0.", "field": "stock", "errors": { "stock": [ "The stock field must be at least 0." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "delete": { "operationId": "products.delete", "description": "Requires scope `merchant-items-delete`.\n\nDeletes a product.", "summary": "Delete a product", "tags": [ "Products" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Product deleted successfully" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Product deleted successfully", "data": { "id": "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "p_id": 20417, "deleted": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-delete' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products/publish": { "post": { "operationId": "products.publish", "description": "Requires scope `merchant-items-update`.\n\nPublishes or unpublishes a list of products in one call.", "summary": "Publish products in bulk", "tags": [ "Products" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkUpdatePublishRequest" }, "example": { "ids": [ "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b21", "019a1d52-3c8e-7f41-b0d2-6a3e9c1f4b22" ], "published": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "2 products published successfully", "data": { "count": 2, "published": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The ids field is required.", "field": "ids", "errors": { "ids": [ "The ids field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "500": { "description": "Server error \u2014 retry shortly and quote `error.request_id` in support. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "server_error", "message": "An unexpected error occurred.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#server_error", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/reviews": { "get": { "operationId": "reviews.list_imported", "description": "Requires scope `merchant-reviews-read`.\n\nLists only this installed app\u2019s imported reviews for this store, newest ingested first with cursor pagination. Approved imports remain unverified and are hidden from verified-only storefront blocks, store-wide summaries and testimonials unless the merchant opts in with verified_only=0. Customer product review lists, per-product summaries and latest-approved reviews include approved imports. Native reviews and rating aggregates are not readable through this API. Imports are capped at 30 requests/minute and 2,000/day per installation, and 5,000 pending rows per app/store; 409 conflicts may be retried after 1 second.", "summary": "List reviews imported by this app", "tags": [ "Reviews" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] }, "example": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMyAwOTowMDowMCIsImlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjIxIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" }, { "name": "product", "in": "query", "schema": { "type": "string", "maxLength": 255 } }, { "name": "status", "in": "query", "schema": { "type": "string", "enum": [ "pending", "approved", "rejected" ] }, "example": "pending" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantImportedReview" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "source_review_id": "chowdeck-review-2026-0042", "source": "chowdeck", "author_display_name": "Ifeoma Adebayo", "product_p_id": 20417, "rating": 5, "title": "Fresh and delicious", "description": "The jollof arrived hot.", "media": [], "status": "pending", "is_verified_purchase": false, "submitted_at": "2026-09-24T13:05:00+00:00", "created_at": "2026-10-03T08:00:00.000000Z", "edited_at": null } ], "has_more": true, "next_cursor": "eyJjcmVhdGVkX2F0IjoiMjAyNi0xMC0wMyAwOTowMDowMCIsImlkIjoiMDE5YTFkNTItM2M4ZS03ZjQxLWIwZDItNmEzZTljMWY0YjIxIiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-reviews-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/reviews/import": { "post": { "operationId": "reviews.import", "description": "Requires scope `merchant-reviews-import`.\n\nImports up to 100 reviews per request into pending moderation. Product references accept this store\u2019s p_id, UUID or slug. The app identity and source are derived from the installation; re-import is idempotent by source_review_id. Approved imports contribute to product ratings but are not verified purchases. Limits: 30 requests/minute and 2,000/day per installation, plus 5,000 pending rows per app/store. Product resolution/mismatch, pending-cap 422 and 409 conflict attempts count toward quota; malformed payloads rejected by request validation do not. A 409 identity race includes Retry-After: 1; 429 responses include Retry-After seconds until the minute or daily window resets.", "summary": "Import product reviews", "tags": [ "Reviews" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ImportProductReviewsRequest" }, "example": { "reviews": [ { "source_review_id": "chowdeck-review-2026-0042", "product": "20417", "rating": 5, "title": "Fresh and delicious", "description": "The jollof arrived hot.", "author_display_name": "Ifeoma Adebayo", "submitted_at": "2026-09-24T13:05:00+00:00", "media": [ "https://adeyemifoods.com/reviews/2026-0042.jpg" ] } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Product reviews imported" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Product reviews imported", "data": { "results": [ { "source_review_id": "chowdeck-review-2026-0042", "result": "imported", "status": "pending", "product_p_id": 20417 } ] } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-reviews-import' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The reviews field is required.", "field": "reviews", "errors": { "reviews": [ "The reviews field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/shipping-zones": { "get": { "operationId": "shipping_zones.list", "description": "Requires scope `merchant-shipping-read`.\n\nLists the store\u2019s shipping zones.", "summary": "List shipping zones", "tags": [ "Shipping zones" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantShippingZone" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21", "name": "Lagos Island", "zone_type": "local", "countries": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "1500.00", "per_kg_rate": null, "min_weight_kg": null, "max_weight_kg": null, "min_days": 1, "max_days": 1, "active": true, "position": 1, "created_at": "2026-07-05T10:00:00+01:00", "updated_at": "2026-09-10T14:30:00+01:00" }, { "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c22", "name": "Nationwide", "zone_type": "national", "countries": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "3500.00", "per_kg_rate": "500.00", "min_weight_kg": "0.50", "max_weight_kg": "30.00", "min_days": 2, "max_days": 5, "active": true, "position": 2, "created_at": "2026-07-05T10:05:00+01:00", "updated_at": "2026-09-10T14:32:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6IjAxOWEyYzVkLTNlNGYtN2E1Yi04YzZkLTdlOGY5YTBiMWMyMiIsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-shipping-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "shipping_zones.create", "description": "Requires scope `merchant-shipping-create`.\n\nCreates a shipping zone with rates and delivery windows.", "summary": "Create a shipping zone", "tags": [ "Shipping zones" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantShippingZoneRequest" }, "example": { "name": "Nationwide", "zone_type": "national", "countries": [ "NG" ], "base_rate": "3500.00", "per_kg_rate": "500.00", "min_weight_kg": 0.5, "max_weight_kg": 30, "min_days": 2, "max_days": 5, "active": true, "sort_order": 2 } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Shipping zone created" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Shipping zone created", "data": { "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c22", "name": "Nationwide", "zone_type": "national", "countries": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "3500.00", "per_kg_rate": "500.00", "min_weight_kg": "0.50", "max_weight_kg": "30.00", "min_days": 2, "max_days": 5, "active": true, "position": 2, "created_at": "2026-07-05T10:05:00+01:00", "updated_at": "2026-07-05T10:05:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-shipping-create' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected zone type is invalid.", "field": "zone_type", "errors": { "zone_type": [ "The selected zone type is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/shipping-zones/{zone}": { "put": { "operationId": "shipping_zones.update", "description": "Requires scope `merchant-shipping-update`.\n\nReplaces a shipping zone; name, type, base rate and delivery window are required.", "summary": "Update a shipping zone", "tags": [ "Shipping zones" ], "parameters": [ { "name": "zone", "in": "path", "required": true, "schema": { "type": "string" }, "example": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MerchantShippingZoneRequest" }, "example": { "name": "Lagos Island", "zone_type": "local", "countries": [ "NG" ], "base_rate": "1500.00", "min_days": 1, "max_days": 1, "active": true, "sort_order": 1 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Shipping zone updated" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Shipping zone updated", "data": { "id": "019a2c5d-3e4f-7a5b-8c6d-7e8f9a0b1c21", "name": "Lagos Island", "zone_type": "local", "countries": [ "NG" ], "state_ids": [], "area_ids": [], "currency": "NGN", "base_rate": "1500.00", "per_kg_rate": null, "min_weight_kg": null, "max_weight_kg": null, "min_days": 1, "max_days": 1, "active": true, "position": 1, "created_at": "2026-07-05T10:00:00+01:00", "updated_at": "2026-09-10T14:30:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-shipping-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The base rate field must be at least 0.", "field": "base_rate", "errors": { "base_rate": [ "The base rate field must be at least 0." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Vendor shipping zone not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/store": { "get": { "operationId": "store.retrieve", "description": "Requires scope `merchant-business_profile-read`.\n\nRetrieves the store\u2019s business profile: name, contact, branding and storefront status.", "summary": "Retrieve the store", "tags": [ "Store" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "The store behind the calling key \u2014 the public object, never the dashboard shape.", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "example": "success" }, "message": { "type": "string", "example": "store" }, "data": { "type": "object", "properties": { "store": { "$ref": "#/components/schemas/QueekMerchantStore" } }, "required": [ "store" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "store", "data": { "store": { "id": 1095, "uid": "019a0b3a-af57-72d0-9c13-7036c3805892", "name": "Adeyemi Foods", "slug": "adeyemi-foods", "contact": { "email": "hello@adeyemifoods.com", "phone": "+234 801 234 5678" }, "address": { "address": "14 Admiralty Way, Lekki Phase 1", "landmark": "Opposite NIIT", "region": "Lagos", "latitude": 6.4474, "longitude": 3.4712 }, "logo": "https://media.usequeek.com/uploads/stores/1095/logo.png", "banner": "https://media.usequeek.com/uploads/stores/1095/banner.png", "rating": { "value": 4.8, "count": 231 }, "status": "active", "operating_hours": { "weekdays": { "open_time": "08:00", "close_time": "22:00", "status": "closed" }, "saturday": { "open_time": "09:00", "close_time": "18:00" }, "sunday": { "open_time": null, "close_time": null }, "preparation_time": { "minimum": 30, "maximum": 120 }, "temporary_unavailable": true, "available_on_weekend": true }, "capabilities": { "queek_logistics_enabled": true, "delivery_enabled": true, "offers_free_delivery": false, "pickup_enabled": true, "instore_order": false }, "storefront": { "domains": [ "https://adeyemifoods.com", "https://adeyemi-foods.queek.com.ng" ] }, "created_at": "2026-06-02T08:00:00+01:00", "updated_at": "2026-09-24T18:30:00+01:00" } } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-business_profile-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "This store no longer exists.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "500": { "description": "Server error \u2014 retry shortly and quote `error.request_id` in support. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "server_error", "message": "The store could not be read. Retry shortly.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#server_error", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/team-directory": { "get": { "operationId": "team.list", "description": "Requires scope `merchant-team-directory-read`.\n\nLists the store\u2019s staff directory \u2014 each member\u2019s id, display name, role names and active flag \u2014 with cursor pagination (`limit` + `starting_after`, `has_more`/`next_cursor`). Contact details, credentials and permissions are never included.", "summary": "List the team directory", "tags": [ "Team" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "search", "in": "query", "schema": { "type": [ "string", "null" ], "maxLength": 255 } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "description": "Cursor page: `data` carries this page's rows, `next_cursor` the opaque cursor for the next page (absent on the last page).", "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MerchantTeamMember" } }, "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ] } }, "required": [ "data", "has_more" ] }, "example": { "data": [ { "id": 109501, "name": "Amina Yusuf", "role_names": [ "Admin" ], "is_active": true }, { "id": 109502, "name": "Tunde Bakare", "role_names": [ "Manager" ], "is_active": false } ], "has_more": true, "next_cursor": "eyJpZCI6MTA5NTAyLCJfcG9pbnRzVG9OZXh0SXRlbXMiOnRydWV9" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-team-directory-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must not be greater than 100.", "field": "limit", "errors": { "limit": [ "The limit field must not be greater than 100." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/locales": { "get": { "operationId": "locales.list", "description": "Requires scope `merchant-locales-read`.\n\nLists the store\u2019s enabled locales with catalogue names, publish state and the primary flag.", "summary": "List locales", "tags": [ "Translations" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string" }, "name": { "type": "string" }, "native_name": { "type": "string" }, "html_lang": { "type": "string" }, "dir": { "type": "string", "enum": [ "ltr", "rtl" ] }, "published": { "type": "boolean" }, "is_primary": { "type": "boolean" } }, "required": [ "locale", "name", "native_name", "html_lang", "dir", "published", "is_primary" ] } } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Locales retrieved", "data": [ { "locale": "en", "name": "English", "native_name": "English", "html_lang": "en", "dir": "ltr", "published": true, "is_primary": true }, { "locale": "fr", "name": "French", "native_name": "Fran\u00e7ais", "html_lang": "fr", "dir": "ltr", "published": true, "is_primary": false }, { "locale": "de", "name": "German", "native_name": "Deutsch", "html_lang": "de", "dir": "ltr", "published": false, "is_primary": false } ] } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-locales-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "locales.create", "description": "Requires scope `merchant-locales-write`.\n\nEnables a catalogue locale on the store; answers the added locale, unpublished until published.", "summary": "Add a locale", "tags": [ "Translations" ], "parameters": [ { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreVendorLocaleRequest" }, "example": { "locale": "fr" } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "locale": { "type": "string" }, "name": { "type": "string" }, "native_name": { "type": "string" }, "html_lang": { "type": "string" }, "dir": { "type": "string", "enum": [ "ltr", "rtl" ] }, "published": { "type": "boolean" }, "is_primary": { "type": "boolean" } }, "required": [ "locale", "name", "native_name", "html_lang", "dir", "published", "is_primary" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Locale added", "data": { "locale": "fr", "name": "French", "native_name": "Fran\u00e7ais", "html_lang": "fr", "dir": "ltr", "published": false, "is_primary": false } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-locales-write' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. The store primary locale answers translation_locale_is_primary instead \u2014 it is the source language, never a translation target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected locale is invalid.", "field": "locale", "errors": { "locale": [ "The selected locale is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/locales/{locale}": { "patch": { "operationId": "locales.update", "description": "Requires scope `merchant-locales-write`.\n\nPublishes or unpublishes an enabled locale. {locale} is a catalogue code of this store.", "summary": "Publish a locale", "tags": [ "Translations" ], "parameters": [ { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" }, "example": "fr" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateVendorLocaleRequest" }, "example": { "published": true } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "locale": { "type": "string" }, "name": { "type": "string" }, "native_name": { "type": "string" }, "html_lang": { "type": "string" }, "dir": { "type": "string", "enum": [ "ltr", "rtl" ] }, "published": { "type": "boolean" }, "is_primary": { "type": "boolean" } }, "required": [ "locale", "name", "native_name", "html_lang", "dir", "published", "is_primary" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Locale updated", "data": { "locale": "fr", "name": "French", "native_name": "Fran\u00e7ais", "html_lang": "fr", "dir": "ltr", "published": true, "is_primary": false } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-locales-write' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. Publishing the store primary locale answers translation_locale_is_primary instead \u2014 it is the source language, never a translation target.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The published field must be true or false.", "field": "published", "errors": { "published": [ "The published field must be true or false." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Locale not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "delete": { "operationId": "locales.delete", "description": "Requires scope `merchant-locales-write`.\n\nRemoves a locale with all of its translations. {locale} is a catalogue code of this store.", "summary": "Remove a locale", "tags": [ "Translations" ], "parameters": [ { "name": "locale", "in": "path", "required": true, "schema": { "type": "string" }, "example": "de" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "locale": { "type": "string", "description": "The removed locale code." }, "deleted": { "type": "boolean", "description": "Always true when this shape answers." } }, "required": [ "locale", "deleted" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Locale removed", "data": { "locale": "de", "deleted": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-locales-write' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Locale not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/translatable-resources": { "get": { "operationId": "translatable_resources.list", "description": "Requires scope `merchant-translations-read`.\n\nLists one resource type\u2019s translatable content \u2014 the current source value, digest and kind per key \u2014 with cursor pagination (`limit` + `starting_after`, `has_more`/`next_cursor`). `theme_string` is the store\u2019s own singleton: the page carries every theme key of the active theme with `has_more` false \u2014 English comes from the theme registry sync (`themes.en_default`), with the deprecated owner-asserted `theme_strings_en` config row as fallback.", "summary": "List translatable resources", "tags": [ "Translations" ], "parameters": [ { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "type", "in": "query", "required": true, "schema": { "type": "string", "enum": [ "product", "product_variation", "product_variation_item", "collection", "category", "page", "post", "menu", "theme_string" ] }, "example": "product" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "array", "items": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer", "description": "The resource p_id." }, "content": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "value": { "type": "string" }, "digest": { "type": "string" }, "type": { "type": "string" } }, "required": [ "key", "value", "digest", "type" ] } } }, "required": [ "type", "id", "content" ] } } }, "required": [ "status", "message", "data" ] }, "example": { "data": [ { "type": "product", "id": 20417, "content": [ { "key": "title", "value": "Jollof Rice Party Pack", "digest": "717305e87d2a399c8e9bb34ec9185ed112d0f79dad537eef7390b4a16fd23227", "type": "text" }, { "key": "description", "value": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "digest": "fe36ee78505f529bfdd4a2712f6d5cee201e4260b3d9a814535b1b6b92d3622c", "type": "html" }, { "key": "excerpt", "value": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "digest": "5fd1090cc7510d55f0cba61ef520a4e5b8c2fbce650a2032ae84cf2a1c0584cd", "type": "text" } ], "machine_translation_allowed": true }, { "type": "product", "id": 20418, "content": [ { "key": "title", "value": "Homemade Chapman", "digest": "1b3a09a0177033cf7132f3b625228c66f2112485288611e3fd4309e4cbc3b4ed", "type": "text" }, { "key": "description", "value": "Our house Chapman, mixed fresh every morning. Served chilled.", "digest": "5dc5de76314169d70ac5f1008ed3c62e6ed0ac4ebd6b6be334e3a316a355c8e6", "type": "html" }, { "key": "excerpt", "value": "Fresh Chapman with cucumber and orange slices.", "digest": "da2da5ed20ba1c1a185ffcf1ed030b1e0f4d0455283599b9b950d7fba32b42e9", "type": "text" } ], "machine_translation_allowed": true } ], "has_more": true, "next_cursor": "eyJpZCI6MjA0MTgsIl9wb2ludHNUb05leHRJdGVtcyI6dHJ1ZX0" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-translations-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected type is invalid.", "field": "type", "errors": { "type": [ "The selected type is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/translatable-resources/{type}/{id}": { "get": { "operationId": "translatable_resources.retrieve", "description": "Requires scope `merchant-translations-read`.\n\nRetrieves one resource\u2019s translatable content with its stored translations, each flagged outdated when the source changed since. {id} is a p_id or UUID of this store. For `theme_string`, {id} is the store\u2019s own p_id, slug or UUID and keys are `.` against the store\u2019s English defaults (e.g. `roast.cart.title`) \u2014 served from the active theme\u2019s registry-synced `en_default`, with the deprecated owner-asserted `theme_strings_en` config row as fallback.", "summary": "Retrieve translatable content", "tags": [ "Translations" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "example": "product" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "locale", "in": "query", "schema": { "type": [ "string", "null" ], "enum": [ "en", "fr", "es", "pt", "pt-BR", "de", "it", "nl", "pl", "ru", "uk", "tr", "ar", "ur", "fa", "he", "hi", "ja", "ko", "zh-CN", "zh-TW", "id", "ms", "vi", "th", "tl", "sw", "ha", "yo", "ig", "pcm", null ], "maxLength": 12 }, "example": "fr" }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Translatable resource retrieved" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Translatable resource retrieved", "data": { "type": "product", "id": 20417, "content": [ { "key": "title", "value": "Jollof Rice Party Pack", "digest": "717305e87d2a399c8e9bb34ec9185ed112d0f79dad537eef7390b4a16fd23227", "type": "text" }, { "key": "description", "value": "Firewood-smoked party jollof cooked to order, served with dodo and six pieces of grilled chicken. Feeds 10.", "digest": "fe36ee78505f529bfdd4a2712f6d5cee201e4260b3d9a814535b1b6b92d3622c", "type": "html" }, { "key": "excerpt", "value": "Smoky party jollof for 10, with fried plantain and grilled chicken.", "digest": "5fd1090cc7510d55f0cba61ef520a4e5b8c2fbce650a2032ae84cf2a1c0584cd", "type": "text" } ], "machine_translation_allowed": true, "translations": [ { "key": "title", "locale": "fr", "value": "Pack F\u00eate Jollof", "outdated": false, "updated_at": "2026-09-30T12:00:00+01:00" } ] } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-translations-read' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Translatable resource not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The selected locale is invalid.", "field": "locale", "errors": { "locale": [ "The selected locale is invalid." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/translations/{type}/{id}": { "put": { "operationId": "translations.update", "description": "Requires scope `merchant-translations-write`.\n\nRegisters up to 100 translations on one resource against the current source digests \u2014 all or nothing. A stale digest, unknown locale or unknown key answers a per-item `translation_*` code and writes nothing. {id} is a p_id or UUID of this store. Translator flow for `theme_string`: English defaults arrive via the theme registry sync (no English write path here \u2014 the owner-asserted `theme_strings_en` config row is a deprecated fallback only), echo each key\u2019s current digest, then write at most 100 keys per call \u2014 N sequential calls carry a full dictionary.", "summary": "Register translations", "tags": [ "Translations" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "example": "product" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RegisterTranslationsRequest" }, "example": { "translations": [ { "locale": "fr", "key": "title", "value": "Pack F\u00eate Jollof", "digest": "717305e87d2a399c8e9bb34ec9185ed112d0f79dad537eef7390b4a16fd23227" } ] } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "type": { "type": "string" }, "id": { "type": "integer", "description": "The resource p_id." }, "translations": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string" }, "locale": { "type": "string" }, "value": { "type": "string" }, "outdated": { "type": "boolean" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "key", "locale", "value", "outdated" ] } } }, "required": [ "type", "id", "translations" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Translations registered", "data": { "type": "product", "id": 20417, "translations": [ { "key": "title", "locale": "fr", "value": "Pack F\u00eate Jollof", "outdated": false, "updated_at": "2026-09-30T12:00:00+01:00" } ] } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-translations-write' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`. An unknown locale, key or stale digest answers translation_unknown_locale, translation_unknown_key or translation_digest_stale instead, with the item index.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The translations field is required.", "field": "translations", "errors": { "translations": [ "The translations field is required." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Translatable resource not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "delete": { "operationId": "translations.delete", "description": "Requires scope `merchant-translations-write`.\n\nRemoves one resource\u2019s translations, optionally narrowed to `locales` and/or `keys`. {id} is a p_id or UUID of this store. For `theme_string`, narrowing to `keys` prunes a retired theme slug\u2019s dormant overrides.", "summary": "Remove translations", "tags": [ "Translations" ], "parameters": [ { "name": "type", "in": "path", "required": true, "schema": { "type": "string" }, "example": "product" }, { "name": "id", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20417 }, { "name": "locales[]", "in": "query", "schema": { "type": "array", "enum": [ "en", "fr", "es", "pt", "pt-BR", "de", "it", "nl", "pl", "ru", "uk", "tr", "ar", "ur", "fa", "he", "hi", "ja", "ko", "zh-CN", "zh-TW", "id", "ms", "vi", "th", "tl", "sw", "ha", "yo", "ig", "pcm" ], "items": { "type": "string", "enum": [ "en", "fr", "es", "pt", "pt-BR", "de", "it", "nl", "pl", "ru", "uk", "tr", "ar", "ur", "fa", "he", "hi", "ja", "ko", "zh-CN", "zh-TW", "id", "ms", "vi", "th", "tl", "sw", "ha", "yo", "ig", "pcm" ], "maxLength": 12 } } }, { "name": "keys[]", "in": "query", "schema": { "type": "array", "items": { "type": "string", "maxLength": 64 } } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string" }, "data": { "type": "object", "properties": { "type": { "type": "string", "description": "The resource type the translations were removed from." }, "id": { "type": "integer", "description": "The resource p_id." }, "deleted": { "type": "integer", "description": "How many translation rows were removed." } }, "required": [ "type", "id", "deleted" ] } }, "required": [ "status", "message", "data" ] }, "example": { "status": "success", "message": "Translations removed", "data": { "type": "product", "id": 20417, "deleted": 2 } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-translations-write' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The locales field must be an array.", "field": "locales", "errors": { "locales": [ "The locales field must be an array." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Translatable resource not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products/{product}/variants": { "get": { "operationId": "variants.list", "description": "Requires scope `merchant-items-detail`.\n\nLists one product\u2019s variants with the merchant price, the storefront price pair, and the canonical product URL.", "summary": "List product variants", "tags": [ "Variants" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20418 }, { "name": "limit", "in": "query", "schema": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 100 }, "example": 2 }, { "name": "starting_after", "in": "query", "schema": { "type": [ "string", "null" ] } }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Product variants" }, "data": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "data": [ { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "sku": "ADF-CHP-50CL", "barcode": "6151101370016", "title": "50cl", "option_values": { "Size": "50cl" }, "price": "2500.00", "storefront_price": "2500.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 36, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 0.55, "position": 0, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" }, { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "barcode": "6151101370023", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": "4200.00", "storefront_price": "4200.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" } ], "has_more": true, "next_cursor": "eyJpZCI6NzczMiwiX3BvaW50c1RvTmV4dEl0ZW1zIjp0cnVlfQ" } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-detail' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The limit field must be at least 1.", "field": "limit", "errors": { "limit": [ "The limit field must be at least 1." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "post": { "operationId": "variants.create", "description": "Requires scope `merchant-items-update`.\n\nCreates a variant on a product; answers the variant with the merchant price, the storefront price pair, and the canonical product URL.", "summary": "Create a product variant", "tags": [ "Variants" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20418 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StoreProductVariantRequest" }, "example": { "option_values": { "Size": "1 litre" }, "sku": "ADF-CHP-1L", "barcode": "6151101370023", "price": "4200.00", "stock": 24, "weight": 1.05, "position": 1 } } } }, "responses": { "201": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Variant created" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Variant created", "data": { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "barcode": "6151101370023", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": "4200.00", "storefront_price": "4200.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-07-15T11:30:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The price field must be at least 0.", "field": "price", "errors": { "price": [ "The price field must be at least 0." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Product not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } }, "/products/{product}/variants/{variant}": { "patch": { "operationId": "variants.update", "description": "Requires scope `merchant-items-update`.\n\nUpdates a variant\u2019s price, stock and attributes; answers the variant with the merchant price, the storefront price pair, and the canonical product URL.", "summary": "Update a product variant", "tags": [ "Variants" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20418 }, { "name": "variant", "in": "path", "required": true, "schema": { "type": "string" }, "example": 7732 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UpdateProductVariantRequest" }, "example": { "price": "4200.00", "stock": 24 } } } }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Variant updated" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Variant updated", "data": { "id": 7732, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a32", "sku": "ADF-CHP-1L", "barcode": "6151101370023", "title": "1 litre", "option_values": { "Size": "1 litre" }, "price": "4200.00", "storefront_price": "4200.00", "storefront_compare_at_price": null, "url": "https://adeyemifoods.com/products/homemade-chapman", "compare_at_price": null, "stock": 24, "track_inventory": true, "is_digital": false, "is_active": true, "is_backorder": false, "backorder_ready_date": null, "weight": 1.05, "position": 1, "created_at": "2026-07-15T11:30:00+01:00", "updated_at": "2026-09-22T16:05:00+01:00" } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "422": { "description": "Validation failed \u2014 `error.errors` carries per-field detail. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "validation_failed", "message": "The price field must be a number.", "field": "price", "errors": { "price": [ "The price field must be a number." ] }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#validation_failed", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Variant not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } }, "delete": { "operationId": "variants.delete", "description": "Requires scope `merchant-items-update`.\n\nDeletes a variant. A product\u2019s last variant cannot be deleted.", "summary": "Delete a product variant", "tags": [ "Variants" ], "parameters": [ { "name": "product", "in": "path", "required": true, "schema": { "type": "string" }, "example": 20418 }, { "name": "variant", "in": "path", "required": true, "schema": { "type": "string" }, "example": 7731 }, { "name": "X-Client-Key", "in": "header", "required": true, "description": "A private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) minted under Dashboard \u2192 Settings \u2192 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.", "schema": { "type": "string" }, "example": "{{merchantKey}}" }, { "name": "X-Request-Id", "in": "header", "description": "Your own correlation id (8\u2013128 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.", "schema": { "type": "string" } }, { "name": "Idempotency-Key", "in": "header", "description": "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`.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "success" }, "message": { "type": "string", "const": "Variant deleted" }, "data": { "type": "object" }, "meta": { "type": "string" } }, "required": [ "status", "message", "data", "meta" ] }, "example": { "status": "success", "message": "Variant deleted", "data": { "id": 7731, "uid": "019a1d52-5f10-7a02-8c61-0b2d4e6f8a31", "deleted": true } } } } }, "401": { "description": "Unauthorized \u2014 the key is missing, unknown, or its mode does not match its store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "invalid_client_key", "message": "This API accepts only a store private key: send it in the X-Client-Key header (Dashboard \u2192 Settings \u2192 API keys).", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#invalid_client_key", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "403": { "description": "Forbidden \u2014 the key cannot call this operation. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "insufficient_scope", "message": "This API key does not carry the 'merchant-items-update' scope it was called with.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#insufficient_scope", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "409": { "description": "Idempotency conflict \u2014 `idempotency_key_reuse` or `idempotency_key_in_progress`. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "idempotency_key_reuse", "message": "This Idempotency-Key was already used for a different request body. Use a new key for a new request.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#idempotency_key_reuse", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "404": { "description": "Not found \u2014 the addressed record does not exist at this store. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "not_found", "message": "Variant not found.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#not_found", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } }, "429": { "description": "Too many requests \u2014 slow down and retry. Switch on `error.code`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekError" }, "example": { "error": { "code": "too_many_requests", "message": "Too Many Attempts.", "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors#too_many_requests", "request_id": "5d1c9b3e-8f2a-4b6d-9c07-3e1f8a2b6d45" } } } } } } } } }, "components": { "securitySchemes": { "merchantKey": { "type": "apiKey", "description": "The store's private API key (`sk_live_\u2026`, `sk_test_\u2026` on a dev store) from Dashboard \u2192 Settings \u2192 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 \u2014 never ship it to a browser or an app bundle.", "in": "header", "name": "X-Client-Key" } }, "schemas": { "AdjustStockRequest": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "variant_id": { "type": [ "string", "null" ], "format": "uuid" }, "quantity_change": { "type": "integer" }, "type": { "type": "string", "enum": [ "restock", "adjustment", "damage" ] }, "reason": { "type": "string", "maxLength": 500 } }, "required": [ "product_ids", "quantity_change", "type", "reason" ], "title": "AdjustStockRequest" }, "App.Http.Resources.Api.CollectionResource": { "type": "object", "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": "string" }, "image": { "type": "string" }, "logo": { "type": "string" }, "featured": { "type": "boolean" }, "position": { "type": [ "integer", "null" ] }, "collection_mode": { "type": [ "string", "null" ] }, "parent_uid": { "type": [ "string", "null" ] }, "products_count": { "type": [ "integer", "null" ] }, "children": { "type": "array", "items": {} }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "uid", "name", "slug", "description", "image", "logo", "featured", "position", "collection_mode", "parent_uid", "products_count", "children", "created_at", "updated_at" ], "title": "Collection" }, "App.Http.Resources.Customer.OrderItemResource": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "string" }, "title": { "type": "string" }, "variant_id": { "type": "string" }, "variant_title": { "type": "string" }, "variant_option_values": { "type": "object", "additionalProperties": { "type": "string" } }, "variant_media": { "type": [ "object", "null" ], "properties": { "image": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "variant", "product" ] } }, "required": [ "image", "video_url", "source" ] }, "currency": { "type": "string" }, "total_price": { "type": [ "number", "null" ] }, "sale_price": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "base_unit_price": { "type": [ "number", "null" ] }, "is_backorder": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ] }, "discounted_amount": { "type": [ "number", "null" ] }, "created_at": { "type": "string", "format": "date-time" }, "addons": {}, "properties": { "type": "string", "description": "Per-line checkout properties. Always present as an object so\ndashboard chips and the shopper page never branch on absence.\nBearer keys are withheld here too (dashboard, shopper page,\nrider): the order email is their only carrier." } }, "required": [ "id", "quantity", "title", "variant_id", "variant_title", "variant_option_values", "variant_media", "currency", "total_price", "sale_price", "unit_price", "base_unit_price", "is_backorder", "backorder_ready_date", "created_at", "addons", "properties" ], "title": "OrderItem" }, "App.Http.Resources.Customer.ProductResource": { "title": "Product", "anyOf": [ { "type": "array" }, { "type": "object", "properties": { "shop_id": { "type": "string" }, "id": { "type": "string" }, "p_id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "slug": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "thumbnail_image": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "video_poster_url": { "type": [ "string", "null" ] }, "type": {}, "commerce_mode": { "type": "string" }, "currency": { "type": "string" }, "price": { "type": "number" }, "discount_price": { "type": "number" }, "compare_at_price": { "type": [ "number", "null" ] }, "is_price_from": { "type": "boolean" }, "price_range": { "type": [ "object", "null" ], "properties": { "min": { "type": "number" }, "max": { "type": "number" } }, "required": [ "min", "max" ] }, "has_variants": { "type": "boolean" }, "has_addons": { "type": "string" }, "tax_inclusive": { "type": "boolean" }, "discount": { "type": [ "object", "null" ], "properties": { "id": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ] }, "value": { "type": [ "number", "null" ] }, "amount": { "type": [ "number", "null" ] }, "final_price": { "type": [ "number", "null" ] }, "image_url": { "type": [ "string", "null" ] } }, "required": [ "id", "title", "type", "value", "amount", "final_price", "image_url" ] }, "discounts": { "type": "array", "items": {} }, "media": { "type": "object", "properties": { "thumbnail": { "type": [ "string", "null" ] }, "image": { "type": [ "string", "null" ] }, "original": { "type": [ "string", "null" ], "description": "Full original for hero-scale surfaces (featured/promo blocks render\n~1100-1320 physical px \u2014 the 480px card upscales blurry there)." }, "primary_variant_image": { "type": [ "string", "null" ] }, "image_variants": { "type": [ "object", "null" ], "description": "Sized variants of the primary image (thumbnail, card, hero),\nkeyed by size. Null when the image is a plain URL instead of an\nuploaded image, or when no sized variants exist for it; the\nother image keys are always present.", "additionalProperties": {} }, "primary_variant_image_variants": { "type": [ "object", "null" ], "additionalProperties": {} }, "images": { "type": [ "array", "null" ], "items": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "alt": {}, "variants": { "type": "string" } }, "required": [ "id", "url", "alt", "variants" ] }, { "type": "null" }, { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "url": { "type": [ "string", "null" ] }, "alt": {}, "variants": { "type": "null" } }, "required": [ "id", "url", "alt", "variants" ] } ] } } }, "required": [ "thumbnail", "image", "original", "primary_variant_image", "image_variants", "primary_variant_image_variants", "images" ] }, "inventory": { "type": "array", "items": {} }, "variant_summary": { "type": [ "string", "null" ] }, "variants_count": {}, "rating": { "type": "number" }, "review_count": { "type": "integer" }, "flags": { "type": "object", "properties": { "featured": { "type": "boolean" }, "is_marketplace": { "type": "boolean" }, "is_wholesale": { "type": "boolean" }, "is_new": { "type": "boolean" } }, "required": [ "featured", "is_marketplace", "is_wholesale", "is_new" ] }, "metafields": { "type": "string", "description": "Vendor-defined typed fields, keyed `namespace.key`. `{}` for a store\nthat has defined none, which costs no query (MetafieldPresenter).\nFree-form `metadata` is deliberately NOT here: it is an\nintegrator's private bookkeeping and stays on the merchant API.\nClient surface: draft entries and storefront-hidden definitions\nare omitted from reference values (MetafieldPresenter)." }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "shop": { "type": "array", "items": {} }, "barcode": { "type": "string" } }, "required": [ "shop_id", "id", "p_id", "title", "slug", "excerpt", "description", "image", "thumbnail_image", "video_url", "video_poster_url", "type", "commerce_mode", "currency", "price", "discount_price", "compare_at_price", "is_price_from", "price_range", "has_variants", "has_addons", "tax_inclusive", "discount", "discounts", "media", "inventory", "variant_summary", "variants_count", "rating", "review_count", "flags", "metafields", "created_at", "updated_at", "shop", "barcode" ] } ] }, "App.Http.Resources.OrderResource": { "title": "Order", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "total_price": { "type": [ "number", "null" ] }, "delivery_fee": { "type": [ "number", "null" ] }, "grand_total": { "type": [ "number", "null" ] }, "payment_status": { "type": "string" }, "transaction_id": { "type": [ "string", "null" ] }, "is_verified": { "type": [ "boolean", "null" ] }, "order_no": { "type": "string" }, "status": { "type": "string" }, "order_type": { "type": "string" }, "scheduled_date": { "type": [ "string", "null" ] }, "scheduled_time": { "type": [ "string", "null" ] }, "is_backorder_held": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ] }, "delivery_method": { "type": [ "string", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "0": { "type": "object" }, "delivery_address": { "type": [ "string", "null" ] }, "pickup_address": { "type": [ "string", "null" ] }, "table": { "description": "The dine-in table picked at checkout for in-store QR orders: its\nid, name and section, as shown in the table picker.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "section": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "section" ] }, { "type": "object" } ] }, "stage": { "type": "integer" }, "earliest_delivery_time": { "type": [ "string", "null", "object" ] }, "latest_delivery_time": { "type": [ "string", "null", "object" ] }, "ready_window": { "anyOf": [ { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "from", "to", "label" ] }, { "type": "null" }, { "type": "object" } ] }, "vendor": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ], "description": "Contact + location surfaced so the storefront can render a\n\"collect from\" block on pickup orders. Cheap eager-loaded\ncolumns; not gated behind delivery_mode so a hybrid UI can\nalso show them on rider/dispatch flows." }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "map_lat": { "type": [ "string", "null" ] }, "map_lng": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logo", "address", "phone", "email", "map_lat", "map_lng" ] }, { "type": "object" } ] }, "created_by_id": { "type": [ "string", "null" ] }, "timeline": { "type": "array", "items": {} }, "vendor_timeline": { "type": "array", "items": {} }, "vendor_note": { "type": [ "string", "null" ] }, "rider_note": { "type": [ "string", "null" ] }, "shopforme_fee": { "type": [ "number", "null" ] }, "service_fee": { "type": [ "number", "null" ] }, "delivery_pin": { "type": [ "string", "null", "object" ] }, "delivery_pins": { "type": [ "array", "null", "object" ] }, "is_confirmed": { "type": "boolean" }, "rejected": { "type": "boolean" }, "is_completed": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "cancellation_reason": { "type": [ "string", "null", "object" ] }, "items_count": { "type": "string" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "status_label": { "type": "string" }, "status_img": { "type": "string" }, "user_id": { "type": "string" }, "pickup_map_lat": { "type": [ "string", "null" ] }, "pickup_map_lng": { "type": [ "string", "null" ] }, "items": { "description": "In-memory parent link (zero queries): item currency resolves through\nthis order, then its vendor, before the platform default.", "anyOf": [ { "type": "array", "items": { "$ref": "#/components/schemas/OrderItemResource" } }, { "type": "object" } ] }, "created_by": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": [ "string", "null" ] }, "phone": { "type": "string" }, "email": { "type": "string" } }, "required": [ "id", "name", "avatar", "phone", "email" ] }, { "type": "object" } ] }, "rider": { "$ref": "#/components/schemas/UserItemResource" }, "rider_rating": { "type": "number" }, "rider_review_status": { "type": "string" }, "vendor_review_status": { "type": "string" }, "vendor_rating": { "type": "number" }, "virtual_account_id": { "type": [ "string", "null" ] }, "payment_link": { "type": [ "string", "null" ] }, "pay_link": { "type": "string" }, "viewer_type": { "type": "string", "enum": [ "customer", "vendor", "rider", "admin" ] }, "amount_summary": { "anyOf": [ { "type": "object", "properties": { "title": { "type": "string", "const": "Order Summary" }, "view": { "type": "string", "const": "rider" }, "items": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "key": { "type": "string", "const": "rider_fee" }, "label": { "type": "string", "const": "Rider Fee" }, "type": { "type": "string", "const": "total" }, "amount": { "type": [ "number", "null" ] } }, "required": [ "key", "label", "type", "amount" ] } ], "minItems": 1, "maxItems": 1 } }, "required": [ "title", "view", "items" ] }, { "type": "object", "properties": { "title": { "type": "string", "const": "Order Summary" }, "view": { "type": "string", "const": "vendor" }, "items": { "type": "array", "items": {} } }, "required": [ "title", "view", "items" ] }, { "type": "object", "properties": { "title": { "type": "string", "const": "Order Summary" }, "view": { "type": "string", "const": "customer" }, "items": { "type": "array", "items": {} } }, "required": [ "title", "view", "items" ] } ] } }, "required": [ "id", "title", "currency", "total_price", "delivery_fee", "grand_total", "payment_status", "transaction_id", "is_verified", "order_no", "status", "order_type", "scheduled_date", "scheduled_time", "is_backorder_held", "backorder_ready_date", "delivery_method", "payment_method", "0", "delivery_address", "pickup_address", "table", "stage", "earliest_delivery_time", "latest_delivery_time", "ready_window", "vendor", "created_by_id", "timeline", "vendor_timeline", "vendor_note", "rider_note", "shopforme_fee", "service_fee", "delivery_pin", "delivery_pins", "is_confirmed", "rejected", "is_completed", "cancelled", "cancellation_reason", "items_count", "started_at", "completed_at", "created_at", "updated_at", "status_label", "status_img", "user_id", "pickup_map_lat", "pickup_map_lng", "items", "created_by", "rider", "rider_rating", "rider_review_status", "vendor_review_status", "vendor_rating", "virtual_account_id", "payment_link", "pay_link", "viewer_type", "amount_summary" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "total_price": { "type": [ "number", "null" ] }, "delivery_fee": { "type": [ "number", "null" ] }, "grand_total": { "type": [ "number", "null" ] }, "payment_status": { "type": "string" }, "transaction_id": { "type": [ "string", "null" ] }, "is_verified": { "type": [ "boolean", "null" ] }, "order_no": { "type": "string" }, "status": { "type": "string" }, "order_type": { "type": "string" }, "scheduled_date": { "type": [ "string", "null" ] }, "scheduled_time": { "type": [ "string", "null" ] }, "is_backorder_held": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ] }, "delivery_method": { "type": [ "string", "null" ] }, "payment_method": { "type": [ "string", "null" ] }, "0": { "type": "object", "description": "Settlement ledger is vendor facts, never customer facts: it stays\noff the storefront public path only (client_vendor_id resolved).\nEvery other surface keeps reading it exactly as before." }, "delivery_address": { "type": [ "string", "null" ] }, "pickup_address": { "type": [ "string", "null" ] }, "table": { "description": "The dine-in table picked at checkout for in-store QR orders: its\nid, name and section, as shown in the table picker.", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "section": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "section" ] }, { "type": "object" } ] }, "stage": { "type": "integer" }, "earliest_delivery_time": { "type": [ "string", "null", "object" ] }, "latest_delivery_time": { "type": [ "string", "null", "object" ] }, "ready_window": { "anyOf": [ { "type": "object", "properties": { "from": { "type": [ "string", "null" ] }, "to": { "type": [ "string", "null" ] }, "label": { "type": "string" } }, "required": [ "from", "to", "label" ] }, { "type": "null" }, { "type": "object" } ] }, "vendor": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ], "description": "Contact + location surfaced so the storefront can render a\n\"collect from\" block on pickup orders. Cheap eager-loaded\ncolumns; not gated behind delivery_mode so a hybrid UI can\nalso show them on rider/dispatch flows." }, "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "map_lat": { "type": [ "string", "null" ] }, "map_lng": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "slug", "logo", "address", "phone", "email", "map_lat", "map_lng" ] }, { "type": "object" } ] }, "created_by_id": { "type": [ "string", "null" ] }, "timeline": { "type": "array", "items": {} }, "vendor_timeline": { "type": "array", "items": {} }, "vendor_note": { "type": [ "string", "null" ] }, "rider_note": { "type": [ "string", "null" ] }, "shopforme_fee": { "type": [ "number", "null" ] }, "service_fee": { "type": [ "number", "null" ] }, "delivery_pin": { "type": [ "string", "null", "object" ] }, "delivery_pins": { "type": [ "array", "null", "object" ] }, "is_confirmed": { "type": "boolean" }, "rejected": { "type": "boolean" }, "is_completed": { "type": "boolean" }, "cancelled": { "type": "boolean" }, "cancellation_reason": { "type": [ "string", "null", "object" ] }, "items_count": { "type": "string" }, "started_at": { "type": [ "string", "null" ], "format": "date-time" }, "completed_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "title", "currency", "total_price", "delivery_fee", "grand_total", "payment_status", "transaction_id", "is_verified", "order_no", "status", "order_type", "scheduled_date", "scheduled_time", "is_backorder_held", "backorder_ready_date", "delivery_method", "payment_method", "0", "delivery_address", "pickup_address", "table", "stage", "earliest_delivery_time", "latest_delivery_time", "ready_window", "vendor", "created_by_id", "timeline", "vendor_timeline", "vendor_note", "rider_note", "shopforme_fee", "service_fee", "delivery_pin", "delivery_pins", "is_confirmed", "rejected", "is_completed", "cancelled", "cancellation_reason", "items_count", "started_at", "completed_at", "created_at", "updated_at" ] } ] }, "AppCollectedRecordUpdateRequest": { "type": "object", "properties": { "values": { "type": "object", "description": "Record values keyed by field key. Each value\u2019s shape follows the field type on the definition.", "additionalProperties": {} }, "status": { "$ref": "#/components/schemas/CollectedRecordStatus" } }, "title": "AppCollectedRecordUpdateRequest" }, "AppMediaResource": { "type": "object", "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "variants": { "type": "string" }, "mime_type": { "type": "string" }, "size": { "type": "integer" }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "url", "thumbnail_url", "variants", "mime_type", "size", "width", "height", "created_at" ], "title": "AppMediaResource" }, "AppRequirementStoreRequest": { "type": "object", "description": "The requirements sheet for the calling installation (PUT app/requirements):\nthe app replaces its own {product \u2192 required line-property prefix} map in\none call.\n\nFull-body PUT \u2014 send the whole sheet every time, so a retry replays instead\nof merging and removals are explicit. Products are addressed by p_id (never\nUUID) and must belong to the calling installation's store. Each prefix must\nlive under the installation's own `app.{slug}.` namespace.", "properties": { "items": { "type": "array", "description": "`present` (not `required`): an emptied sheet is the explicit\nfull-removal signal, and an empty array is a valid sheet.", "items": { "type": "object", "properties": { "product_p_id": { "type": "integer", "minimum": 1 }, "prefix": { "type": "string", "description": "The required line-property prefix, e.g. `app.booking.`. It\nmust live under the calling installation's own app\nnamespace, so one installation can never declare for\nanother app's keys.", "pattern": "^app\\.[a-z0-9_]+\\.$", "maxLength": 64 } }, "required": [ "product_p_id", "prefix" ] }, "maxItems": 200 } }, "required": [ "items" ], "title": "AppRequirementStoreRequest" }, "AssignOrderRiderRequest": { "type": "object", "properties": { "rider_id": { "type": "string", "format": "uuid" } }, "required": [ "rider_id" ], "title": "AssignOrderRiderRequest" }, "BankResource": { "type": "object", "properties": { "id": { "type": "string" }, "account_number": { "type": "string" }, "account_name": { "type": "string" }, "bank_name": { "type": "string" }, "approved": { "type": "boolean" } }, "required": [ "id", "account_number", "account_name", "bank_name", "approved" ], "title": "BankResource" }, "BlogCategoryResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "position": { "type": "integer" }, "posts_count": { "type": "integer" } }, "required": [ "id", "name", "slug", "position" ], "title": "BlogCategoryResource" }, "BulkCreateVendorCollectionsRequest": { "type": "object", "properties": { "vendor_id": { "type": "string", "format": "uuid" }, "collections": { "type": "array", "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "collection_mode": { "type": [ "string", "null" ], "enum": [ "manual", "smart", null ] }, "collection_rules": { "type": [ "object", "null" ], "properties": { "conditions": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 60 } } } }, "required": [ "name" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "vendor_id", "collections" ], "title": "BulkCreateVendorCollectionsRequest" }, "BulkUpdatePublishRequest": { "type": "object", "properties": { "ids": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "published": { "type": "boolean" } }, "required": [ "ids", "published" ], "title": "BulkUpdatePublishRequest" }, "CartResource": { "title": "CartResource", "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "cart_id": { "type": "string" }, "item_id": { "type": "string" }, "title": { "type": "string" }, "variant_id": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ] }, "quantity": { "type": "string" }, "selectedAddons": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "subtotal": { "type": [ "number", "null" ] }, "product": { "$ref": "#/components/schemas/App.Http.Resources.Customer.ProductResource" }, "vendor": { "$ref": "#/components/schemas/VendorItemResource" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "id", "cart_id", "item_id", "title", "variant_id", "price", "quantity", "selectedAddons", "subtotal", "product", "vendor", "created_at", "updated_at" ] }, { "type": "object", "properties": { "id": { "type": "string" }, "vendor_id": { "type": "string" }, "vendor": { "$ref": "#/components/schemas/VendorItemResource" }, "cart_items": { "type": "array", "items": {} }, "total_price": { "type": [ "number", "null" ] }, "source": { "type": "string" }, "promo_codes": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "is_valid": { "type": "string" }, "validation_errors": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "last_validated_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "0": { "type": "object", "description": "The handoff for a vendor-built frontend: send the buyer here and the\nhosted storefront adopts this exact cart (?cart= wins on any URL) and\nruns checkout, payment and delivery on Queek. Guest carts only \u2014\nthat is the token the storefront can adopt." }, "discounts": { "type": "object", "additionalProperties": { "type": "object", "properties": { "amount_applied": { "type": [ "number", "null" ] } }, "required": [ "amount_applied" ], "additionalProperties": {} } }, "subtotal": { "type": [ "number", "null" ] }, "discount_total": { "type": [ "number", "null" ] }, "total_after_discounts": { "type": [ "number", "null" ] } }, "required": [ "id", "vendor_id", "vendor", "cart_items", "total_price", "source", "promo_codes", "is_valid", "validation_errors", "last_validated_at", "created_at", "updated_at", "0", "discounts", "subtotal", "discount_total", "total_after_discounts" ] } ] }, "ClientAuthUserResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "region": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ] }, "map_lat": { "type": [ "string", "null" ] }, "map_lng": { "type": [ "string", "null" ] }, "is_rider": { "type": "boolean" }, "rider_approved": { "type": "boolean", "description": "Whether this rider may actually open the storefront rider console \u2014\nis_rider alone is not enough, a vendor approval path must have\nstamped rider_approved_at (see EnsureClientRider). The storefront\nshows a \"pending approval\" state when is_rider && ! rider_approved." }, "profile_complete": { "type": "string" } }, "required": [ "id", "name", "email", "phone", "avatar", "country", "state", "region", "city", "address", "map_lat", "map_lng", "is_rider", "rider_approved", "profile_complete" ], "title": "ClientAuthUserResource" }, "CollectedDefinitionRequest": { "type": "object", "description": "Manage the calling installation's form types (GET + POST\ncollected-definitions, PATCH collected-definitions/{definition}).\n\nOne request shape serves all three verbs, with the same field-type,\nreserved-name, display and budget rules the dashboard enforces \u2014 every\nsurface accepts the same definitions. Installation types carry the `app_`\nprefix and declare it here. The data class is always `collected` and every\ndefinition belongs to the calling installation; neither is sent in the body.\n\nDefinitions are addressed by `p_id` within the installation's store. Types\nowned by another installation are refused with a 403.", "properties": { "type": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "maxLength": 64 }, "name": { "type": "string", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "display_field": { "type": "string", "maxLength": 64 }, "storefront_visible": { "type": [ "boolean", "null" ] }, "has_pages": { "type": [ "boolean", "null" ], "description": "Whether entries of this type get their own public page at\n`/{type}/{handle}`. A type matching a reserved storefront route\n(cart, checkout, search and similar) is refused with a 422." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "name": { "type": "string", "maxLength": 120 }, "type": { "type": "string", "enum": [ "single_line_text", "multi_line_text", "integer", "decimal", "boolean", "date", "url", "json", "media_id", "list.single_line_text", "list.multi_line_text", "list.integer", "list.decimal", "list.boolean", "list.date", "list.url", "list.media_id" ] }, "required": { "type": [ "boolean", "null" ] }, "validations": { "type": [ "object", "null" ], "properties": { "min": { "type": [ "string", "null" ] }, "max": { "type": [ "string", "null" ] }, "regex": { "type": [ "string", "null" ], "maxLength": 255 }, "choices": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 100 }, "metaobject_type": { "type": "string" } } } } }, "minItems": 1, "maxItems": 20 } }, "required": [ "type", "name", "display_field", "fields" ], "title": "CollectedDefinitionRequest" }, "CollectedRecordResource": { "type": "object", "properties": { "p_id": { "type": "integer" }, "definition_p_id": { "type": "integer" }, "type": { "type": [ "string", "null" ] }, "status": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "new" ] } ] }, "source": { "type": [ "string", "null" ] }, "submitted_at": { "type": "string", "format": "date-time" }, "values": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "p_id", "status", "source", "submitted_at", "values", "created_at", "updated_at" ], "title": "CollectedRecordResource" }, "CollectedRecordStatus": { "type": "string", "description": "Triage state of a collected record in the merchant's inbox. Values are merchant-set only (status is the one mutable column); rows are never edited, only triaged and eventually purged or deleted.\n", "enum": [ "new", "read", "archived", "spam" ], "title": "CollectedRecordStatus" }, "CollectedRecordSubmitRequest": { "type": "object", "description": "Submit one record under one of the calling installation's collected types\n(POST records).\n\nValues are validated against the type's fields \u2014 the same field rules the\ndashboard enforces \u2014 and the per-definition storage cap is checked before\nanything is written. Every record is filed under the calling installation\nwith source `app`: the body carries no source, so a submission can never be\nmisfiled under another source. Calls are rate-limited per installation, and\na validation failure (422) never consumes budget.\n\nTypes owned by another installation are refused with a 403.", "properties": { "definition": { "type": "string", "maxLength": 64 }, "values": { "type": "object", "description": "Record values keyed by field key. Each value\u2019s shape follows the field type on the definition.", "additionalProperties": {} } }, "required": [ "definition", "values" ], "title": "CollectedRecordSubmitRequest" }, "CollectionResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "description": { "type": [ "string", "null" ] }, "image": { "type": "string" }, "image_variants": { "type": [ "string", "null" ], "description": "Pre-sized copies of the image, resolved from its URL (categories\nand collections store no media id)." }, "featured": { "type": "boolean" }, "parent_id": { "type": [ "string", "null" ] }, "mode": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "smart", "manual" ] }, "ranking": { "type": [ "object", "null" ], "properties": { "sort": { "type": "string" }, "limit": {} }, "required": [ "sort", "limit" ] }, "sort": { "type": "string" }, "rules_count": { "type": "integer" }, "products_count": { "type": "integer" }, "children": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } }, "required": [ "id", "name", "slug", "description", "image", "image_variants", "featured", "parent_id", "mode", "type", "ranking", "sort", "rules_count", "products_count", "children" ], "title": "CollectionResource" }, "CouponResource": { "type": "object", "properties": { "id": { "type": "string" }, "code": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "discount_type": { "type": "string" }, "discount_value": { "type": "string" }, "applies_to": { "type": "string" }, "target_product_ids": { "type": "array", "items": {} }, "target_category_ids": { "type": "array", "items": {} }, "minimum_order_amount": { "type": "string" }, "capped_amount": { "type": [ "string", "null" ] }, "capped_amount_per_user": { "type": [ "string", "null" ] }, "usage_limit": { "type": [ "integer", "null" ] }, "usage_limit_per_user": { "type": [ "integer", "null" ] }, "used_count": { "type": "integer" }, "is_active": { "type": "boolean" }, "is_valid": { "type": "boolean" }, "is_expired": { "type": "boolean" }, "image_url": { "type": "string" }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "code", "title", "description", "discount_type", "discount_value", "applies_to", "target_product_ids", "target_category_ids", "minimum_order_amount", "capped_amount", "capped_amount_per_user", "usage_limit", "usage_limit_per_user", "used_count", "is_active", "is_valid", "is_expired", "image_url", "starts_at", "expires_at", "created_at", "updated_at" ], "title": "CouponResource" }, "CustomerAddressResource": { "type": "object", "properties": { "id": { "type": "string" }, "label": { "type": [ "string", "null" ] }, "address": { "type": "string" }, "lat": { "type": "number" }, "lng": { "type": "number" }, "country_code": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "area": { "type": [ "string", "null" ] }, "state_id": { "type": [ "string", "null" ] }, "area_id": { "type": [ "string", "null" ] }, "is_default": { "type": "boolean" } }, "required": [ "id", "label", "address", "lat", "lng", "country_code", "state", "city", "area", "state_id", "area_id", "is_default" ], "title": "CustomerAddressResource" }, "CustomerResource": { "type": "object", "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "avatar": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "uid", "name", "email", "phone", "avatar", "created_at", "updated_at" ], "title": "CustomerResource" }, "CustomerWishlistItemResource": { "type": "object", "properties": { "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "product": { "type": "array", "items": {} }, "variant": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "p_id": { "type": "integer" }, "title": { "type": "string" }, "option_values": { "type": "string" } }, "required": [ "id", "p_id", "title", "option_values" ] } }, "required": [ "created_at", "product", "variant" ], "title": "CustomerWishlistItemResource" }, "DiscountResource": { "type": "object", "properties": { "id": { "type": "string" }, "reference": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "string" }, "product_ids": { "type": "array", "items": {} }, "category_ids": { "type": "array", "items": {} }, "minimum_order_amount": { "type": "string" }, "minimum_quantity": { "type": "integer" }, "capped_amount": { "type": [ "string", "null" ] }, "capped_amount_per_user": { "type": [ "string", "null" ] }, "max_usage_total": { "type": [ "integer", "null" ] }, "max_usage_per_user": { "type": [ "integer", "null" ] }, "usage_count": { "type": "integer" }, "auto_apply": { "type": "boolean" }, "status": { "type": "string", "enum": [ "active", "inactive" ] }, "is_active": { "type": "boolean" }, "is_published": { "type": "boolean" }, "image_url": { "type": "string" }, "valid_from": { "type": [ "string", "null" ] }, "valid_until": { "type": [ "string", "null" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "reference", "title", "description", "type", "value", "product_ids", "category_ids", "minimum_order_amount", "minimum_quantity", "capped_amount", "capped_amount_per_user", "max_usage_total", "max_usage_per_user", "usage_count", "auto_apply", "status", "is_active", "is_published", "image_url", "valid_from", "valid_until", "published_at", "created_at", "updated_at" ], "title": "DiscountResource" }, "FollowerResource": { "type": "object", "properties": { "id": { "type": "string" }, "customer_id": { "type": [ "integer", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "avatar": { "type": [ "string", "null" ] }, "shared_contact": { "type": "boolean" }, "is_customer": { "type": "boolean" }, "followed_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "customer_id", "name", "email", "phone", "avatar", "shared_contact", "is_customer", "followed_at" ], "title": "FollowerResource" }, "ImportProductReviewsRequest": { "type": "object", "properties": { "app_id": { "type": "string" }, "source_app_id": { "type": "string" }, "source": { "type": "string" }, "reviews": { "type": "array", "items": { "type": "object", "properties": { "source_review_id": { "type": "string", "maxLength": 120 }, "product": { "type": "string", "maxLength": 255 }, "rating": { "type": "integer", "minimum": 1, "maximum": 5 }, "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ], "maxLength": 5000 }, "author_display_name": { "type": [ "string", "null" ], "maxLength": 120 }, "submitted_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": [ "string", "null" ], "format": "date-time" }, "media": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uri", "maxLength": 2048 }, "maxItems": 20 }, "user_id": { "type": "string" }, "order_id": { "type": "string" }, "vendor_id": { "type": "string" }, "source_app_id": { "type": "string" }, "source": { "type": "string" }, "status": { "type": "string" }, "is_verified_purchase": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" } }, "required": [ "source_review_id", "product", "rating", "title", "description", "author_display_name", "submitted_at", "edited_at", "media" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "reviews" ], "title": "ImportProductReviewsRequest" }, "ImportThirdPartyOrderRequest": { "type": "object", "description": "Import an order an outside sales channel already charged for. Generic app\nsource attribution comes from the authenticated installation.\n\nThe payload is the platform's receipt, recorded as charged. Item unit\nprices, delivery fee, discount and total are amounts in naira with at most\n2 decimals (6500 or \"6500.00\"), like every Merchant API amount, and they\nmust add up: the sum of unit_price \u00d7 quantity, plus delivery_fee, minus\ndiscount, equals total. Each item names its `product` (p_id, UUID or slug\nof a product in this store)\nand, for a variant, its `variant` (p_id or UUID of one of THAT product's\nvariants). The old single `ref` is refused: product and variant p_ids are\nseparate sequences, so one number could name two rows. A product from\nanother store fails the import with a named 422, never a cross-store sale.\n\nThe customer travels as name + phone only and becomes the order's\n`shipping_address` recipient; no customer record is created.", "properties": { "channel": { "type": "string", "enum": [ "chowdeck", "glovo" ], "description": "Optional for generic app installations, which derive source from the authenticated app and must omit this field. An installed Chowdeck or Glovo app must send its matching legacy slug. A generic app supplying this field, or a legacy app sending the other slug, receives 422. Human-key legacy imports still require this field and may send either slug." }, "external_ref": { "type": "string", "maxLength": 120 }, "placed_at": { "type": "string", "format": "date-time" }, "customer": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 120 }, "phone": { "type": "string", "maxLength": 30 } }, "required": [ "name", "phone" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "ref": { "type": "string", "description": "The old single `ref` resolved variant-first, then product, across\ntwo separate p_id sequences \u2014 one integer could name two rows.\nRefused outright (never aliased): the caller must say which." }, "product": { "type": "string", "maxLength": 120 }, "variant": { "type": [ "string", "null" ], "maxLength": 120 }, "quantity": { "type": "integer", "minimum": 1, "maximum": 1000 }, "unit_price": { "type": "number", "description": "Naira, at most 2 decimals \u2014 the Merchant API's one money rule\n(MerchantShippingZoneRequest's rates): a kobo figure is off by\n100x and runs past these caps instead of posing as naira.", "minimum": 0, "maximum": 1000000 } }, "required": [ "product", "quantity", "unit_price" ] }, "minItems": 1, "maxItems": 100 }, "delivery_fee": { "type": "number", "minimum": 0, "maximum": 1000000 }, "discount": { "type": "number", "minimum": 0, "maximum": 1000000 }, "total": { "type": "number", "minimum": 0.01, "maximum": 10000000 }, "fulfilment": { "type": "string", "enum": [ "delivery", "pickup" ] }, "notes": { "type": [ "string", "null" ], "maxLength": 2000 } }, "required": [ "external_ref", "placed_at", "customer", "items", "delivery_fee", "discount", "total", "fulfilment" ], "title": "ImportThirdPartyOrderRequest" }, "InventoryLevelResource": { "type": "object", "properties": { "product": { "type": "object", "properties": { "p_id": { "type": "integer" }, "slug": { "type": [ "string", "null" ] } }, "required": [ "p_id", "slug" ] }, "variant": { "type": [ "object", "null" ], "properties": { "p_id": { "type": "integer" } }, "required": [ "p_id" ] }, "quantity": { "type": "integer" }, "previous_quantity": { "type": "integer" }, "reason": { "type": "string" } }, "required": [ "product", "variant", "quantity", "previous_quantity", "reason" ], "title": "InventoryLevelResource" }, "InventoryOverviewResource": { "type": "object", "properties": { "total_products": { "type": "integer" }, "tracked_products": { "type": "integer" }, "untracked_products": { "type": "integer" }, "in_stock": { "type": "integer" }, "out_of_stock": { "type": "integer" }, "low_stock": { "type": "integer" }, "negative_stock": { "type": "integer" } }, "required": [ "total_products", "tracked_products", "untracked_products", "in_stock", "out_of_stock", "low_stock", "negative_stock" ], "title": "InventoryOverviewResource" }, "MerchantAppFileUploadRequest": { "type": "object", "properties": { "file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 10240 kilobytes." } }, "required": [ "file" ], "title": "MerchantAppFileUploadRequest" }, "MerchantCollectedRecord": { "$ref": "#/components/schemas/CollectedRecordResource", "title": "MerchantCollectedRecord" }, "MerchantCollection": { "$ref": "#/components/schemas/App.Http.Resources.Api.CollectionResource", "title": "MerchantCollection" }, "MerchantCoupon": { "$ref": "#/components/schemas/CouponResource", "title": "MerchantCoupon" }, "MerchantCustomer": { "$ref": "#/components/schemas/CustomerResource", "title": "MerchantCustomer" }, "MerchantDiscount": { "$ref": "#/components/schemas/DiscountResource", "title": "MerchantDiscount" }, "MerchantFollower": { "$ref": "#/components/schemas/FollowerResource", "title": "MerchantFollower" }, "MerchantImportedProductReviewResource": { "type": "object", "properties": { "source_review_id": { "type": "string" }, "source": { "type": [ "string", "null" ] }, "author_display_name": { "type": "string" }, "product_p_id": { "type": [ "string", "null" ] }, "rating": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "media": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "status": { "type": "string" }, "is_verified_purchase": { "type": "boolean" }, "submitted_at": { "type": "string", "format": "date-time" }, "created_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time" } }, "required": [ "source_review_id", "source", "author_display_name", "product_p_id", "rating", "title", "description", "media", "status", "is_verified_purchase", "submitted_at", "created_at", "edited_at" ], "title": "MerchantImportedProductReviewResource" }, "MerchantImportedReview": { "$ref": "#/components/schemas/MerchantImportedProductReviewResource", "title": "MerchantImportedReview" }, "MerchantInventoryAdjustment": { "$ref": "#/components/schemas/MerchantInventoryAdjustmentResource", "title": "MerchantInventoryAdjustment" }, "MerchantInventoryAdjustmentResource": { "type": "object", "properties": { "result": { "type": "string" }, "level": { "type": "object", "properties": { "product_p_id": { "type": "integer" }, "variant_p_id": { "type": [ "integer", "null" ] }, "mode": { "type": "string" }, "before": { "type": "string" }, "change": { "type": "string" }, "after": { "type": "string" }, "reason_code": { "type": "string" } }, "required": [ "product_p_id", "variant_p_id", "mode", "before", "change", "after", "reason_code" ] }, "adjustment": { "type": [ "array", "null" ], "items": {} } }, "required": [ "result", "level", "adjustment" ], "title": "MerchantInventoryAdjustmentResource" }, "MerchantInventoryLevelAdjustmentRequest": { "type": "object", "properties": { "product": { "type": "string", "maxLength": 255 }, "variant": { "type": [ "integer", "null" ], "minimum": 1 }, "mode": { "type": "string", "enum": [ "set", "delta" ] }, "quantity": { "type": "integer", "minimum": -1000000, "maximum": 1000000 }, "expected_stock": { "type": "integer", "minimum": -1000000, "maximum": 1000000 }, "reason_code": { "type": "string", "enum": [ "correction", "count", "damage", "received", "return", "theft", "other" ] }, "note": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "product", "mode", "quantity", "reason_code" ], "title": "MerchantInventoryLevelAdjustmentRequest" }, "MerchantInventoryLevels": { "$ref": "#/components/schemas/MerchantInventoryLevelsResource", "title": "MerchantInventoryLevels" }, "MerchantInventoryLevelsResource": { "type": "object", "properties": { "p_id": { "type": "integer" }, "slug": { "type": "string" }, "barcode": { "type": "string" }, "stock": { "type": "integer" }, "effective_tracking": { "type": "string" }, "variants": { "type": "string" } }, "required": [ "p_id", "slug", "barcode", "stock", "effective_tracking", "variants" ], "title": "MerchantInventoryLevelsResource" }, "MerchantMedia": { "$ref": "#/components/schemas/AppMediaResource", "title": "MerchantMedia" }, "MerchantOrder": { "$ref": "#/components/schemas/OrderResource", "title": "MerchantOrder" }, "MerchantPost": { "$ref": "#/components/schemas/PostResource", "title": "MerchantPost" }, "MerchantProduct": { "$ref": "#/components/schemas/ProductResource", "title": "MerchantProduct" }, "MerchantProductImage": { "$ref": "#/components/schemas/ProductImageResource", "title": "MerchantProductImage" }, "MerchantShippingZone": { "$ref": "#/components/schemas/ShippingZoneResource", "title": "MerchantShippingZone" }, "MerchantShippingZoneRequest": { "type": "object", "description": "POST shipping-zones / PUT shipping-zones/{zone} on the merchant API.\n\nZone rules match the dashboard's, except the rates: this API speaks money as\ndecimal strings in the currency's major unit (\"1500.00\", or a number) \u2014 the\nsame shape a zone read returns, so a read round-trips into a write. Values\nare stored in the currency's minor unit; the dashboard sends minor-unit\nintegers directly.", "properties": { "name": { "type": "string", "maxLength": 100 }, "zone_type": { "type": "string", "enum": [ "local", "national", "international" ] }, "countries": { "type": [ "array", "null" ], "items": { "type": "string", "minLength": 2, "maxLength": 2 } }, "state_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "area_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "base_rate": { "type": "number", "minimum": 0, "maximum": 21474836.47 }, "per_kg_rate": { "type": [ "number", "null" ], "minimum": 0, "maximum": 21474836.47 }, "min_weight_kg": { "type": [ "number", "null" ], "minimum": 0 }, "max_weight_kg": { "type": [ "number", "null" ] }, "min_days": { "type": "integer", "minimum": 1 }, "max_days": { "type": "integer" }, "active": { "type": [ "boolean", "null" ] }, "sort_order": { "type": [ "integer", "null" ], "minimum": 0 } }, "required": [ "name", "zone_type", "base_rate", "min_days", "max_days" ], "title": "MerchantShippingZoneRequest" }, "MerchantStockAdjustment": { "$ref": "#/components/schemas/StockAdjustmentResource", "title": "MerchantStockAdjustment" }, "MerchantStorePostRequest": { "type": "object", "description": "POST posts on the merchant API: a markdown-body blog-post create.\n\nThe key authorizes the store; no vendor_id input is read. `slug` is\nnormalised with Str::slug only when it arrives as a string.", "properties": { "title": { "type": "string", "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "maxLength": 255 }, "body": { "type": [ "string", "null" ], "maxLength": 100000 }, "excerpt": { "type": [ "string", "null" ] }, "cover_image_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "status": { "type": [ "string", "null" ], "enum": [ "draft", "published", null ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 100 }, "maxItems": 20 }, "seo": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "og_image": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "canonical_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "keywords": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 80 } }, "noindex": { "type": [ "boolean", "null" ] } } } }, "required": [ "title", "seo" ], "title": "MerchantStorePostRequest" }, "MerchantTeamMember": { "$ref": "#/components/schemas/TeamDirectoryResource", "title": "MerchantTeamMember" }, "MerchantUpdatePostRequest": { "type": "object", "description": "PUT posts/{post} on the merchant API: a partial markdown-body update.\n\nAbsent stays untouched; explicit-null clears ONLY excerpt,\ncover_image_url, tags, and seo; null/blank slug keeps the existing slug.\n`slug` is normalised with Str::slug only when it arrives as a string, and\nthe scoped unique ignores the resolved row.", "properties": { "title": { "type": "string", "maxLength": 255 }, "slug": { "type": [ "string", "null" ], "maxLength": 255 }, "body": { "type": [ "string", "null" ], "maxLength": 100000 }, "excerpt": { "type": [ "string", "null" ] }, "cover_image_url": { "type": [ "string", "null" ], "maxLength": 2048 }, "status": { "type": "string", "enum": [ "draft", "published" ] }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 100 }, "maxItems": 20 }, "seo": { "type": "object", "properties": { "title": { "type": [ "string", "null" ], "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "og_image": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "canonical_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "keywords": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 80 } }, "noindex": { "type": [ "boolean", "null" ] } } } }, "required": [ "seo" ], "title": "MerchantUpdatePostRequest" }, "MerchantWishlistItem": { "$ref": "#/components/schemas/CustomerWishlistItemResource", "title": "MerchantWishlistItem" }, "MetafieldDefinitionRequest": { "type": "object", "description": "Create/update a metafield definition on the REST developer surface.\n\n`namespace`, `key`, `owner_type` and `type` are immutable after creation: a\nstored value denormalises all four, so changing one would silently orphan\nevery value already written against it. Only presentation (`name`,\n`description`) and `validations` may change, and a tightened validation is\ndocumented as applying to future writes only.\n\nThe same rules back every surface that writes definitions, so all of them\naccept exactly the same legal definitions.", "properties": { "owner_type": { "type": "string", "enum": [ "product", "order" ] }, "namespace": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "type": { "type": "string", "enum": [ "single_line_text", "multi_line_text", "integer", "decimal", "boolean", "date", "url", "json", "media_id", "metaobject_reference", "list.single_line_text", "list.multi_line_text", "list.integer", "list.decimal", "list.boolean", "list.date", "list.url", "list.media_id", "list.metaobject_reference" ] }, "storefront_visible": { "type": [ "boolean", "null" ] }, "pinned": { "type": [ "boolean", "null" ] }, "pinned_position": { "type": [ "integer", "null" ], "minimum": 0 }, "name": { "type": [ "string", "null" ], "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "validations": { "type": "object", "properties": { "min": { "type": [ "string", "null" ] }, "max": { "type": [ "string", "null" ] }, "regex": { "type": [ "string", "null" ], "maxLength": 255 }, "choices": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 100 }, "metaobject_type": { "type": [ "string", "null" ], "maxLength": 64 } } } }, "required": [ "owner_type", "namespace", "key", "type" ], "title": "MetafieldDefinitionRequest" }, "MetafieldDefinitionResource": { "type": "object", "properties": { "p_id": { "type": "integer" }, "handle": { "type": "string" }, "owner_type": { "type": "string" }, "namespace": { "type": "string" }, "key": { "type": "string" }, "type": { "type": "string" }, "storefront_visible": { "type": "boolean" }, "pinned": { "type": "boolean" }, "pinned_position": { "type": [ "integer", "null" ] }, "name": { "type": "string" }, "description": { "type": "string" }, "validations": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "p_id", "handle", "owner_type", "namespace", "key", "type", "storefront_visible", "pinned", "pinned_position", "name", "description", "validations", "created_at", "updated_at" ], "title": "MetafieldDefinitionResource" }, "MetaobjectDataClass": { "type": "string", "description": "What KIND of data a metaobject definition holds. `content` is merchant content (designers, size charts): entries may be storefront-visible and carry their own pages. `collected` is data gathered FROM people (form submissions, applications): entries are never storefront-readable and never revalidate the storefront. The booleans (`storefront_visible`, `has_pages`) stay the permanent source of truth \u2014 a collected definition is always stored with both off, however it is written.\n", "enum": [ "content", "collected" ], "title": "MetaobjectDataClass" }, "MetaobjectDefinitionRequest": { "type": "object", "description": "Create/update a metaobject definition on the REST developer surface.\n\n`type` is immutable after creation: entries carry it, and reference values\nresolve through it, so changing one would silently orphan every entry and\nlink already written against it. The field SET may be replaced on update,\nbut removing a field (or retyping one) while entries still hold values for\nit is a 422.\n\nThe same rules back every surface that writes definitions, so all of them\naccept exactly the same legal types.", "properties": { "type": { "type": "string", "pattern": "^[a-z][a-z0-9_]{1,63}$", "maxLength": 64 }, "name": { "type": "string", "maxLength": 120 }, "description": { "type": [ "string", "null" ], "maxLength": 1000 }, "display_field": { "type": "string", "maxLength": 64 }, "storefront_visible": { "type": [ "boolean", "null" ] }, "has_pages": { "type": [ "boolean", "null" ], "description": "Whether entries of this type get their own public page at\n`/{type}/{handle}`. A type matching a reserved storefront route\n(cart, checkout, search and similar) is refused with a 422." }, "fields": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "pattern": "^[a-z][a-z0-9_]*$", "maxLength": 64 }, "name": { "type": "string", "maxLength": 120 }, "type": { "type": "string", "enum": [ "single_line_text", "multi_line_text", "integer", "decimal", "boolean", "date", "url", "json", "media_id", "list.single_line_text", "list.multi_line_text", "list.integer", "list.decimal", "list.boolean", "list.date", "list.url", "list.media_id" ] }, "required": { "type": [ "boolean", "null" ] }, "validations": { "type": [ "object", "null" ], "properties": { "min": { "type": [ "string", "null" ] }, "max": { "type": [ "string", "null" ] }, "regex": { "type": [ "string", "null" ], "maxLength": 255 }, "choices": { "type": [ "array", "null" ], "items": { "type": "string" }, "maxItems": 100 }, "metaobject_type": { "type": "string" } } } } }, "minItems": 1, "maxItems": 20 }, "data_class": { "anyOf": [ { "$ref": "#/components/schemas/MetaobjectDataClass" }, { "type": "null" } ] }, "entry_cap_override": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 1000000 }, "retention_days": { "type": [ "integer", "null" ], "minimum": 1, "maximum": 3650 } }, "required": [ "type", "name", "display_field", "fields" ], "title": "MetaobjectDefinitionRequest" }, "MetaobjectDefinitionResource": { "type": "object", "properties": { "p_id": { "type": "integer" }, "type": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" }, "display_field": { "type": "string" }, "storefront_visible": { "type": "boolean" }, "has_pages": { "type": "boolean" }, "data_class": { "description": "The definition's data class (`content` or `collected`). Read-only\nhere: it is fixed at creation and cannot be changed through\nthis API.", "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "content" ] } ] }, "entry_cap_override": { "type": [ "integer", "null" ] }, "retention_days": { "type": [ "integer", "null" ] }, "fields": { "type": "array", "items": {} }, "entries_count": { "type": "integer" }, "records_count": { "type": [ "integer", "null" ], "description": "How many entries a collected definition holds (null for content\ndefinitions). Rendered on dashboard reads only, so store-key\nresponses never carry it." }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } }, "required": [ "p_id", "type", "name", "description", "display_field", "storefront_visible", "has_pages", "data_class", "entry_cap_override", "retention_days", "fields", "created_at", "updated_at" ], "title": "MetaobjectDefinitionResource" }, "MetaobjectRequest": { "type": "object", "description": "Create/update a metaobject entry on the REST developer surface.\n\nShape is checked first (`type` exists, `handle` is slug-shaped, `status` is\nknown). Each field value is then validated against its definition \u2014 an\nunknown key or a wrong-typed value fails with a `fields.{key}` error.", "properties": { "type": { "type": "string", "maxLength": 64 }, "handle": { "type": [ "string", "null" ], "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 120 }, "status": { "type": [ "string", "null" ], "enum": [ "active", "draft", null ] }, "fields": { "type": "array", "items": { "type": "string" }, "minItems": 1 } }, "required": [ "type", "fields" ], "title": "MetaobjectRequest" }, "MetaobjectResource": { "type": "object", "additionalProperties": {}, "title": "MetaobjectResource" }, "OrderItemResource": { "type": "object", "properties": { "id": { "type": "string" }, "quantity": { "type": "integer" }, "title": { "type": [ "string", "null" ] }, "variant_id": { "type": [ "string", "null" ] }, "variant_title": { "type": [ "string", "null" ] }, "variant_option_values": { "type": "object", "additionalProperties": { "type": "string" } }, "variant_media": { "type": [ "object", "null" ], "properties": { "image": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ] }, "source": { "type": "string", "enum": [ "variant", "product" ] } }, "required": [ "image", "video_url", "source" ] }, "currency": { "type": "string" }, "total_price": { "type": [ "number", "null" ] }, "sale_price": { "type": [ "number", "null" ] }, "unit_price": { "type": [ "number", "null" ] }, "base_unit_price": { "type": [ "number", "null" ] }, "is_backorder": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ] }, "discounted_amount": { "type": [ "number", "null" ] }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "addons": {}, "properties": { "type": "string", "description": "Per-line checkout properties. Always present as an object so\ndashboard chips and the shopper page never branch on absence.\nBearer keys are withheld here too (dashboard, shopper page,\nrider): the order email is their only carrier." } }, "required": [ "id", "quantity", "title", "variant_id", "variant_title", "variant_option_values", "variant_media", "currency", "total_price", "sale_price", "unit_price", "base_unit_price", "is_backorder", "backorder_ready_date", "created_at", "addons", "properties" ], "title": "OrderItemResource" }, "OrderResource": { "type": "object", "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "order_number": { "type": "string" }, "status": { "type": "string" }, "payment_status": { "type": "string" }, "payment_method": { "type": "string" }, "fulfillment_status": { "type": "string", "enum": [ "fulfilled", "unfulfilled" ] }, "cancelled": { "type": "boolean" }, "cancel_reason": { "type": [ "string", "null" ] }, "channel": { "type": "string", "description": "`channel` is the messaging channel the order came through \u2014 never\nthe sales channel. The installed app source and caller reference\nare exposed in the two keys below." }, "platform": { "type": [ "string", "null" ] }, "custom_channel": { "type": "string", "description": "Import recognition: the sales channel that imported the order\n(an app slug or legacy channel \u2014 null unless imported) and the\noutside platform's own reference (null unless imported). Together with\n`platform` (third_party) an app matches orders events to its\nown records with no link table. Additive: both keys are null\nfor every order that is not an import." }, "external_ref": { "type": "string" }, "delivery_method": { "type": "string" }, "currency": { "type": "string", "description": "Vendor chain with the same unloaded-relation safety net as the\nsibling order shapes: loaded relation first, then the\ncache-backed lookup \u2014 never the silent platform default." }, "subtotal": { "type": "string" }, "discount_total": { "type": "string" }, "shipping_total": { "type": "string" }, "tax_total": { "type": "string" }, "total": { "type": "string" }, "customer": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "id", "name", "email", "phone" ] }, "shipping_address": { "type": [ "object", "null" ], "properties": { "address": { "type": [ "string", "null" ] }, "latitude": { "type": [ "number", "null" ] }, "longitude": { "type": [ "number", "null" ] }, "name": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] } }, "required": [ "address", "latitude", "longitude", "name", "phone" ] }, "shipment": { "type": [ "object", "null" ], "properties": { "carrier_name": { "type": [ "string", "null" ] }, "tracking_number": { "type": [ "string", "null" ] }, "tracking_url": { "type": [ "string", "null" ] }, "zone_name": { "type": [ "string", "null" ] }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time" }, "estimated_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "carrier_name", "tracking_number", "tracking_url", "zone_name", "shipped_at", "estimated_delivery_at", "delivered_at" ] }, "line_items": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": "string" }, "product_id": { "type": [ "integer", "null" ] }, "product_uid": { "type": [ "string", "null" ] }, "title": { "type": "string" }, "variant_title": { "type": "string" }, "quantity": { "type": "integer" }, "unit_price": { "type": "string" }, "total": { "type": "string" }, "properties": { "type": "string", "description": "Per-line checkout properties (jsonb, array-cast). Absent lines\nrender an empty object, never null \u2014 apps always see the key.\nAn app's single-use keys (claims, manage links) reach only the\napp that issued them, never another app or key." } }, "required": [ "id", "product_id", "product_uid", "title", "variant_title", "quantity", "unit_price", "total", "properties" ] } }, "note": { "type": "string" }, "metafields": { "type": "string", "description": "The receiver's own fields coming back to them: typed metafields the\nmerchant defined, and the opaque metadata an integrator wrote. This\nis the whole point of order extensions \u2014 a webhook that omits the\nERP id forces the receiver to make a second call to match the order\nto their own record." }, "metadata": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "fulfilled_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "uid", "order_number", "status", "payment_status", "payment_method", "fulfillment_status", "cancelled", "cancel_reason", "channel", "platform", "custom_channel", "external_ref", "delivery_method", "currency", "subtotal", "discount_total", "shipping_total", "tax_total", "total", "customer", "shipping_address", "shipment", "line_items", "note", "metafields", "metadata", "created_at", "updated_at", "fulfilled_at" ], "additionalProperties": {}, "title": "OrderResource" }, "PinCollectionProductRequest": { "type": "object", "properties": { "product_id": { "type": "string", "format": "uuid" }, "pinned": { "type": [ "boolean", "null" ] } }, "required": [ "product_id" ], "title": "PinCollectionProductRequest" }, "PostResource": { "type": "object", "properties": { "id": { "type": "string" }, "parent_id": { "type": [ "string", "null" ] }, "blog_category_ids": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "type": { "type": "string" }, "template": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "content": { "type": "string" }, "excerpt": { "type": "string" }, "cover_image_url": { "type": "string" }, "status": { "type": "string" }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "seo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "position": { "type": "integer" }, "is_home": { "type": "boolean" }, "chrome": { "type": "string" }, "show_page_title": { "type": "boolean" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "parent_id", "blog_category_ids", "type", "template", "slug", "title", "content", "excerpt", "cover_image_url", "status", "tags", "seo", "position", "is_home", "chrome", "show_page_title", "published_at", "created_at", "updated_at" ], "title": "PostResource" }, "ProductImageResource": { "type": "object", "properties": { "id": { "type": [ "integer", "null" ] }, "is_primary": { "type": "string" }, "position": { "type": "string" }, "url": { "type": "string" }, "alt": { "type": [ "string", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "variants": { "type": "string" } }, "required": [ "id", "is_primary", "position", "url", "alt", "width", "height", "variants" ], "title": "ProductImageResource" }, "ProductQuestionResource": { "type": "object", "properties": { "id": { "type": "string" }, "question": { "type": "string" }, "answer": { "type": "string" }, "status": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "answered_at": { "type": "string", "format": "date-time" }, "user": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "avatar": { "type": "string" } }, "required": [ "id", "name", "avatar" ] }, "product": { "type": [ "object", "null" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "id", "slug", "title", "thumbnail" ] } }, "required": [ "id", "question", "answer", "status", "created_at", "answered_at" ], "title": "ProductQuestionResource" }, "ProductRequest": { "type": "object", "properties": { "metafields": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "namespace": { "type": "string", "maxLength": 64 }, "key": { "type": "string", "maxLength": 64 }, "value": { "type": [ "string", "null" ] } } }, "maxItems": 50 }, "metadata": { "type": [ "array", "null" ], "description": "Free-form integrator bookkeeping: opaque strings in, the same\nstrings out. Never interpreted, never rendered \u2014 so the only rules\nit can carry are size and count.", "items": { "type": [ "string", "null" ], "maxLength": 500 }, "maxItems": 50 }, "title": { "type": "string", "maxLength": 191 }, "slug": { "type": "string", "description": "Update only: the merchant chose a new URL slug when renaming. Never empty, never a duplicate.", "pattern": "^[a-z0-9]+(?:-[a-z0-9]+)*$", "maxLength": 100 }, "stock": { "type": [ "integer", "null" ], "minimum": 0 }, "track_inventory": { "type": [ "boolean", "null" ] }, "in_stock": { "type": [ "boolean", "null" ] }, "service_id": { "type": [ "string", "null" ] }, "type": { "type": [ "string", "null" ], "maxLength": 50 }, "barcode": { "type": [ "string", "null" ], "description": "'addons' => 'nullable',", "maxLength": 100 }, "expiry_date": { "type": [ "string", "null" ], "format": "date-time" }, "is_backorder": { "type": [ "boolean", "null" ] }, "backorder_ready_date": { "type": [ "string", "null" ], "format": "date-time" }, "description": { "type": [ "string", "null" ], "maxLength": 50000 }, "excerpt": { "type": [ "string", "null" ], "maxLength": 5000 }, "image_file": { "type": "string", "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 2048 kilobytes." }, "image_media_id": { "type": [ "integer", "null" ] }, "tags": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 100 } }, "featured": { "type": [ "string", "null" ] }, "min_qty": { "type": [ "string", "null" ] }, "max_qty": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ], "minimum": 0 }, "unit": { "type": [ "string", "null" ] }, "categories": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 2 }, "taxonomy_node_id": { "type": [ "string", "null" ], "description": "Node fields are accepted regardless of the A3 flag so clients can\nship node-based payloads before the flag flips (and survive a\nrollback). Flag off, a node with no legacy input resolves to the\nlegacy write; legacy input wins when both are sent." }, "taxonomy_slug": { "type": [ "string", "null" ] }, "taxonomy_category_id": { "type": "string" }, "collection_category_ids": { "type": "array", "items": { "type": "string" } }, "variations": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "has_variants": { "type": "boolean" }, "variants": { "type": "array", "items": { "type": "object", "properties": { "id": { "type": [ "string", "null" ], "format": "uuid" }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "barcode": { "type": [ "string", "null" ], "maxLength": 100 }, "title": { "type": "string", "maxLength": 150 }, "option_values": { "type": "array", "items": { "type": "string" }, "minItems": 1 }, "price": { "type": "number", "minimum": 0 }, "compare_at_price": { "type": [ "number", "null" ], "minimum": 0 }, "stock": { "type": [ "integer", "null" ], "minimum": 0 }, "track_inventory": { "type": [ "boolean", "null" ] }, "is_active": { "type": [ "boolean", "null" ] }, "weight": { "type": [ "number", "null" ], "minimum": 0 }, "position": { "type": [ "integer", "null" ], "minimum": 0 }, "is_backorder": { "type": [ "boolean", "null" ] }, "backorder_ready_date": { "type": [ "string", "null" ], "format": "date-time" } } } }, "cost_price": { "type": [ "number", "null" ], "minimum": 0 }, "currency": { "type": [ "string", "null" ], "minLength": 3, "maxLength": 3 }, "is_digital": { "type": [ "boolean", "null" ] }, "is_pos": { "type": [ "boolean", "null" ] }, "is_instore": { "type": [ "boolean", "null" ] }, "is_online": { "type": [ "boolean", "null" ] }, "is_marketplace": { "type": [ "boolean", "null" ] }, "is_inboxes": { "type": [ "boolean", "null" ] }, "is_wholesale": { "type": [ "boolean", "null" ] }, "wholesale_price": { "type": [ "number", "null" ], "minimum": 0 }, "wholesale_min_qty": { "type": [ "integer", "null" ], "minimum": 1 }, "published": { "type": [ "string", "null" ] }, "approved": { "type": [ "string", "null" ] }, "price": { "type": "number", "minimum": 5 }, "sku": { "type": [ "string", "null" ], "description": "Product-level identity/pricing for products WITHOUT variants\n(Shopify default-variant parity). Prohibited the moment\nvariants are in play \u2014 variants carry their own\nsku/compare_at_price and the product-level pair is ignored\nthere, never merged.", "maxLength": 100 }, "compare_at_price": { "type": [ "number", "null" ], "minimum": 0 }, "images": { "type": [ "string", "null" ] }, "image_url": { "type": [ "string", "null" ] }, "video_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "video_file": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 51200 kilobytes." }, "video_media_id": { "type": [ "integer", "null" ] }, "video_poster_url": { "type": [ "string", "null" ], "format": "uri", "description": "Optional still image for the video \u2014 falls back to the product's own\nprimary image when unset, so no dimension/square ceremony like the\nprimary image's own rules (never a hard requirement).", "maxLength": 2048 }, "video_poster_file": { "type": [ "string", "null" ], "format": "binary", "contentMediaType": "application/octet-stream", "description": "Maximum file size: 2048 kilobytes." }, "video_poster_media_id": { "type": [ "integer", "null" ] }, "variant_media": { "type": "object", "properties": { "by_variant_id": { "type": "array", "items": { "type": "object", "properties": { "image_media_id": { "type": "string" } } } }, "by_option_values": { "type": "array", "items": { "type": "object", "properties": { "image_media_id": { "type": "string" } } } } } }, "gallery_media_ids": { "type": [ "array", "null" ], "description": "The product's other photos, after the main one, in order (media ids of the store's files)", "items": { "type": "integer" } } }, "required": [ "title", "categories", "price" ], "title": "ProductRequest" }, "ProductResource": { "type": "object", "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "description": { "type": "string" }, "status": { "type": "string", "enum": [ "active", "out_of_stock", "draft", "archived" ] }, "published": { "type": "boolean" }, "in_stock": { "type": "boolean" }, "price": { "type": "string" }, "storefront_price": { "type": "string" }, "storefront_compare_at_price": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "currency": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "stock": { "type": [ "integer", "null" ] }, "track_inventory": { "type": "boolean" }, "is_digital": { "type": "boolean" }, "has_variants": { "type": "boolean" }, "image": { "type": "string" }, "thumbnail_image": { "type": "string" }, "primary_image_url": { "type": [ "string", "null" ] }, "variants": { "type": "array", "items": { "$ref": "#/components/schemas/ProductVariantResource" } }, "options": { "type": "array", "description": "Product-level options derived from the ACTIVE variants (no\noptions table \u2014 ordered by first appearance over the\nposition-sorted set). In-memory over the variants already\nloaded above: zero extra queries.", "items": {} }, "images": { "type": "array", "items": { "$ref": "#/components/schemas/ProductImageResource" } }, "metafields": { "type": "string", "description": "The receiver's own fields coming back to them: typed metafields\nthe merchant defined, and the opaque metadata an integrator\nwrote. Same reason the order payload carries both." }, "metadata": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "deleted_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "uid", "title", "slug", "excerpt", "description", "status", "published", "in_stock", "price", "storefront_price", "storefront_compare_at_price", "url", "currency", "sku", "barcode", "stock", "track_inventory", "is_digital", "has_variants", "image", "thumbnail_image", "primary_image_url", "variants", "options", "images", "metafields", "metadata", "created_at", "updated_at", "deleted_at" ], "title": "ProductResource" }, "ProductReviewResource": { "type": "object", "properties": { "id": { "type": "string" }, "rating": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "media": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "vendor_response": { "type": "string" }, "vendor_response_at": { "type": "string", "format": "date-time" }, "status": { "type": "string" }, "is_verified_purchase": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ] }, "author_display_name": { "type": "string" }, "user": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "id", "slug", "title", "thumbnail" ] } }, "required": [ "id", "rating", "title", "description", "media", "vendor_response", "vendor_response_at", "status", "is_verified_purchase", "created_at", "updated_at", "edited_at", "submitted_at", "source", "author_display_name" ], "title": "ProductReviewResource" }, "ProductVariantResource": { "type": "object", "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "sku": { "type": "string" }, "barcode": { "type": "string" }, "title": { "type": "string" }, "option_values": { "type": "string" }, "price": { "type": "string" }, "storefront_price": { "type": "string" }, "storefront_compare_at_price": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "compare_at_price": { "type": [ "string", "null" ] }, "stock": { "type": "integer" }, "track_inventory": { "type": "boolean" }, "is_digital": { "type": "boolean", "description": "Product-level flag, inherited read-only: variants carry no\nis_digital column, so a missing parent reads false, never throws." }, "is_active": { "type": "boolean" }, "is_backorder": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ] }, "weight": { "type": [ "number", "null" ] }, "position": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "uid", "sku", "barcode", "title", "option_values", "price", "storefront_price", "storefront_compare_at_price", "url", "compare_at_price", "stock", "track_inventory", "is_digital", "is_active", "is_backorder", "backorder_ready_date", "weight", "position", "created_at", "updated_at" ], "title": "ProductVariantResource" }, "PromotionResource": { "type": "object", "properties": { "id": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "image_url": { "type": "string" }, "type": { "type": "string" }, "value": { "type": "number" }, "priority": { "type": "integer" }, "valid_from": { "type": [ "string", "null" ] }, "valid_until": { "type": [ "string", "null" ] }, "status": { "type": "string", "const": "expired" }, "is_live": { "type": "boolean" } }, "required": [ "id", "title", "description", "image_url", "type", "value", "priority", "valid_from", "valid_until", "status", "is_live" ], "title": "PromotionResource" }, "QueekError": { "type": "object", "description": "The error envelope every error body answers. Switch on `error.code`, never on the message. The additive legacy-compatibility top-level keys some surfaces emit beside it (`error_code`, `message`, and \u2014 on non-reissued surfaces only \u2014 `request_id`, `doc_url`) are documented separately under `QueekLegacyErrorKeys`, which no operation references.", "properties": { "error": { "type": "object", "description": "The canonical error. Switch on `error.code`, never on the message.", "properties": { "code": { "type": "string", "enum": [ "ai_unavailable_in_test_mode", "api_key_expired", "api_key_mode_mismatch", "api_key_revoked", "app_embed_not_ready", "app_grant_insufficient", "app_handoff_failed", "app_installation_gone", "app_installation_pending", "app_ip_not_allowed", "app_proxy_failed", "app_proxy_gone", "app_token_revoked", "bad_request", "channel_gateway_unreachable", "client_key_required", "conflict", "custom_domain_provisioning_failed", "custom_gateway_forbidden", "custom_gateway_kyc_required", "custom_gateway_not_configured", "custom_gateway_not_verified", "custom_gateway_plan_required", "custom_gateway_store_ineligible", "custom_gateway_verification_failed", "forbidden", "gone", "idempotency_key_in_progress", "idempotency_key_reuse", "insufficient_scope", "invalid_client", "invalid_client_key", "metafield_definition_missing", "metafield_filter_unsupported_type", "metafield_namespace_reserved", "metafield_value_invalid", "metaobject_definition_missing", "metaobject_field_invalid", "metaobject_reference_invalid", "metaobject_type_reserved", "method_not_allowed", "not_found", "origin_not_allowed", "origin_required", "payload_too_large", "payment_amount_mismatch", "plan_inactive", "private_key_required", "requires_slot", "resync_cooldown", "route_not_available", "server_error", "service_unavailable", "subscription_feature_locked", "too_many_requests", "translation_digest_stale", "translation_locale_is_primary", "translation_max_published_locales", "translation_unknown_key", "translation_unknown_locale", "unauthenticated", "unknown_product_ref", "unknown_service", "unknown_variant_ref", "unsupported_media_type", "validation_failed", "vendor_access_denied", "vendor_mail_sender_forbidden", "vendor_mail_sender_not_configured", "vendor_mail_sender_plan_required", "vendor_mail_sender_verification_failed" ], "description": "Stable identifier a client switches on. A new failure mode gets a new code; an existing code never changes meaning." }, "message": { "type": "string", "description": "Human-readable explanation. Not stable \u2014 never switch on it." }, "field": { "type": [ "string", "null" ], "description": "First offending field, on validation failures only." }, "errors": { "type": "object", "additionalProperties": { "type": "array", "items": { "type": "string" } }, "description": "Per-field validation messages, on validation failures only." }, "doc_url": { "type": "string", "description": "Deep link to this code in the error reference: https://docs.usequeek.com/docs/versioning-and-errors#." }, "request_id": { "type": "string", "description": "The X-Request-Id of this request. Always a string. Quote it in support." } }, "required": [ "code", "message", "doc_url" ] } }, "required": [ "error" ] }, "QueekMerchantStore": { "$ref": "#/components/schemas/StoreResource", "title": "QueekMerchantStore" }, "QueekMetafieldType": { "type": "string", "description": "A metafield definition's `type`. Scalar forms, plus `list.` for each listable one.\n\nLimits (shared Postgres, part of the contract): 200 definitions per store, 50 values per resource, 65536 bytes per serialized value. Free-form `metadata`: 50 keys, key \u2264 64 chars, value \u2264 500 chars.\n\nReserved namespaces (a store may not define in these): `queek`.\nOwner types wired in this version: `product`, `order`.", "enum": [ "single_line_text", "multi_line_text", "integer", "decimal", "boolean", "date", "url", "json", "media_id", "metaobject_reference", "list.single_line_text", "list.multi_line_text", "list.integer", "list.decimal", "list.boolean", "list.date", "list.url", "list.media_id", "list.metaobject_reference" ], "title": "QueekMetafieldType" }, "QueekStoreAddress": { "$ref": "#/components/schemas/CustomerAddressResource", "title": "QueekStoreAddress" }, "QueekStoreBlogCategory": { "$ref": "#/components/schemas/BlogCategoryResource", "title": "QueekStoreBlogCategory" }, "QueekStoreCart": { "$ref": "#/components/schemas/CartResource", "title": "QueekStoreCart" }, "QueekStoreCategory": { "$ref": "#/components/schemas/TaxonomyCategoryResource", "title": "QueekStoreCategory" }, "QueekStoreCollection": { "$ref": "#/components/schemas/CollectionResource", "title": "QueekStoreCollection" }, "QueekStoreCustomer": { "$ref": "#/components/schemas/ClientAuthUserResource", "title": "QueekStoreCustomer" }, "QueekStoreLocale": { "$ref": "#/components/schemas/StoreLocaleResource", "title": "QueekStoreLocale" }, "QueekStoreMetafieldDefinition": { "$ref": "#/components/schemas/MetafieldDefinitionResource", "title": "QueekStoreMetafieldDefinition" }, "QueekStoreMetaobject": { "$ref": "#/components/schemas/MetaobjectResource", "title": "QueekStoreMetaobject" }, "QueekStoreOrder": { "$ref": "#/components/schemas/App.Http.Resources.OrderResource", "title": "QueekStoreOrder" }, "QueekStoreOrderItem": { "$ref": "#/components/schemas/App.Http.Resources.Customer.OrderItemResource", "title": "QueekStoreOrderItem" }, "QueekStorePage": { "$ref": "#/components/schemas/StorePageResource", "title": "QueekStorePage" }, "QueekStoreProduct": { "$ref": "#/components/schemas/App.Http.Resources.Customer.ProductResource", "title": "QueekStoreProduct" }, "QueekStorePromotion": { "$ref": "#/components/schemas/PromotionResource", "title": "QueekStorePromotion" }, "QueekStoreQuestion": { "$ref": "#/components/schemas/ProductQuestionResource", "title": "QueekStoreQuestion" }, "QueekStoreReview": { "$ref": "#/components/schemas/ProductReviewResource", "title": "QueekStoreReview" }, "QueekStoreReviewsBlockItem": { "$ref": "#/components/schemas/ReviewsBlockItemResource", "title": "QueekStoreReviewsBlockItem" }, "QueekStoreVendor": { "$ref": "#/components/schemas/VendorResource", "title": "QueekStoreVendor" }, "QueekWebhookCustomerEmailMarketingConsentEvent": { "type": "object", "description": "The signed body of a webhook delivery. Signed as `{webhook-id}.{webhook-timestamp}.{raw body}` with HMAC-SHA256 over the base64-decoded secret, value `v1,`; verify before trusting it.", "properties": { "id": { "type": "string", "description": "Event id, identical to the `webhook-id` header. Dedupe on it \u2014 a retry reuses it." }, "topic": { "$ref": "#/components/schemas/QueekWebhookTopic" }, "api_version": { "type": "string", "description": "Payload contract version. Additive within a major." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp of the event.", "format": "date-time" }, "data": { "$ref": "#/components/schemas/QueekWebhookCustomerEmailMarketingConsentPayload" } }, "required": [ "id", "topic", "api_version", "created_at", "data" ], "title": "QueekWebhookCustomerEmailMarketingConsentEvent" }, "QueekWebhookCustomerEmailMarketingConsentPayload": { "type": "object", "properties": { "id": { "type": "integer" }, "email_marketing_consent": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "not_opted_out", "unsubscribed" ] }, "opt_in_level": { "type": [ "string", "null" ], "enum": [ "SINGLE_OPT_IN", "CONFIRMED_OPT_IN", null ] }, "consent_updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "state", "opt_in_level", "consent_updated_at" ] } }, "required": [ "id", "email_marketing_consent" ], "title": "QueekWebhookCustomerEmailMarketingConsentPayload" }, "QueekWebhookCustomerEvent": { "type": "object", "description": "The signed body of a webhook delivery. Signed as `{webhook-id}.{webhook-timestamp}.{raw body}` with HMAC-SHA256 over the base64-decoded secret, value `v1,`; verify before trusting it.", "properties": { "id": { "type": "string", "description": "Event id, identical to the `webhook-id` header. Dedupe on it \u2014 a retry reuses it." }, "topic": { "$ref": "#/components/schemas/QueekWebhookTopic" }, "api_version": { "type": "string", "description": "Payload contract version. Additive within a major." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp of the event.", "format": "date-time" }, "data": { "$ref": "#/components/schemas/QueekWebhookCustomerPayload" } }, "required": [ "id", "topic", "api_version", "created_at", "data" ], "title": "QueekWebhookCustomerEvent" }, "QueekWebhookCustomerPayload": { "$ref": "#/components/schemas/CustomerResource", "title": "QueekWebhookCustomerPayload" }, "QueekWebhookCustomerSmsMarketingConsentEvent": { "type": "object", "description": "The signed body of a webhook delivery. Signed as `{webhook-id}.{webhook-timestamp}.{raw body}` with HMAC-SHA256 over the base64-decoded secret, value `v1,`; verify before trusting it.", "properties": { "id": { "type": "string", "description": "Event id, identical to the `webhook-id` header. Dedupe on it \u2014 a retry reuses it." }, "topic": { "$ref": "#/components/schemas/QueekWebhookTopic" }, "api_version": { "type": "string", "description": "Payload contract version. Additive within a major." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp of the event.", "format": "date-time" }, "data": { "$ref": "#/components/schemas/QueekWebhookCustomerSmsMarketingConsentPayload" } }, "required": [ "id", "topic", "api_version", "created_at", "data" ], "title": "QueekWebhookCustomerSmsMarketingConsentEvent" }, "QueekWebhookCustomerSmsMarketingConsentPayload": { "type": "object", "properties": { "id": { "type": "integer" }, "sms_marketing_consent": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "subscribed", "unsubscribed", "not_subscribed" ] }, "opt_in_level": { "type": [ "string", "null" ], "enum": [ "SINGLE_OPT_IN", "CONFIRMED_OPT_IN", null ] }, "consent_updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "state", "opt_in_level", "consent_updated_at" ] } }, "required": [ "id", "sms_marketing_consent" ], "title": "QueekWebhookCustomerSmsMarketingConsentPayload" }, "QueekWebhookEvent": { "type": "object", "description": "The signed body of a webhook delivery. Signed as `{webhook-id}.{webhook-timestamp}.{raw body}` with HMAC-SHA256 over the base64-decoded secret, value `v1,`; verify before trusting it.", "properties": { "id": { "type": "string", "description": "Event id, identical to the `webhook-id` header. Dedupe on it \u2014 a retry reuses it." }, "topic": { "$ref": "#/components/schemas/QueekWebhookTopic" }, "api_version": { "type": "string", "description": "Payload contract version. Additive within a major." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp of the event.", "format": "date-time" }, "data": { "$ref": "#/components/schemas/OrderResource" } }, "required": [ "id", "topic", "api_version", "created_at", "data" ], "title": "QueekWebhookEvent" }, "QueekWebhookInventoryLevelEvent": { "type": "object", "description": "The signed body of a webhook delivery. Signed as `{webhook-id}.{webhook-timestamp}.{raw body}` with HMAC-SHA256 over the base64-decoded secret, value `v1,`; verify before trusting it.", "properties": { "id": { "type": "string", "description": "Event id, identical to the `webhook-id` header. Dedupe on it \u2014 a retry reuses it." }, "topic": { "$ref": "#/components/schemas/QueekWebhookTopic" }, "api_version": { "type": "string", "description": "Payload contract version. Additive within a major." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp of the event.", "format": "date-time" }, "data": { "$ref": "#/components/schemas/QueekWebhookInventoryLevelPayload" } }, "required": [ "id", "topic", "api_version", "created_at", "data" ], "title": "QueekWebhookInventoryLevelEvent" }, "QueekWebhookInventoryLevelPayload": { "$ref": "#/components/schemas/InventoryLevelResource", "title": "QueekWebhookInventoryLevelPayload" }, "QueekWebhookProductEvent": { "type": "object", "description": "The signed body of a webhook delivery. Signed as `{webhook-id}.{webhook-timestamp}.{raw body}` with HMAC-SHA256 over the base64-decoded secret, value `v1,`; verify before trusting it.", "properties": { "id": { "type": "string", "description": "Event id, identical to the `webhook-id` header. Dedupe on it \u2014 a retry reuses it." }, "topic": { "$ref": "#/components/schemas/QueekWebhookTopic" }, "api_version": { "type": "string", "description": "Payload contract version. Additive within a major." }, "created_at": { "type": "string", "description": "ISO-8601 timestamp of the event.", "format": "date-time" }, "data": { "$ref": "#/components/schemas/QueekWebhookProductPayload" } }, "required": [ "id", "topic", "api_version", "created_at", "data" ], "title": "QueekWebhookProductEvent" }, "QueekWebhookProductPayload": { "$ref": "#/components/schemas/ProductResource", "title": "QueekWebhookProductPayload" }, "QueekWebhookTopic": { "type": "string", "description": "`orders/create` \u2014 An order was placed, on any channel.\n`orders/paid` \u2014 An order moved to paid.\n`orders/updated` \u2014 An order changed \u2014 status, fulfilment stage or any merchant action.\n`orders/fulfilled` \u2014 An order was completed or delivered.\n`orders/cancelled` \u2014 An order was cancelled or rejected.\n`products/create` \u2014 A product was created in the store.\n`products/update` \u2014 A product changed \u2014 visible content, price or availability.\n`products/delete` \u2014 A product was deleted, soft-delete included.\n`customers/create` \u2014 A customer record was created for the store.\n`customers/update` \u2014 A customer profile field changed.\n`customers_email_marketing_consent/update` \u2014 A customer email marketing preference changed.\n`customers_marketing_consent/update` \u2014 A customer's SMS marketing consent changed.\n`inventory_levels/update` \u2014 A product or variant stock level changed, with the reason.\n`locales/create` \u2014 A locale was added to the store.\n`locales/update` \u2014 A locale was published or unpublished on the store.\n`locales/destroy` \u2014 A locale was removed from the store, with its translations.\n`translations/update` \u2014 Translations were registered on one resource, for the locales and keys in the payload.\n`translations/delete` \u2014 Translations were removed from one resource, for the locales and keys in the payload.", "enum": [ "orders/create", "orders/paid", "orders/updated", "orders/fulfilled", "orders/cancelled", "products/create", "products/update", "products/delete", "customers/create", "customers/update", "customers_email_marketing_consent/update", "customers_marketing_consent/update", "inventory_levels/update", "locales/create", "locales/update", "locales/destroy", "translations/update", "translations/delete" ], "title": "QueekWebhookTopic" }, "RegisterTranslationsRequest": { "type": "object", "description": "PUT translations/{type}/{id} \u2014 register a batch of translations against the\ncurrent source digests. The body shape is validated first (at most 100\nitems); then each item's locale, key and digest is checked against the live\nsource text. Failures answer per-item codes (translation_unknown_locale,\ntranslation_unknown_key, translation_digest_stale) and nothing is written\nunless every item passes.", "properties": { "translations": { "type": "array", "items": { "type": "object", "properties": { "locale": { "type": "string", "maxLength": 12 }, "key": { "type": "string", "maxLength": 64 }, "value": { "type": "string", "description": "Largest v1 source field is ProductRequest's description (50000).", "maxLength": 50000 }, "digest": { "type": "string" } }, "required": [ "locale", "key", "value", "digest" ] }, "minItems": 1, "maxItems": 100 } }, "required": [ "translations" ], "title": "RegisterTranslationsRequest" }, "ReorderCollectionProductsRequest": { "type": "object", "properties": { "product_ids": { "type": "array", "items": { "type": "string", "format": "uuid" }, "minItems": 1, "maxItems": 500 } }, "required": [ "product_ids" ], "title": "ReorderCollectionProductsRequest" }, "ReviewsBlockItemResource": { "type": "object", "properties": { "id": { "type": "string" }, "rating": { "type": "integer" }, "title": { "type": "string" }, "description": { "type": "string" }, "media": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "vendor_response": { "type": "string" }, "vendor_response_at": { "type": "string", "format": "date-time" }, "is_verified_purchase": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" }, "edited_at": { "type": "string", "format": "date-time" }, "submitted_at": { "type": "string", "format": "date-time" }, "source": { "type": [ "string", "null" ] }, "author_display_name": { "type": "string" }, "user": { "type": "string" }, "product": { "type": "object", "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "thumbnail": { "type": "string" } }, "required": [ "id", "slug", "title", "thumbnail" ] } }, "required": [ "id", "rating", "title", "description", "media", "vendor_response", "vendor_response_at", "is_verified_purchase", "created_at", "edited_at", "submitted_at", "source", "author_display_name" ], "title": "ReviewsBlockItemResource" }, "SendAppAlertRequest": { "type": "object", "description": "Send an in-app notice to the installing merchant from the calling\ninstallation (POST app/alerts). The installation comes from the calling key\n\u2014 the body carries no target, so one installation can never alert on another\ninstallation's behalf.\n\nTitles and messages are bell content by design: plain text, length-capped\nlike the manifest listing fields, rendered escaped on every surface. The\noptional dedupe_key lets the app collapse repeats of one problem (one\nfailing import batch, one expired credential) inside the TTL.", "properties": { "severity": { "type": "string", "enum": [ "info", "warning", "error" ] }, "title": { "type": "string", "maxLength": 120 }, "message": { "type": "string", "maxLength": 2000 }, "dedupe_key": { "type": [ "string", "null" ], "maxLength": 120 }, "meta": { "type": [ "array", "null" ], "items": { "type": "string", "maxLength": 500 }, "maxItems": 10 } }, "required": [ "severity", "title", "message" ], "title": "SendAppAlertRequest" }, "ShippingZoneResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "zone_type": { "type": "string" }, "countries": { "type": "array", "items": {} }, "state_ids": { "type": "array", "items": {} }, "area_ids": { "type": "array", "items": {} }, "currency": { "type": "string", "description": "Vendor chain, never the silent platform default: loaded relation first,\nthen the cache-backed lookup (zero DB queries on a warm cache)." }, "base_rate": { "type": "string" }, "per_kg_rate": { "type": [ "string", "null" ] }, "min_weight_kg": { "type": [ "string", "null" ] }, "max_weight_kg": { "type": [ "string", "null" ] }, "min_days": { "type": "integer" }, "max_days": { "type": "integer" }, "active": { "type": "boolean" }, "position": { "type": "integer" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "name", "zone_type", "countries", "state_ids", "area_ids", "currency", "base_rate", "per_kg_rate", "min_weight_kg", "max_weight_kg", "min_days", "max_days", "active", "position", "created_at", "updated_at" ], "title": "ShippingZoneResource" }, "StockAdjustmentResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "quantity_before": { "type": "integer" }, "quantity_change": { "type": "integer" }, "quantity_after": { "type": "integer" }, "reason": { "type": "string" }, "reason_code": { "type": [ "string", "null" ] }, "scope": { "type": "string" }, "product": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "uid": { "type": "string" }, "title": { "type": "string" }, "slug": { "type": "string" } }, "required": [ "id", "uid", "title", "slug" ] }, "variant": { "type": [ "object", "null" ], "properties": { "uid": { "type": "string" }, "title": { "type": "string" }, "option_values": { "type": "string" } }, "required": [ "uid", "title", "option_values" ] }, "order": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "uid": { "type": "string" } }, "required": [ "id", "uid" ] }, "shortfall": { "type": "string" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "quantity_before", "quantity_change", "quantity_after", "reason", "reason_code", "scope", "product", "variant", "order", "shortfall", "created_at" ], "title": "StockAdjustmentResource" }, "StoreCouponRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "code": { "type": [ "string", "null" ], "minLength": 4, "maxLength": 20 }, "discount_type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "discount_value": { "type": "number", "minimum": 0 }, "minimum_order_amount": { "type": [ "number", "null" ], "minimum": 0 }, "applies_to": { "type": "string", "enum": [ "all_products", "specific_products", "specific_categories" ] }, "target_product_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "target_category_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "usage_limit": { "type": [ "integer", "null" ], "minimum": 1 }, "usage_limit_per_user": { "type": "integer", "minimum": 1, "maximum": 10 }, "starts_at": { "type": [ "string", "null" ], "format": "date-time" }, "expires_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "title", "discount_type", "discount_value", "applies_to", "usage_limit_per_user" ], "title": "StoreCouponRequest" }, "StoreDiscountRequest": { "type": "object", "properties": { "title": { "type": "string", "maxLength": 255 }, "description": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "number", "minimum": 0 }, "priority": { "type": [ "integer", "null" ], "minimum": 0, "maximum": 1000 }, "stack_mode": { "type": [ "string", "null" ], "enum": [ "exclusive", "best_price", null ] }, "product_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "category_ids": { "type": [ "array", "null" ], "items": { "type": "string" } }, "rules_json": { "type": "object", "properties": { "product_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "taxonomy_category_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "collection_category_ids": { "type": [ "array", "null" ], "items": { "type": "string", "format": "uuid" } }, "attributes": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "name": { "type": "string", "maxLength": 100 }, "operator": { "type": "string", "enum": [ "eq", "equals", "contains", "includes" ] }, "value": { "type": "string" } } } } } }, "action_json": { "type": "object", "properties": { "type": { "type": "string", "enum": [ "percentage", "fixed" ] }, "value": { "type": "number", "minimum": 0 }, "min_final_price": { "type": [ "number", "null" ], "minimum": 0 } } }, "minimum_order_amount": { "type": [ "number", "null" ], "minimum": 0 }, "minimum_quantity": { "type": [ "integer", "null" ], "minimum": 1 }, "capped_amount": { "type": [ "number", "null" ], "minimum": 0 }, "capped_amount_per_user": { "type": [ "number", "null" ], "minimum": 0 }, "max_usage_total": { "type": [ "integer", "null" ], "minimum": 1 }, "max_usage_per_user": { "type": [ "integer", "null" ], "minimum": 1 }, "valid_from": { "type": [ "string", "null" ], "format": "date-time" }, "valid_until": { "type": [ "string", "null" ], "format": "date-time" }, "is_active": { "type": "boolean" }, "is_published": { "type": "boolean" }, "auto_apply": { "type": "boolean" }, "image_url": { "type": [ "string", "null" ], "format": "uri" }, "settings": { "type": [ "array", "null" ], "items": { "type": "string" } } }, "required": [ "title", "type", "value" ], "title": "StoreDiscountRequest" }, "StoreLocaleResource": { "type": "object", "properties": { "locale": { "type": "string" }, "name": { "type": "string" }, "native_name": { "type": "string" }, "is_primary": { "type": "boolean" }, "path_prefix": { "type": "string" }, "hreflang": { "type": "string" }, "html_lang": { "type": "string" }, "dir": { "type": "string" } }, "required": [ "locale", "name", "native_name", "is_primary", "path_prefix", "hreflang", "html_lang", "dir" ], "title": "StoreLocaleResource" }, "StorePageResource": { "type": "object", "properties": { "id": { "type": "string" }, "type": { "type": "string" }, "template": { "type": "string" }, "slug": { "type": "string" }, "title": { "type": "string" }, "content": { "description": "Self-heal on serve: run stored blocks through the canonical\nnormalizer so a legacy/malformed section (e.g. a gallery with a\nnull slide) can never crash the storefront render. Same sanitizer\nthe write path uses, so serving == what a re-save would produce.\nPre-normalized above (attachContentMediaVariants also collects\nmedia_index from this exact array) rather than re-normalized here,\nso content[] and media_index can never disagree with each other.", "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "media_index": { "type": "string" }, "excerpt": { "type": [ "string", "null" ] }, "cover_image_url": { "type": "string" }, "cover_image_variants": { "type": [ "string", "null" ] }, "tags": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "seo": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "blog_categories": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "reading_time": { "type": "integer" }, "author": { "type": [ "object", "null" ], "properties": { "name": { "type": "string" }, "avatar_url": { "type": "string" } }, "required": [ "name", "avatar_url" ] }, "is_home": { "type": "boolean" }, "chrome": { "type": "string" }, "show_page_title": { "type": "boolean" }, "status": { "type": "string" }, "position": { "type": "integer" }, "published_at": { "type": [ "string", "null" ], "format": "date-time" }, "created_at": { "type": [ "string", "null" ], "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "id", "type", "template", "slug", "title", "content", "media_index", "excerpt", "cover_image_url", "cover_image_variants", "tags", "seo", "blog_categories", "reading_time", "is_home", "chrome", "show_page_title", "status", "position", "published_at", "created_at", "updated_at" ], "title": "StorePageResource" }, "StoreProductImageRequest": { "type": "object", "description": "Attach one image: a `media_id` from the store's own files, or a PUBLIC `url`\nthat the server downloads into the store's files (SSRF-guarded, never\nhot-linked). `primary: true` makes it the main image; otherwise it joins the\ngallery.", "properties": { "media_id": { "type": [ "integer", "null" ], "minimum": 1 }, "url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 2048 }, "primary": { "type": "boolean" } }, "title": "StoreProductImageRequest" }, "StoreProductVariantRequest": { "type": "object", "description": "One variant of a shop product. `title` is not accepted: it is derived from the\noption values (\"Large / Red\") by the variant service, as on every other writer.", "properties": { "option_values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3 }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "barcode": { "type": [ "string", "null" ], "maxLength": 100 }, "price": { "type": "number", "minimum": 0 }, "compare_at_price": { "type": [ "number", "null" ], "minimum": 0 }, "stock": { "type": "integer", "minimum": 0 }, "track_inventory": { "type": "boolean" }, "is_active": { "type": "boolean" }, "is_backorder": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ], "format": "date-time", "description": "No `sometimes`: required_if must still fire when the date is omitted." }, "weight": { "type": [ "number", "null" ], "minimum": 0 }, "position": { "type": "integer", "minimum": 0 } }, "required": [ "option_values", "price" ], "title": "StoreProductVariantRequest" }, "StoreResource": { "type": "object", "properties": { "id": { "type": "integer", "description": "The store id. An integer (the vendor `p_id`) \u2014 send this back wherever an id is asked for." }, "uid": { "type": "string", "description": "The store UUID. Opaque \u2014 prefer `id` unless a field asks for the UUID." }, "name": { "type": "string", "description": "The store name, as shoppers see it." }, "slug": { "type": "string", "description": "The URL-safe store handle. Unique across Queek." }, "contact": { "type": "object", "properties": { "email": { "type": "string", "description": "The public support email printed on receipts and store pages." }, "phone": { "type": "string", "description": "The public support phone printed on receipts and store pages." } }, "required": [ "email", "phone" ], "description": "How shoppers reach the store." }, "address": { "type": "object", "properties": { "address": { "type": "string", "description": "The street address shoppers see on the store page." }, "landmark": { "type": "string", "description": "A nearby landmark, when the merchant set one." }, "region": { "type": [ "string", "null" ], "description": "The region name (e.g. Lagos) the store trades in." }, "latitude": { "type": [ "number", "null" ], "description": "Store latitude for maps and delivery estimates." }, "longitude": { "type": [ "number", "null" ], "description": "Store longitude for maps and delivery estimates." } }, "required": [ "address", "landmark", "region", "latitude", "longitude" ], "description": "Where shoppers find the store." }, "logo": { "type": [ "string", "null" ], "description": "Resolved logo URL. Null when the store has no logo." }, "banner": { "type": [ "string", "null" ], "description": "Resolved banner URL. Null when the store has no banner." }, "rating": { "type": "object", "properties": { "value": { "type": "number", "description": "Average shopper rating, 0\u20135." }, "count": { "type": "integer", "description": "How many ratings produced the average." } }, "required": [ "value", "count" ], "description": "What shoppers think of the store." }, "status": { "type": "string", "description": "Storefront status (`active` means trading)." }, "operating_hours": { "type": "object", "properties": { "weekdays": { "type": "object", "properties": { "open_time": { "type": "string", "description": "Weekday opening time (`HH:MM`)." }, "close_time": { "type": "string", "description": "Weekday closing time (`HH:MM`)." }, "status": { "type": "string", "description": "Reserved for the live open/closed status. Not computed yet: it always reads `closed` today, so decide whether the store is open from the opening windows and `temporary_unavailable`." } }, "required": [ "open_time", "close_time", "status" ], "description": "Monday\u2013Friday opening window, plus an open/closed status field." }, "saturday": { "type": "object", "properties": { "open_time": { "type": "string", "description": "Saturday opening time (`HH:MM`), null when closed." }, "close_time": { "type": "string", "description": "Saturday closing time (`HH:MM`), null when closed." } }, "required": [ "open_time", "close_time" ], "description": "Saturday opening window." }, "sunday": { "type": "object", "properties": { "open_time": { "type": "string", "description": "Sunday opening time (`HH:MM`), null when closed." }, "close_time": { "type": "string", "description": "Sunday closing time (`HH:MM`), null when closed." } }, "required": [ "open_time", "close_time" ], "description": "Sunday opening window." }, "preparation_time": { "type": "object", "properties": { "minimum": { "type": "integer", "description": "Minimum preparation time in minutes." }, "maximum": { "type": "integer", "description": "Maximum preparation time in minutes." } }, "required": [ "minimum", "maximum" ], "description": "Kitchen/preparation time in minutes, minimum and maximum." }, "temporary_unavailable": { "type": "boolean", "description": "True while the merchant has paused the storefront." }, "available_on_weekend": { "type": "boolean", "description": "Whether the store trades on weekends at all." } }, "required": [ "weekdays", "saturday", "sunday", "preparation_time", "temporary_unavailable", "available_on_weekend" ], "description": "When the store trades." }, "capabilities": { "type": "object", "properties": { "queek_logistics_enabled": { "type": "boolean", "description": "Whether Queek logistics fulfils this store\u2019s deliveries." }, "delivery_enabled": { "type": "boolean", "description": "Whether the store delivers." }, "offers_free_delivery": { "type": "boolean", "description": "Whether delivery is free at this store." }, "pickup_enabled": { "type": "boolean", "description": "Whether shoppers can pick up." }, "instore_order": { "type": "string", "description": "Whether in-store (QR) ordering is on." } }, "required": [ "queek_logistics_enabled", "delivery_enabled", "offers_free_delivery", "pickup_enabled", "instore_order" ], "description": "What the storefront offers." }, "storefront": { "type": "object", "properties": { "domains": { "type": "string", "description": "Every origin the storefront answers on (`https://host`), the canonical one first: each verified custom domain, then the Queek subdomain." } }, "required": [ "domains" ], "description": "Where the store\u2019s own storefront is served." }, "created_at": { "type": [ "string", "null" ], "description": "When the store was created (ISO-8601).", "format": "date-time" }, "updated_at": { "type": [ "string", "null" ], "description": "When the store was last updated (ISO-8601).", "format": "date-time" } }, "required": [ "id", "uid", "name", "slug", "contact", "address", "logo", "banner", "rating", "status", "operating_hours", "capabilities", "storefront", "created_at", "updated_at" ], "title": "StoreResource" }, "StoreVendorLocaleRequest": { "type": "object", "description": "POST locales {locale} \u2014 enable a catalogue locale on the store. The code\nmust be a supported catalogue code; anything else is a 422, never a guess.", "properties": { "locale": { "type": "string", "enum": [ "en", "fr", "es", "pt", "pt-BR", "de", "it", "nl", "pl", "ru", "uk", "tr", "ar", "ur", "fa", "he", "hi", "ja", "ko", "zh-CN", "zh-TW", "id", "ms", "vi", "th", "tl", "sw", "ha", "yo", "ig", "pcm" ], "maxLength": 12 } }, "required": [ "locale" ], "title": "StoreVendorLocaleRequest" }, "TaxonomyCategoryResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "slug": { "type": "string" }, "image": { "type": "string" }, "image_variants": { "type": [ "string", "null" ], "description": "Pre-sized copies of the image, resolved from its URL (categories\nand collections store no media id)." }, "products_count": { "type": "integer" }, "children": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } }, "required": [ "id", "name", "slug", "image", "image_variants", "products_count", "children" ], "title": "TaxonomyCategoryResource" }, "TeamDirectoryResource": { "type": "object", "properties": { "id": { "type": "integer" }, "name": { "type": [ "string", "null" ] }, "role_names": { "type": "string" }, "is_active": { "type": "boolean" } }, "required": [ "id", "name", "role_names", "is_active" ], "title": "TeamDirectoryResource" }, "UpdateAppSetupNoticeRequest": { "type": "object", "description": "Store the calling installation's merchant-visible setup values (PUT\napp/setup). Call it once the installation's key is active.\n\nFull-body PUT \u2014 send status plus the whole items sheet every time, so a\nretry replays instead of merging. Length limits apply per field; values that\nlook like URLs must be https (a token-bearing http URL would train the\nmerchant to paste secrets into cleartext).", "properties": { "status": { "type": "string", "description": "needs_action is the absence state the backend derives when no\nnotice is stored \u2014 an app may only declare incomplete/complete.", "enum": [ "incomplete", "complete" ] }, "items": { "type": "array", "items": { "type": "object", "properties": { "key": { "type": "string", "maxLength": 80 }, "label": { "type": "string", "maxLength": 120 }, "value": { "type": "string", "maxLength": 2000 }, "sensitive": { "type": "boolean" }, "copyable": { "type": "boolean" }, "instructions": { "type": [ "string", "null" ], "maxLength": 500 } }, "required": [ "key", "label", "value", "sensitive", "copyable" ] }, "minItems": 1, "maxItems": 20 } }, "required": [ "status", "items" ], "title": "UpdateAppSetupNoticeRequest" }, "UpdateCustomerEmailMarketingConsentRequest": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "unsubscribed", "not_opted_out" ] }, "source": { "type": "string", "maxLength": 120 }, "consent_updated_at": { "type": "string", "format": "date-time" }, "opt_in_level": { "type": "string", "enum": [ "SINGLE_OPT_IN", "CONFIRMED_OPT_IN" ] } }, "required": [ "state" ], "title": "UpdateCustomerEmailMarketingConsentRequest" }, "UpdateCustomerSmsMarketingConsentRequest": { "type": "object", "properties": { "state": { "type": "string", "enum": [ "subscribed", "unsubscribed" ] }, "source": { "type": [ "string", "null" ], "enum": [ "checkout", "account", "import", "provider_sync", "other", null ] }, "consent_updated_at": { "type": [ "string", "null" ], "format": "date-time" }, "opt_in_level": { "type": "string", "enum": [ "SINGLE_OPT_IN", "CONFIRMED_OPT_IN" ] } }, "required": [ "state" ], "title": "UpdateCustomerSmsMarketingConsentRequest" }, "UpdateProductImageRequest": { "type": "object", "description": "Make an image already on the product its primary image. To clear the primary\nimage, DELETE it instead.", "properties": { "primary": { "enum": [ "yes", "on", "1", 1, "true", true ] } }, "required": [ "primary" ], "title": "UpdateProductImageRequest" }, "UpdateProductVariantRequest": { "type": "object", "description": "Same fields as a new variant, every one optional: only what is sent changes.", "properties": { "option_values": { "type": "array", "items": { "type": "string" }, "minItems": 1, "maxItems": 3 }, "sku": { "type": [ "string", "null" ], "maxLength": 100 }, "barcode": { "type": [ "string", "null" ], "maxLength": 100 }, "price": { "type": "number", "minimum": 0 }, "compare_at_price": { "type": [ "number", "null" ], "minimum": 0 }, "stock": { "type": "integer", "minimum": 0 }, "track_inventory": { "type": "boolean" }, "is_active": { "type": "boolean" }, "is_backorder": { "type": "boolean" }, "backorder_ready_date": { "type": [ "string", "null" ], "format": "date-time", "description": "No `sometimes`: required_if must still fire when the date is omitted." }, "weight": { "type": [ "number", "null" ], "minimum": 0 }, "position": { "type": "integer", "minimum": 0 } }, "title": "UpdateProductVariantRequest" }, "UpdateShipmentRequest": { "type": "object", "properties": { "carrier_name": { "type": [ "string", "null" ], "maxLength": 100 }, "tracking_number": { "type": [ "string", "null" ], "maxLength": 200 }, "tracking_url": { "type": [ "string", "null" ], "format": "uri", "maxLength": 500 }, "status": { "type": [ "string", "null" ], "description": "Lifecycle advance targets the order (single status truth). Optional:\na vendor may edit tracking without moving the order forward.", "enum": [ "on_transit", "delivered", null ] }, "shipped_at": { "type": [ "string", "null" ], "format": "date-time" }, "estimated_delivery_at": { "type": [ "string", "null" ], "format": "date-time" }, "delivered_at": { "type": [ "string", "null" ], "format": "date-time" }, "notes": { "type": [ "string", "null" ], "maxLength": 1000 } }, "title": "UpdateShipmentRequest" }, "UpdateVendorLocaleRequest": { "type": "object", "description": "PATCH locales/{locale} \u2014 publish or unpublish an enabled locale by sending\n`published`. An unknown code, or a code the store never added, answers 404.", "properties": { "published": { "type": "boolean" } }, "required": [ "published" ], "title": "UpdateVendorLocaleRequest" }, "UpdateVendorOrderStatusRequest": { "type": "object", "properties": { "status": { "type": "string", "enum": [ "approve_payment", "accept", "rejected", "mark_received", "ready_for_pickup", "picked_up", "ready_to_serve", "served", "complete" ] }, "reason": { "type": [ "string", "null" ] }, "earliest_delivery_time": { "type": [ "string", "null" ], "format": "date-time" }, "latest_delivery_time": { "type": [ "string", "null" ], "format": "date-time" } }, "required": [ "status" ], "title": "UpdateVendorOrderStatusRequest" }, "UserItemResource": { "type": "object", "properties": { "id": { "type": "string" }, "username": { "type": "string" }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "phone": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "phone_code": { "type": [ "string", "null" ] }, "avatar": { "type": "string" }, "map_lat": { "type": "number" }, "map_lng": { "type": "number" }, "address": { "type": [ "string", "null" ] }, "status": { "type": "string" }, "roles": { "type": "string" }, "transactions_count": { "type": "string" }, "orders_count": { "type": "string" }, "assigned_orders_count": { "type": "string" }, "completed_orders_count": { "type": "string" }, "date_joined": { "type": "string" }, "last_seen": { "type": [ "string", "null" ] }, "wallet": { "$ref": "#/components/schemas/WalletResource" } }, "required": [ "id", "username", "first_name", "last_name", "name", "email", "phone", "country_code", "phone_code", "avatar", "map_lat", "map_lng", "address", "status", "date_joined", "last_seen" ], "title": "UserItemResource" }, "VendorItemResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "distance": { "type": "string" }, "delivery_info": { "type": "object", "properties": { "is_free_delivery": { "type": "boolean" }, "delivery_fee": { "type": [ "number", "null" ] }, "delivery_fee_value": { "type": [ "number", "null" ] }, "min_order": { "type": "number" }, "min_order_fee": { "type": "number" }, "d_p_value": { "type": "number", "const": 1.5 }, "s_p_value": { "type": "number", "description": "delivery_fee_percentage_value", "const": 1.5 }, "delivery_time": { "type": "string", "description": "service_fee_percentage_value" }, "delivery_message": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "We dont have any available rider close to your location at the moment, please check back later", "Hours not set" ] } ] }, "offers_free_delivery": { "type": "string" }, "pickup_enabled": { "type": "string" }, "offer_instant_delivery": { "type": "boolean" }, "disable_delivery_msg": { "type": "string", "const": "We dont have any available rider close to your location at the moment, please check back later" } }, "required": [ "is_free_delivery", "delivery_fee", "delivery_fee_value", "min_order", "min_order_fee", "d_p_value", "s_p_value", "delivery_time", "delivery_message", "offers_free_delivery", "pickup_enabled", "offer_instant_delivery" ] }, "notice": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "slug": { "type": "string" }, "service": { "type": "string" }, "currency": { "type": "string", "description": "The store's own currency (3-letter code, never a symbol \u2014 Q2):\ncart/vendor payloads read this per-vendor instead of the\nplatform default. Attribute-only, zero new queries." }, "logo": { "type": [ "string", "null" ] }, "disable_order": { "type": "boolean" }, "is_closed": { "type": "boolean" }, "temporary_unavailable": { "type": "string" }, "preorder_enabled": { "type": "string" }, "area": { "type": "string" }, "banner": { "type": [ "string", "null" ] }, "support_phone": { "type": "string" }, "phone": { "type": "string" }, "country_code": { "type": "string" }, "phone_code": { "type": "string" }, "support_email": { "type": "string" }, "slogan": { "type": "string" }, "tags": { "type": "string" }, "tag": { "type": "string", "description": "The store's own service tag (fashion, food, ...), like the\nstorefront info surface answers \u2014 never a hardcoded trade." }, "is_new": { "type": "string" }, "rating": { "type": "number" }, "rating_count": { "type": "integer" }, "short_description": { "type": "string" }, "address": { "type": "string" }, "open_time": { "type": [ "string", "null" ] }, "close_time": { "type": [ "string", "null" ] }, "service_type": { "type": "string" }, "landmark": { "type": "string" }, "region_id": { "type": "string" }, "min_order_price": { "type": [ "number", "null" ] } }, "required": [ "id", "name", "distance", "delivery_info", "notice", "slug", "service", "currency", "logo", "disable_order", "is_closed", "temporary_unavailable", "preorder_enabled", "area", "banner", "support_phone", "phone", "country_code", "phone_code", "support_email", "slogan", "tags", "tag", "is_new", "rating", "rating_count", "short_description", "address", "open_time", "close_time", "service_type", "landmark", "region_id", "min_order_price" ], "title": "VendorItemResource" }, "VendorOrderExtensionRequest": { "type": "object", "description": "PATCH orders/{order} \u2014 the developer-extension fields of an order, and\nnothing else.\n\nAn order's state is NOT editable here: status, cancellation, rider\nassignment and shipment each have their own endpoint with their own side\neffects (stock, settlement, notifications, webhooks). Any field outside the\nallowed set is rejected by name with a 422 rather than ignored \u2014 an\nintegrator who tries to cancel an order by PATCHing `status` learns it from\nthe error, not from an order that shipped anyway.\n\n`metafields` must reference an existing definition for orders and never use\nan app-owned (`app.*`, `queek.*`) namespace on this endpoint. `metadata` is\nfree-form integrator bookkeeping \u2014 replaced wholesale (`null` clears it),\ncapped in size and count, with no namespace rule and no definitions.\n`line_items` merges per-line properties by key: an app mirrors what it\nbooked or issued onto the line it belongs to. Property keys from an app\ninstallation key must live under its own `app.{slug}.` namespace; any other\ncaller writes any checkout-shaped key EXCEPT the app-owned `app.*` /\n`queek.*` ones, so no merchant can forge or clear an app's keys. Keys and\nvalues obey the documented caps.", "properties": { "metafields": { "type": [ "array", "null" ], "items": { "type": "object", "properties": { "namespace": { "type": "string", "maxLength": 64 }, "key": { "type": "string", "maxLength": 64 }, "value": { "type": [ "string", "null" ] } } }, "maxItems": 50 }, "metadata": { "type": [ "array", "null" ], "description": "Free-form integrator bookkeeping: opaque strings in, the same\nstrings out. Never interpreted, never rendered \u2014 so the only rules\nit can carry are size and count.", "items": { "type": [ "string", "null" ], "maxLength": 500 }, "maxItems": 50 }, "line_items": { "type": "array", "description": "Per-line properties to merge: a string sets the key, null\ndeletes it, keys you leave out keep their value.", "items": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid", "description": "The line item `id` exactly as the order object's `line_items[].id` carries it." }, "properties": { "type": "array", "description": "Key \u2192 value map merged into the line's `properties`. Keys are\n`namespace.key` (lowercase, at most 64 characters); a line holds\nat most 20 keys and the whole order 200, counted after the merge.", "items": { "type": [ "string", "null" ], "maxLength": 500 }, "maxItems": 20 } }, "required": [ "id", "properties" ] }, "minItems": 1, "uniqueItems": true } }, "title": "VendorOrderExtensionRequest" }, "VendorProfileResource": { "type": "object", "properties": { "id": { "type": "string" }, "p_id": { "type": "integer" }, "name": { "type": "string" }, "brand_id": { "type": "string" }, "status": { "type": "string" }, "approved": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "banner": { "type": [ "string", "null" ] }, "logo_media_id": { "type": [ "integer", "null" ] }, "banner_media_id": { "type": [ "integer", "null" ] }, "logo_media": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "mime_type": { "type": "string" }, "aggregate_type": { "type": "string" }, "size": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] } }, "required": [ "id", "url", "thumbnail_url", "mime_type", "aggregate_type", "size", "width", "height", "duration_seconds" ] }, "banner_media": { "type": [ "object", "null" ], "properties": { "id": { "type": "integer" }, "url": { "type": "string" }, "thumbnail_url": { "type": "string" }, "mime_type": { "type": "string" }, "aggregate_type": { "type": "string" }, "size": { "type": [ "integer", "null" ] }, "width": { "type": [ "integer", "null" ] }, "height": { "type": [ "integer", "null" ] }, "duration_seconds": { "type": [ "integer", "null" ] } }, "required": [ "id", "url", "thumbnail_url", "mime_type", "aggregate_type", "size", "width", "height", "duration_seconds" ] }, "rating": { "type": "object", "properties": { "value": { "type": "number" }, "count": { "type": "integer" } }, "required": [ "value", "count" ] }, "commission": { "type": "number" }, "store_details": { "type": "object", "properties": { "support_phone": { "type": "string" }, "support_email": { "type": "string" }, "address": { "type": "string" }, "landmark": { "type": "string" }, "map_coordinates": { "type": "object", "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } }, "required": [ "lat", "lng" ] }, "region": { "type": [ "string", "null" ] }, "minimum_order_price": { "type": "number" }, "service_type": { "type": "string" } }, "required": [ "support_phone", "support_email", "address", "landmark", "map_coordinates", "region", "minimum_order_price", "service_type" ] }, "operating_hours": { "type": "object", "properties": { "weekdays": { "type": "object", "properties": { "open_time": { "type": "string" }, "close_time": { "type": "string" }, "status": { "type": "string" } }, "required": [ "open_time", "close_time", "status" ] }, "saturday": { "type": "object", "properties": { "open_time": { "type": "string" }, "close_time": { "type": "string" } }, "required": [ "open_time", "close_time" ] }, "sunday": { "type": "object", "properties": { "open_time": { "type": "string" }, "close_time": { "type": "string" } }, "required": [ "open_time", "close_time" ] }, "preparation_time": { "type": "object", "properties": { "minimum": { "type": "integer" }, "maximum": { "type": "integer" } }, "required": [ "minimum", "maximum" ] }, "temporary_unavailable": { "type": "boolean" }, "available_on_weekend": { "type": "boolean" } }, "required": [ "weekdays", "saturday", "sunday", "preparation_time", "temporary_unavailable", "available_on_weekend" ] }, "services_capabilities": { "type": "object", "properties": { "queek_logistics_enabled": { "type": "boolean" }, "delivery_enabled": { "type": "boolean" }, "offers_free_delivery": { "type": "boolean" }, "pickup_enabled": { "type": "boolean" }, "instore_order": { "type": "string" }, "risk_level": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Not assessed" ] } ] } }, "required": [ "queek_logistics_enabled", "delivery_enabled", "offers_free_delivery", "pickup_enabled", "instore_order", "risk_level" ] }, "commission_charges": { "type": "object", "properties": { "settlement_schedule": { "type": "string" }, "instore_price": { "type": "string" }, "commission": { "type": "string" }, "instore_order": { "type": "string" }, "instore_order_commission": { "type": "integer" }, "service_charge": { "type": "object", "properties": { "percent": { "type": "number" }, "cap": { "type": "number" } }, "required": [ "percent", "cap" ] }, "risk_level": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "Not assessed" ] } ] } }, "required": [ "settlement_schedule", "instore_price", "commission", "instore_order", "instore_order_commission", "service_charge", "risk_level" ] }, "management": { "type": "object", "description": "Team contacts on a store-profile read: a store-key caller receives\nnames only \u2014 contact details and roles are never included,\nwhatever scopes the key holds.", "properties": { "owner": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "string" } ] }, "manager": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "string" }, { "type": "string", "enum": [ "Not assigned" ] } ] }, "onboarded_by": { "anyOf": [ { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" } }, "required": [ "id", "name" ] }, { "type": "string" }, { "type": "null" } ] } }, "required": [ "owner", "manager", "onboarded_by" ] }, "bank_account": { "anyOf": [ { "$ref": "#/components/schemas/BankResource" }, { "type": "null" } ] }, "wallet": { "type": "object", "properties": { "balance": { "type": [ "string", "null" ] }, "balance_val": { "type": [ "number", "null" ] }, "total_withdrawal": { "type": [ "string", "null" ] } }, "required": [ "balance", "balance_val", "total_withdrawal" ] }, "qr_codes": { "type": "array", "prefixItems": [ { "type": "object", "properties": { "name": { "type": "string", "const": "in_store_qrcode" }, "url": { "type": [ "string", "null" ] }, "qrcode": { "type": "string" } }, "required": [ "name", "url", "qrcode" ] } ], "minItems": 1, "maxItems": 1 }, "agreement_status": { "type": "string" }, "kyc_tier": { "type": "integer" }, "featured": { "type": "boolean" }, "shop_for_me": { "type": "boolean" }, "is_busy": { "type": "boolean" } }, "required": [ "id", "p_id", "name", "brand_id", "status", "approved", "logo", "banner", "logo_media_id", "banner_media_id", "rating", "commission", "store_details", "operating_hours", "services_capabilities", "commission_charges", "management", "bank_account", "wallet", "qr_codes", "agreement_status", "kyc_tier", "featured", "shop_for_me", "is_busy" ], "title": "VendorProfileResource" }, "VendorResource": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "distance": { "type": "number" }, "distance_text": { "type": "string" }, "delivery_info": { "type": "object", "properties": { "delivery_fee": { "type": [ "number", "null" ] }, "delivery_time": { "type": "string" }, "pickup_enabled": { "type": "boolean" }, "disable_delivery_msg": { "type": "string", "const": "We dont have any available rider close to your location at the moment, please check back later" }, "delivery_message": { "type": "string" }, "disable_delivery": { "type": "boolean" } }, "required": [ "delivery_fee", "delivery_time", "pickup_enabled", "delivery_message", "disable_delivery" ] }, "is_open": { "type": "boolean" }, "message": { "type": "string" }, "temporary_unavailable": { "type": "boolean" }, "preorder_enabled": { "type": "boolean" }, "tags": { "type": "string" }, "tag": { "type": "string" }, "is_new": { "type": [ "string", "boolean" ] }, "featured": { "type": "boolean" }, "service_type": { "type": "string" }, "commerce_mode": { "anyOf": [ { "type": "string" }, { "type": "string", "enum": [ "quick" ] } ] }, "notice": { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 }, "slug": { "type": "string" }, "service": { "type": "string" }, "logo": { "type": [ "string", "null" ] }, "banner": { "type": [ "string", "null" ] }, "logo_variants": { "type": [ "string", "null" ] }, "banner_variants": { "type": [ "string", "null" ] }, "rating": { "type": "number" }, "rating_count": { "type": "integer" }, "discounts": { "anyOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" }, "minItems": 0, "maxItems": 0 } ] }, "open_time": { "type": [ "string", "null" ] }, "close_time": { "type": [ "string", "null" ] }, "address": { "type": [ "string", "null" ], "description": "Always present: both discovery selects load these columns, and the storefront /\nagent merchant cards render them. Safe under non-strict missing-attribute access." }, "area": { "type": [ "string", "null" ] }, "landmark": { "type": [ "string", "null" ] }, "support_phone": { "type": [ "string", "null" ] }, "country_code": { "type": [ "string", "null" ] }, "phone_code": { "type": [ "string", "null" ] }, "support_email": { "type": [ "string", "null" ] }, "slogan": { "type": [ "string", "null" ] }, "short_description": { "type": [ "string", "null" ] }, "disable_order": { "type": "boolean" }, "region_id": { "type": [ "string", "null" ] }, "min_order_price": { "type": [ "number", "null" ] }, "is_test": { "type": "boolean", "description": "A sandbox store is publicly reachable at `{slug}-test`; the storefront\nkeeps it out of crawlers and AI discovery (robots, sitemap, agents.md)." }, "dev_store": { "type": "boolean", "description": "S-E: the core storefront renders a password page for dev\nstores. One flag per fact: dev_store says WHAT it is,\npassword_required gates the token; this response itself\nstays public \u2014 gated reads 401. indexable:false tells the\nstorefront to noindex + drop it from sitemap/feed/agents." }, "password_required": { "type": "boolean" }, "indexable": { "type": "boolean" }, "is_closed": { "type": "boolean" }, "currency": { "type": "string" }, "storefront_url": { "type": [ "string", "null" ] }, "checkout_url": { "type": [ "string", "null" ] }, "contact": { "type": "object", "properties": { "phone": { "type": [ "string", "null" ] }, "email": { "type": [ "string", "null" ] }, "whatsapp": { "type": [ "string", "null" ] } }, "required": [ "phone", "email", "whatsapp" ] }, "brand": { "type": "object", "properties": { "logo": { "type": [ "string", "null" ] }, "colors": { "type": "string" }, "font": { "type": "string" }, "socials": { "type": "array", "items": {} } }, "required": [ "logo", "colors", "font", "socials" ] } }, "required": [ "id", "name", "distance", "distance_text", "delivery_info", "is_open", "message", "temporary_unavailable", "preorder_enabled", "tags", "tag", "is_new", "featured", "service_type", "commerce_mode", "notice", "slug", "service", "logo", "banner", "logo_variants", "banner_variants", "rating", "rating_count", "discounts", "open_time", "close_time", "address", "area", "is_closed", "currency" ], "title": "VendorResource" }, "WalletResource": { "type": "object", "properties": { "balance": { "type": [ "number", "null" ] }, "balance_value": { "type": "string" }, "name": { "type": [ "string", "null" ] }, "account_number": { "type": [ "string", "null" ] }, "account_name": { "type": [ "string", "null" ] }, "account_provider": { "type": [ "string", "null" ] } }, "required": [ "balance", "balance_value", "name", "account_number", "account_name", "account_provider" ], "title": "WalletResource" }, "QueekLegacyErrorKeys": { "type": "object", "description": "Additive legacy-compatibility top-level keys the runtime still emits on error bodies \u2014 never a replacement for `error.*`, which is the contract. `error_code` and `message` ride top-level on helper-produced refusals; `request_id` and `doc_url` ride top-level ONLY on non-reissued controller-helper bodies (storefront, client, developer and dashboard surfaces) \u2014 merchant routes reissue refusals, so there they live inside `error` and the `X-Request-Id` header. Handler-produced bodies keep their own top-level keys with `error` stapled beside them. Not referenced by any operation response: new integrations switch on `error.code`.", "properties": { "error_code": { "type": "string", "description": "Top-level mirror of `error.code` on helper-produced refusals (shared controller error helpers, client-auth handler branches)." }, "message": { "type": "string", "description": "Top-level mirror of `error.message` on the same helper-produced refusals as `error_code`." }, "request_id": { "type": "string", "description": "Top-level mirror of `error.request_id` ONLY on non-reissued controller-helper bodies. Always a string when present." }, "doc_url": { "type": "string", "description": "Top-level mirror of `error.doc_url`, same per-producer scope as top-level `request_id`: non-reissued controller-helper bodies only." } } }, "MerchantMetaobject": { "type": "object", "description": "One vendor metaobject entry with timestamps. `fields` carries the values keyed by field key.", "required": [ "p_id", "type", "handle", "display_name", "status", "fields", "created_at", "updated_at" ], "properties": { "p_id": { "type": "integer" }, "type": { "type": "string" }, "handle": { "type": "string" }, "display_name": { "type": "string" }, "status": { "type": "string" }, "fields": { "type": "object", "description": "Entry values keyed by field key.", "additionalProperties": true }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } }, "MerchantPayoutBatch": { "type": "object", "description": "One released daily seller settlement batch. Only order settlement credits are included.", "required": [ "id", "settlement_date", "total_amount", "currency", "order_count", "first_posted_at", "last_posted_at" ], "properties": { "id": { "type": "string", "description": "The batch id \u2014 its YYYY-MM-DD settlement date." }, "settlement_date": { "type": "string", "format": "date", "description": "The settled day (YYYY-MM-DD)." }, "total_amount": { "type": "string", "description": "Major-unit decimal string in `currency`." }, "currency": { "type": "string", "description": "ISO currency code." }, "order_count": { "type": "integer", "description": "Settled orders in the batch." }, "first_posted_at": { "type": "string", "format": "date-time" }, "last_posted_at": { "type": "string", "format": "date-time" } } } }, "responses": { "AuthenticationException": { "description": "Unauthenticated", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ValidationException": { "description": "Validation error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Errors overview." }, "errors": { "type": "object", "description": "A detailed description of each field that failed validation.", "additionalProperties": { "type": "array", "items": { "type": "string" } } } }, "required": [ "message", "errors" ] } } } }, "AuthorizationException": { "description": "Authorization error", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } }, "ModelNotFoundException": { "description": "Not found", "content": { "application/json": { "schema": { "type": "object", "properties": { "message": { "type": "string", "description": "Error overview." } }, "required": [ "message" ] } } } } } }, "webhooks": { "orders/create": { "post": { "summary": "orders/create", "description": "An order was placed, on any channel.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.orders.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "orders/paid": { "post": { "summary": "orders/paid", "description": "An order moved to paid.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.orders.paid", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "orders/updated": { "post": { "summary": "orders/updated", "description": "An order changed \u2014 status, fulfilment stage or any merchant action.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.orders.updated", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "orders/fulfilled": { "post": { "summary": "orders/fulfilled", "description": "An order was completed or delivered.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.orders.fulfilled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "orders/cancelled": { "post": { "summary": "orders/cancelled", "description": "An order was cancelled or rejected.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.orders.cancelled", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "products/create": { "post": { "summary": "products/create", "description": "A product was created in the store.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.products.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookProductEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "products/update": { "post": { "summary": "products/update", "description": "A product changed \u2014 visible content, price or availability.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.products.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookProductEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "products/delete": { "post": { "summary": "products/delete", "description": "A product was deleted, soft-delete included.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.products.delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookProductEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "customers/create": { "post": { "summary": "customers/create", "description": "A customer record was created for the store.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.customers.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookCustomerEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "customers/update": { "post": { "summary": "customers/update", "description": "A customer profile field changed.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.customers.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookCustomerEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "customers_email_marketing_consent/update": { "post": { "summary": "customers_email_marketing_consent/update", "description": "A customer email marketing preference changed.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.customers_email_marketing_consent.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookCustomerEmailMarketingConsentEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "customers_marketing_consent/update": { "post": { "summary": "customers_marketing_consent/update", "description": "A customer's SMS marketing consent changed.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.customers_marketing_consent.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookCustomerSmsMarketingConsentEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "inventory_levels/update": { "post": { "summary": "inventory_levels/update", "description": "A product or variant stock level changed, with the reason.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.inventory_levels.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookInventoryLevelEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "locales/create": { "post": { "summary": "locales/create", "description": "A locale was added to the store.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.locales.create", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "locales/update": { "post": { "summary": "locales/update", "description": "A locale was published or unpublished on the store.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.locales.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "locales/destroy": { "post": { "summary": "locales/destroy", "description": "A locale was removed from the store, with its translations.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.locales.destroy", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "translations/update": { "post": { "summary": "translations/update", "description": "Translations were registered on one resource, for the locales and keys in the payload.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.translations.update", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } }, "translations/delete": { "post": { "summary": "translations/delete", "description": "Translations were removed from one resource, for the locales and keys in the payload.\n\nDelivered to every active endpoint of the store subscribed to this topic. Endpoint subscriptions live outside this API (dashboard); verify the signature, dedupe on the event `id`, acknowledge with a 2xx inside 5s, and do the work asynchronously.", "operationId": "webhook.translations.delete", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/QueekWebhookEvent" } } } }, "responses": { "200": { "description": "Acknowledged. Any other status (or a timeout) is retried on the published backoff schedule." } } } } }, "x-queek-error-codes": { "codes": [ "ai_unavailable_in_test_mode", "api_key_expired", "api_key_mode_mismatch", "api_key_revoked", "app_embed_not_ready", "app_grant_insufficient", "app_handoff_failed", "app_installation_gone", "app_installation_pending", "app_ip_not_allowed", "app_proxy_failed", "app_proxy_gone", "app_token_revoked", "bad_request", "channel_gateway_unreachable", "client_key_required", "conflict", "custom_domain_provisioning_failed", "custom_gateway_forbidden", "custom_gateway_kyc_required", "custom_gateway_not_configured", "custom_gateway_not_verified", "custom_gateway_plan_required", "custom_gateway_store_ineligible", "custom_gateway_verification_failed", "forbidden", "gone", "idempotency_key_in_progress", "idempotency_key_reuse", "insufficient_scope", "invalid_client", "invalid_client_key", "metafield_definition_missing", "metafield_filter_unsupported_type", "metafield_namespace_reserved", "metafield_value_invalid", "metaobject_definition_missing", "metaobject_field_invalid", "metaobject_reference_invalid", "metaobject_type_reserved", "method_not_allowed", "not_found", "origin_not_allowed", "origin_required", "payload_too_large", "payment_amount_mismatch", "plan_inactive", "private_key_required", "requires_slot", "resync_cooldown", "route_not_available", "server_error", "service_unavailable", "subscription_feature_locked", "too_many_requests", "translation_digest_stale", "translation_locale_is_primary", "translation_max_published_locales", "translation_unknown_key", "translation_unknown_locale", "unauthenticated", "unknown_product_ref", "unknown_service", "unknown_variant_ref", "unsupported_media_type", "validation_failed", "vendor_access_denied", "vendor_mail_sender_forbidden", "vendor_mail_sender_not_configured", "vendor_mail_sender_plan_required", "vendor_mail_sender_verification_failed" ], "status_defaults": { "400": "bad_request", "401": "unauthenticated", "403": "forbidden", "404": "not_found", "405": "method_not_allowed", "409": "conflict", "410": "gone", "413": "payload_too_large", "415": "unsupported_media_type", "422": "validation_failed", "429": "too_many_requests", "500": "server_error", "503": "service_unavailable" }, "doc_url": "https://docs.usequeek.com/docs/versioning-and-errors" }, "x-queek-request-id": { "header": "X-Request-Id", "version_header": "X-Queek-Api-Version", "api_version": "v1", "min_length": 8, "max_length": 128, "pattern": "^[A-Za-z0-9_.:-]+$" }, "x-queek-idempotency": { "header": "Idempotency-Key", "replay_header": "Idempotent-Replayed", "ttl_hours": 24, "lock_seconds": 30, "wait_seconds": 15, "reuse_error_code": "idempotency_key_reuse", "in_progress_error_code": "idempotency_key_in_progress", "conflict_status": 409, "scope": "vendor + caller + METHOD:path + key. The body is the fingerprint, not part of the slot.", "stores_failures": false }, "x-queek-rate-limits": { "shared_bucket": { "per_minute": 180, "scope": "API key + IP, or storefront origin + IP when no key is sent." }, "private_key_quota": { "applies_to": "sk_live_ private keys only. A pk_live_ public key is shared by every visitor of the store, so it gets no per-store bucket.", "entitlement": "api_requests_per_minute", "default_per_minute": 120, "per_minute_by_plan": { "free": 60, "social_media": 120, "starter": 120, "growth": 240, "scale": 1200, "enterprise": 2400 } }, "error_code": "too_many_requests", "response_headers": [ "X-RateLimit-Limit", "X-RateLimit-Remaining", "Retry-After" ] }, "x-queek-metafields": { "types": [ "single_line_text", "multi_line_text", "integer", "decimal", "boolean", "date", "url", "json", "media_id", "metaobject_reference", "list.single_line_text", "list.multi_line_text", "list.integer", "list.decimal", "list.boolean", "list.date", "list.url", "list.media_id", "list.metaobject_reference" ], "list_prefix": "list.", "owner_types": [ "product", "order" ], "reserved_namespaces": [ "queek" ], "limits": { "max_definitions_per_vendor": 200, "max_metafields_per_resource": 50, "max_value_bytes": 65536, "max_metadata_keys": 50, "max_metadata_key_length": 64, "max_metadata_value_length": 500 } }, "x-queek-webhooks": { "signing": { "scheme": "Standard Webhooks", "headers": [ "webhook-id", "webhook-timestamp", "webhook-signature" ], "secret_prefix": "whsec_", "signed_content": "{webhook-id}.{webhook-timestamp}.{raw body}", "algorithm": "HMAC-SHA256 over the base64-decoded secret, value `v1,`", "tolerance_seconds": 300, "secret_grace_hours": 24 }, "delivery": { "attempts": 8, "backoff_seconds": [ 5, 30, 120, 600, 1800, 3600, 7200 ], "timeout_seconds": 5, "connect_timeout_seconds": 3, "success": "any 2xx inside the timeout", "auto_disable_after_hours": 24, "retention_days": 7, "max_endpoints_per_vendor": 10 }, "topics": { "orders/create": "An order was placed, on any channel.", "orders/paid": "An order moved to paid.", "orders/updated": "An order changed \u2014 status, fulfilment stage or any merchant action.", "orders/fulfilled": "An order was completed or delivered.", "orders/cancelled": "An order was cancelled or rejected.", "products/create": "A product was created in the store.", "products/update": "A product changed \u2014 visible content, price or availability.", "products/delete": "A product was deleted, soft-delete included.", "customers/create": "A customer record was created for the store.", "customers/update": "A customer profile field changed.", "customers_email_marketing_consent/update": "A customer email marketing preference changed.", "customers_marketing_consent/update": "A customer's SMS marketing consent changed.", "inventory_levels/update": "A product or variant stock level changed, with the reason.", "locales/create": "A locale was added to the store.", "locales/update": "A locale was published or unpublished on the store.", "locales/destroy": "A locale was removed from the store, with its translations.", "translations/update": "Translations were registered on one resource, for the locales and keys in the payload.", "translations/delete": "Translations were removed from one resource, for the locales and keys in the payload." } } }