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 (
typepost only).owner_typeacceptsproduct,order,customer,collection,postandvariant. See Custom fields. - Two access switches per definition.
storefront_visibledecides 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 ownGET /auth/meandGET /store/orders*, read-only. - Public reads carry
metafieldson each variant of a product, on collections and on blog posts, only for fields the merchant switched on.GET /store/metafield-definitionstakesowner_type(productdefault,variant,collection,post). - Merchant API:
variants[].metafieldsonPOST/PUT /productsand on the single-variant routes;metafieldsonPOST /postsandPUT /posts/{post}; customers'metafieldson the customer reads. New:GET /collections/{collection}(scopemerchant-collections-detail) andPUT /collections/{collection}(scopemerchant-collections-update), which writesmetafields.POST /collections/bulkrefusesmetafields. - Webhooks:
products/*carry every variant's values;customers/createandcustomers/updatecarry the customer'smetafields. 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
idback 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, theX-Client-Keyheader 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_urlcarries the return link. When the connection lists after-checkout return links,checkout_urlends 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_inactiveandapi_key_mode_mismatchnow 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/quoteandPOST /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,modeandresourcesoftype,idand optionalkeys), 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 asheldwith a reason and nothing is written for it. The run needs anIdempotency-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 answer403 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}andPUT /translations/{type}/{id}returnorigin:machinefor a translation written by machine translation,humanfor any other. A person's write over a machine translation makes ithuman. Machine translation never refreshes or overwrites a translation a person wrote, even when it is out of date: it is held ashuman_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_largeandtranslation_daily_limit. See Merchant API errors.
2026-10-18 — Customer privacy topics
- New topics
customers/data_requestandcustomers/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 ondata.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/deleteis documented as a removal from the store's directory, not an erasure. Shop-level erasure is unchanged: it is theapp/uninstalledhandoff withreason: "store_deleted".
2026-10-17 — Merchant API: refund an order
POST /orders/{order}/refundsrefunds one payment of an order, in full or in part. It needs themerchant-orders-refund-createscope (review-required for apps) and anIdempotency-Key, which is required on this call: without it the request answers400 idempotency_key_required. The refund follows the original payment: a card or bank payment goes back through the payment provider (typeoriginal_payment,pendinguntil 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 withrefundableandrestocked. See Refunds.- Order reads gain
refundableandline_items[].refundable_quantity.refundableis{ "amount", "currency" }: what can still be refunded on the order. Both needmerchant-orders-read;refundable_quantityisnullwithout it. refunds[]rows and therefunds/createpayload gaintypeandreason.typeiswallet_credit,original_paymentorrecorded;reasonisorder_cancelledormerchant_refund. A refund made by a cancellation keepswallet_creditandorder_cancelled.refunds/createis now sent for every kind of refund, once, when it is created; a card or bank refund finishing or failing is signalled byorders/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,postandmenuanswer with integer ids. Like every other type, each item'sidis the record'sp_id, and{id}onGET /translatable-resources/{type}/{id},PUT /translations/{type}/{id}andDELETE /translations/{type}/{id}takes that integer or the UUID.PageResourceandPostResourcecarryp_idbeside the UUIDid, so the numbers match.pageandpostare separate types.pagecovers every page that is not a blog post, andpostonly the blog posts. A page id can no longer be read or written as a post, or the reverse.collectionandcategorylist 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 orderfrom_date,to_dateanddate_range(today,this_week,this_month), analyticsstart_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'svalid_untilor a post'spublished_atsent as2026-10-30T23:58means 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_atandupdated_aton taxes were2026-10-23 06:17:26, with no zone; they are now2026-10-23T06:17:26+01:00, the same instant. - Storefront API: product, post, page and menu timestamps use one spelling. Product
created_atandupdated_atwere 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 now2026-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/infois_openandGET /store/configbusiness_hours.timezonefollow the store's timezone.
2026-10-12 — Merchant API: product responses carry collections only
- The derived
collection_category_idslist is gone from product responses. Every product already carriedcollections, the full objects (id,name, and the rest), andcollection_category_idswas only those ids copied out under the old name. Read the ids fromcollections[].id; they are the same values you send back ascollection_ids. - Discount rules are a separate field and are unchanged:
rules_json.collection_category_idsstill targets your collections.
2026-10-09 — Merchant API: one collection_ids field for product collections
POST /productsandPUT /products/{product}takecollection_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 fromGET /collections. On update, omit it or sendnullto 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 answers422 validation_failedoncollection_ids.N— smart collections fill themselves from their rules, so a product is never added to one by hand.categoriesandcollection_category_idsare no longer read.collection_idsis 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 tocollection_ids.taxonomy_category_id,taxonomy_node_idandtaxonomy_slugare 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. Sendcollection_idsto place a product in your own collections.- Smart collection rules:
collection_idreplacestaxonomy_category_id.collection_idtakes operatoreq(one collection id) orincludes(a list of ids) and matches the products already in those collections. A new rule that still carries the retiredtaxonomy_category_idfield is rejected:POST /collections/bulkanswers422 validation_failedoncollections.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 ofcategory_id: it matches the products in your store's own collection of that category.- Headless API:
GET /store/categoriesandGET /store/categories/{category}/productsanswer410 Gone. UseGET /store/collectionsandGET /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 routesdata/service/{id}/categories,data/service/{id}/category_types,s/service/{id}/category_typesandservice/{id}/categoriesno 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
404and422bodies that operation answers — the422names a field the operation validates.request_idin every example is a UUID, as the API sends it. - Variant and image deletes answer what they deleted.
DELETE /products/{product}/variants/{variant}answereddata: []; it now answers{"id": 7731, "uid": "…", "deleted": true}(the variant's own ids).DELETE /products/{product}/images/{image}answers{"id": 88215, "deleted": true}—idisnullwhen the removed primary image was a bare URL with no media row.DELETE /products/{product}gains"deleted": truebeside itsidandp_id. A client that testeddatafor an empty list should testdata.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), andGET /customers/{customer}answers"Customer not found"(was"User not found").error.codeis unchanged (not_found) — branch on it, never on the message. - An imported order's customer is on
shipping_address.POST /orders/importstores the platform's customer (name + phone) as the order's recipient:shipping_address.nameandshipping_address.phone(new, additive;nullon every other order), readable only withmerchant-customers-contact-readlike every contact. Webhooks carry them, as they carrycustomer. Queek never writes contact intometadata, and a key without the contact scope readsmetadatawithout 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:
customeris the store's own record of the buyer. Itsidis now the store customer id (the oneGET /customers/{customer}and thecustomers/*events use), andname,emailandphoneare what this store holds — no longer the buyer's global Queek profile, which could carry the name and contact they use at other stores.customerisnullwhen the order has no store customer record (marketplace orders, imports placed under a guest). If you matched orders to people by the oldcustomer.id,emailorname, re-key on the newcustomer.id.- New
shipmentkey (additive): carrier tracking on a shipping order —carrier_name,tracking_number,tracking_url,zone_name,shipped_at,estimated_delivery_at,delivered_at— ornull.PATCH /orders/{order}/shipmentanswers 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.