Queek docs

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.

The 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.

Set stock to 44, expecting 42
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

AreaGroups
CatalogueProducts, Variants, Images, Collections, Add-ons, Metafields, Metaobjects, Publications
Stock and ordersInventory, Orders, Payments (settlement batches)
PeopleCustomers, Team
Marketing and contentDiscounts, Coupons, Content (posts), Reviews, Translations
Store setupStore, Shipping zones, Files, Analytics
AppsRecords, 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 4217 currency, never a JSON number.
  • Dates are ISO 8601 with a numeric offset.
  • Lists use cursor pagination: send next_cursor as starting_after while has_more is true. See Building safe integrations.
  • Writes take an Idempotency-Key. See Idempotency & rate limits.
  • Deletes answer 200 with the envelope, never 204. Creates answer 200 or 201, documented per operation.
  • Customer contact (name, email, phone, address) is null unless 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

The reference is generated from the committed OpenAPI document, spec/merchant-openapi.json. Import it into any OpenAPI client to explore the API interactively.

On this page