Merchant API overview
The server-side API for a store's own systems, covering catalogue, stock, orders and customers. Scoped private keys, idempotent writes, cursor pagination.
The Merchant API is how a store's own servers read and write its Queek data: an ERP pushing stock levels, a fulfilment service moving orders through statuses, a catalogue tool creating products, collections and discounts. It is the server-side counterpart to the Headless API, which serves shoppers, and it never touches checkout, payment collection or delivery dispatch directly.
It has 146 operations in 25 groups. Each operation requires exactly one scope, so a key can be limited to the one job it does.
You will end this page having read a store, adjusted a stock level safely, and knowing where retries, limits and errors are documented. Every snippet is a complete request: put a real key in it and it runs.
Get a private key
The merchant mints it in the Queek dashboard, under Settings → Connections
(New API key, a private key), and hands it to you. It is a private sk_live_… key —
sk_test_… on a dev store — bound to one store, carrying
exactly the scopes the integration needs. There is no
OAuth flow and no token exchange: the key is the credential.
Servers only
The key authenticates alone and acts for the whole store. Keep it on your
server — never in browser code, an app bundle, or a public repository. A public
pk_ key is a browser credential and is refused here.
Make the first request
Every call carries the key in X-Client-Key, and the base URL is
https://api.usequeek.com/api/v1/merchant. No vendor header, no vendor_id: the
key already names its store.
curl https://api.usequeek.com/api/v1/merchant/store \
-H "X-Client-Key: sk_live_..." \
-H "Accept: application/json"GET /store is the one call you always make first. It returns the store
you are acting for — if the key is wrong, this is where you find out.
Make a first write
Set a product's stock to a counted quantity. expected_stock makes it a compare-and-set: if
the level changed since you read it, nothing is written.
curl -X POST https://api.usequeek.com/api/v1/merchant/inventory/levels/adjustments \
-H "X-Client-Key: sk_live_..." \
-H "Idempotency-Key: 7d3c4c1a-2c50-4c0f-8f0f-3a4d1a2b9c77" \
-H "Content-Type: application/json" \
-d '{"product": "20417", "mode": "set", "quantity": 44, "expected_stock": 42, "reason_code": "count"}'The key needs the merchant-inventory-update scope. The reply carries the level before and
after (level.before, level.after) and the audit row it wrote. If someone sold or received
stock in between, you get 409 conflict with data.current_stock: read that value, decide,
and retry with it as expected_stock. A retry with the same Idempotency-Key and body replays
the first answer instead of writing twice.
reason_code is one of correction, count, damage, received, return, theft or
other. This operation handles one product or variant per call. To apply one delta to many
products, use POST /inventory/adjustments.
What the API covers
| Area | Groups |
|---|---|
| Catalogue | Products, Variants, Images, Collections, Add-ons, Metafields, Metaobjects, Publications |
| Stock and orders | Inventory, Orders, Payments (settlement batches) |
| People | Customers, Team |
| Marketing and content | Discounts, Coupons, Content (posts), Reviews, Translations |
| Store setup | Store, Shipping zones, Files, Analytics |
| Apps | Records, collected definitions, merchant alerts and installation notices |
Read Scopes for what each operation needs, then work through the reference. A few rules hold everywhere:
- Money is a decimal string (
"1500.00") beside an ISO 4217currency, never a JSON number. - Dates are ISO 8601 with a numeric offset.
- Lists use cursor pagination: send
next_cursorasstarting_afterwhilehas_moreis true. See Building safe integrations. - Writes take an
Idempotency-Key. See Idempotency & rate limits. - Deletes answer
200with the envelope, never204. Creates answer200or201, documented per operation. - Customer contact (name, email, phone, address) is
nullunless the key holds the contact scope. - Failures answer in one error envelope. Branch on
error.code.
Stay in sync with events
Do not poll. Queek posts signed events for orders, products, customers, stock levels and
translations. The webhooks are shared with the storefront: same topics, same
verification, same retries. This API moves the store's state; webhooks tell you when a shopper
or checkout moved it first. For anything you missed, reconcile with a cursor walk and
updated_after on orders.
Where to go next
Authentication & keys
The private key alone, one store per key, scopes as permission, and what each refusal means.
Scopes
The scopes and operations each unlocks, generated from the spec.
Idempotency & rate limits
Retry writes safely, and understand the per-key, per-plan quota.
Building safe integrations
Cursor reads, retries, error handling, and an integration checklist.
Merchant endpoint reference
Every operation, parameter and response, generated from the merchant OpenAPI spec.
Errors
The one envelope, every code this API emits, and the retries that are safe.
Webhooks
Order events pushed to your server, signed with Standard Webhooks.
The reference is generated from the committed OpenAPI document,
spec/merchant-openapi.json. Import it into any OpenAPI client to explore the API
interactively.