Queek docs

Changelog

Every change to the Headless API (formerly the Storefront API) and the Merchant API, newest first.

Both APIs are additive inside v1: new endpoints, fields and enum values arrive without notice, and nothing is removed, renamed or retyped (see Versioning & errors). Entries below record what was added and any behaviour that was corrected. Newest first.

2026-10-20 — Custom fields on every record type

  • Metafields now exist on six record types: products, orders and customers, plus variants, collections and blog posts (type post only). owner_type accepts product, order, customer, collection, post and variant. See Custom fields.
  • Two access switches per definition. storefront_visible decides what the public API returns; it defaults on for products and off for variants, collections and posts. customer_visible (customer and order definitions only, default off) lets the signed-in customer read the value on their own GET /auth/me and GET /store/orders*, read-only.
  • Public reads carry metafields on each variant of a product, on collections and on blog posts, only for fields the merchant switched on. GET /store/metafield-definitions takes owner_type (product default, variant, collection, post).
  • Merchant API: variants[].metafields on POST/PUT /products and on the single-variant routes; metafields on POST /posts and PUT /posts/{post}; customers' metafields on the customer reads. New: GET /collections/{collection} (scope merchant-collections-detail) and PUT /collections/{collection} (scope merchant-collections-update), which writes metafields. POST /collections/bulk refuses metafields.
  • Webhooks: products/* carry every variant's values; customers/create and customers/update carry the customer's metafields. A change to a value alone announces its record. Collections and posts have no topics.
  • A variant's values are deleted with the variant. Send each variant's id back on a product save, or its values are lost.

2026-10-20 — Headless API

  • The Storefront API is now the Headless API. The host (client.usequeek.com), the base path, the X-Client-Key header and every endpoint are unchanged. A merchant manages it at Channels → Headless API: Connect a site or app, pick Website, Mobile app, Server or backend, AI agent or Testing on my computer, and Copy for AI.
  • A connection owns its keys. Replace key keeps the old key working until it is turned off; Turn off stops one; Disconnect stops them all. A secret key exists only for a server connection and is shown once. See Manage a connection.
  • Allowed websites are exact https:// addresses. * is not accepted on new connections. Existing public keys became a Default connection and keep their list.
  • checkout_url carries the return link. When the connection lists after-checkout return links, checkout_url ends with &return_url=…, and the customer lands there with ?queek_order= after paying. Orders from a connection's carts count toward its Orders and revenue.
  • An AI agent key can browse products and build carts only. Anything else answers 403 agent_access_denied.
  • Plainer failures. invalid_client_key, origin_required, origin_not_allowed, plan_inactive and api_key_mode_mismatch now carry plain-English messages, and the connection's Problems card lists them with a one-click fix. See Rules for AI builders.

2026-10-20 — Merchant API: machine translation

  • New POST /translations/machine/quote and POST /translations/machine. An app asks for a quote for a job, then runs the confirmed quote. The body names the store's own content by reference (locale, mode and resources of type, id and optional keys), never text: Queek reads the store's text, translates it and saves each clean result as a translation. A text that fails a check is returned as held with a reason and nothing is written for it. The run needs an Idempotency-Key. See Machine translation.
  • New scope merchant-translations-machine. It is shown to the merchant at install, and an app that adds it to a version is reviewed as shopper-facing content. The merchant can switch machine translation off for each app; while it is off both calls answer 403 machine_translation_off.
  • Credits. The quote shows the credits and a run is never charged more than its quote. The store sees each run in its usage history as "Machine translation" and gets a notice for a large run. A job is limited to 20 resources, 20 keys per resource and 200,000 characters; a store to 1,000,000 characters a day; an app to 30 requests a minute.
  • Translation rows gain origin. GET /translatable-resources/{type}/{id} and PUT /translations/{type}/{id} return origin: machine for a translation written by machine translation, human for any other. A person's write over a machine translation makes it human. Machine translation never refreshes or overwrites a translation a person wrote, even when it is out of date: it is held as human_written.
  • New error codes. machine_translation_off, machine_translation_unavailable, machine_translation_busy, insufficient_credits, quote_expired, quote_mismatch, quote_already_used, quote_stale, translation_run_too_large and translation_daily_limit. See Merchant API errors.

2026-10-18 — Customer privacy topics

  • New topics customers/data_request and customers/redact. A merchant can now ask, from a customer's profile in the dashboard, for the data held about that customer or for their personal data to be erased. Apps that declare the topics in their manifest are told, with ids only (the request id, the customer id, the customer's order ids and the request time): no name, email or phone. An erasure waits 10 days so it can be cancelled, and is held until 180 days after the customer's most recent order. Delivery is at-least-once; dedupe on data.id. See Customer privacy topics.
  • No scope and no approval line. The topics are sent to every active installation whose manifest declares them, even installs made before they existed, and even when the store has switched customer topics off.
  • customers/delete is documented as a removal from the store's directory, not an erasure. Shop-level erasure is unchanged: it is the app/uninstalled handoff with reason: "store_deleted".

2026-10-17 — Merchant API: refund an order

  • POST /orders/{order}/refunds refunds one payment of an order, in full or in part. It needs the merchant-orders-refund-create scope (review-required for apps) and an Idempotency-Key, which is required on this call: without it the request answers 400 idempotency_key_required. The refund follows the original payment: a card or bank payment goes back through the payment provider (type original_payment, pending until the provider processes it), a wallet payment goes back to the wallet (wallet_credit), and a payment the store took itself is only recorded (recorded). The call returns the refund with refundable and restocked. See Refunds.
  • Order reads gain refundable and line_items[].refundable_quantity. refundable is { "amount", "currency" }: what can still be refunded on the order. Both need merchant-orders-read; refundable_quantity is null without it.
  • refunds[] rows and the refunds/create payload gain type and reason. type is wallet_credit, original_payment or recorded; reason is order_cancelled or merchant_refund. A refund made by a cancellation keeps wallet_credit and order_cancelled. refunds/create is now sent for every kind of refund, once, when it is created; a card or bank refund finishing or failing is signalled by orders/updated.
  • A cancelled order paid by card or bank is refunded to the card or bank. Cancellations of orders Queek collected through its payment provider no longer credit the wallet instead.

2026-10-16 — Merchant API: pages, posts and menus translate by p_id

  • GET /translatable-resources?type=page, post and menu answer with integer ids. Like every other type, each item's id is the record's p_id, and {id} on GET /translatable-resources/{type}/{id}, PUT /translations/{type}/{id} and DELETE /translations/{type}/{id} takes that integer or the UUID. PageResource and PostResource carry p_id beside the UUID id, so the numbers match.
  • page and post are separate types. page covers every page that is not a blog post, and post only the blog posts. A page id can no longer be read or written as a post, or the reverse.
  • collection and category list only the store's own collections. The two types list the same rows, and the shared product taxonomy is never listed or written. Translations are kept per type: see Translate store content.

2026-10-23 — Days follow the store's timezone; every timestamp carries its offset

  • Day-based reads use the store's own calendar. A store's timezone (the store object, GET /store) now sets its days everywhere: Merchant API order from_date, to_date and date_range (today, this_week, this_month), analytics start_date/end_date, and "today". Before, every store's days were counted in Africa/Lagos. For a store in Africa/Lagos nothing changes.
  • A date-time you send without an offset is read on the store's clock. A coupon's starts_at, a discount's valid_until or a post's published_at sent as 2026-10-30T23:58 means 23:58 in the store's timezone; one sent with an offset (2026-10-31T03:58:00Z) keeps it. Before, an incoming offset was dropped.
  • Merchant API: tax timestamps carry an offset. created_at and updated_at on taxes were 2026-10-23 06:17:26, with no zone; they are now 2026-10-23T06:17:26+01:00, the same instant.
  • Storefront API: product, post, page and menu timestamps use one spelling. Product created_at and updated_at were offset-less (2026-09-01 12:00:00) and now carry +01:00; posts, pages and menus were UTC (2026-08-27T12:00:00.000000Z) and are now 2026-08-27T13:00:00+01:00. Each value is the same instant as before, so a client that parses ISO-8601 sees no difference. GET /store/info is_open and GET /store/config business_hours.timezone follow the store's timezone.

2026-10-12 — Merchant API: product responses carry collections only

  • The derived collection_category_ids list is gone from product responses. Every product already carried collections, the full objects (id, name, and the rest), and collection_category_ids was only those ids copied out under the old name. Read the ids from collections[].id; they are the same values you send back as collection_ids.
  • Discount rules are a separate field and are unchanged: rules_json.collection_category_ids still targets your collections.

2026-10-09 — Merchant API: one collection_ids field for product collections

  • POST /products and PUT /products/{product} take collection_ids. It is an array of your store's own collection ids (up to 50), the same for every store, and optional on create. Read the ids from GET /collections. On update, omit it or send null to keep the product's current collections, or send [] to clear them. Each id must be one of your own active manual collections. A marketplace (global) category, another store's collection, a deleted collection or a smart collection answers 422 validation_failed on collection_ids.N — smart collections fill themselves from their rules, so a product is never added to one by hand.
  • categories and collection_category_ids are no longer read. collection_ids is the only collection field on product writes. A request that still sends either key is not rejected; the key is ignored and the product's collections are left unchanged. Move to collection_ids.
  • taxonomy_category_id, taxonomy_node_id and taxonomy_slug are accepted and ignored. The marketplace taxonomy is assigned by Queek and is never something a merchant sets, so these inputs no longer link a product to anything. Older clients that still send them do not break; they just stop having an effect. Send collection_ids to place a product in your own collections.
  • Smart collection rules: collection_id replaces taxonomy_category_id. collection_id takes operator eq (one collection id) or includes (a list of ids) and matches the products already in those collections. A new rule that still carries the retired taxonomy_category_id field is rejected: POST /collections/bulk answers 422 validation_failed on collections.N.collection_rules.conditions.M.field ("The taxonomy_category_id rule is retired — use collection_id.").
  • GET /products?taxonomy_category_id= keeps working as an alias of category_id: it matches the products in your store's own collection of that category.
  • Headless API: GET /store/categories and GET /store/categories/{category}/products answer 410 Gone. Use GET /store/collections and GET /store/collections/{collection}/products, which return the same collections your merchant manages.
  • Dashboard API: the old category routes are removed. vendors/{vendor}/categories*, biz/vendor/categories/tree, biz/vendor/categories/main-roots, biz/vendor/categories/main/{id}/tree, biz/vendor/listing/taxonomy-categories, and the service category routes data/service/{id}/categories, data/service/{id}/category_types, s/service/{id}/category_types and service/{id}/categories no longer exist. None of them is part of the Merchant API.

2026-09-25 — POST /orders/import takes naira

unit_price, delivery_fee, discount and total are now amounts in naira with at most 2 decimals (6500 or "6500.00"), like every other Merchant API amount — they were integers in kobo. The receipt must add up: the sum of unit_price × quantity, plus delivery_fee, minus discount, equals total, or the import answers 422 validation_failed on total with the amount it expected. Caps: ₦1,000,000 per unit price, delivery fee or discount, ₦10,000,000 per total. If you sent kobo, divide by 100 before sending.

2026-09-25 — Merchant API: real examples, deletes name what they deleted

  • The reference shows real calls. Every operation now carries a realistic request body, path and page parameter values from one example store, and the exact 404 and 422 bodies that operation answers — the 422 names a field the operation validates. request_id in every example is a UUID, as the API sends it.
  • Variant and image deletes answer what they deleted. DELETE /products/{product}/variants/{variant} answered data: []; it now answers {"id": 7731, "uid": "…", "deleted": true} (the variant's own ids). DELETE /products/{product}/images/{image} answers {"id": 88215, "deleted": true} — id is null when the removed primary image was a bare URL with no media row. DELETE /products/{product} gains "deleted": true beside its id and p_id. A client that tested data for an empty list should test data.deleted.
  • A missing record's 404 names the record. Operations that answered "No query results for model [App\Models\Product] 20417" now answer "Product not found." (likewise for orders and shipping zones), and GET /customers/{customer} answers "Customer not found" (was "User not found"). error.code is unchanged (not_found) — branch on it, never on the message.
  • An imported order's customer is on shipping_address. POST /orders/import stores the platform's customer (name + phone) as the order's recipient: shipping_address.name and shipping_address.phone (new, additive; null on every other order), readable only with merchant-customers-contact-read like every contact. Webhooks carry them, as they carry customer. Queek never writes contact into metadata, and a key without the contact scope reads metadata without contact keys (customer_phone, phone, email, …).

2026-09-25 — order payload: store customer and shipment

The order object — every orders/* webhook and every Merchant API order endpoint — changed in two ways:

  • customer is the store's own record of the buyer. Its id is now the store customer id (the one GET /customers/{customer} and the customers/* events use), and name, email and phone are what this store holds — no longer the buyer's global Queek profile, which could carry the name and contact they use at other stores. customer is null when the order has no store customer record (marketplace orders, imports placed under a guest). If you matched orders to people by the old customer.id, email or name, re-key on the new customer.id.
  • New shipment key (additive): carrier tracking on a shipping order — carrier_name, tracking_number, tracking_url, zone_name, shipped_at, estimated_delivery_at, delivered_at — or null. PATCH /orders/{order}/shipment answers the order with it.

2026-09-23 — public API naming

The Merchant API moved to clean public paths under /api/v1/merchant/* (49 operations in 14 groups: Store, Products, Variants, Images, Collections, Inventory, Orders, Customers, Discounts, Coupons, Shipping zones, Metafields, Metaobjects, Content), each with a standard name and one update verb per resource; discounts gained list and retrieve. The earlier biz/vendor paths — live only hours, never announced — now refuse keys with route_not_available naming the new path. The scopes table is regenerated (32 scopes, adding discount list and retrieve).

The Storefront reference is complete: 57 operations with standard names (the committed snapshot had only 30), including the account, address, follow, order and metaobject groups, grouped by the spec's own order.

2026-09-23 — Merchant API v1

The Merchant API is documented: server-side access for a store's own systems (ERP and stock sync, fulfilment, catalogue) on https://api.usequeek.com/api/v1/biz, authenticated by a private sk_ key alone. New section beside the storefront docs with an overview, authentication & keys, a scopes table generated from the spec (30 scopes across 49 operations), idempotency & rate limits, errors, and an endpoint reference generated from the new spec/merchant-openapi.json snapshot (37 paths, 18 tags).

2026-09-22 — snapshot baseline

Baseline snapshot: 29 paths, 30 operations, 7 shared schemas. Future entries list added/removed/changed paths and schemas against this starting point.

On this page