API overview

Themes draw the storefront; apps and integrations use the APIs. Both are versioned by date: the current version is 2026-10, supported for 12 months.

Admin API

Read and change a store’s data: products, orders, customers, inventory, discounts, content and more.

• Base URL: https://api.sooquna.com/admin/api/2026-10
• Auth: an app’s access token in X-Sooquna-Access-Token (or Authorization: Bearer). Merchants create custom apps in Settings › Apps and API and choose their scopes; tokens are shown once.
• Scopes: read_products, write_orders… An endpoint needs the scope in the reference; write_ includes read_.
• Rate limit: a bucket of 40 requests per app and store, refilled at the plan’s rate. Read X-RateLimit-Remaining; a 429 comes with Retry-After.
• Pagination: ?limit= and ?after=<page_info.end_cursor>.
• Versions: in the last three months of a version, responses carry Deprecation and Sunset headers.

The Admin API reference has every endpoint with code in cURL, Node.js, Python, PHP, Go and C#, and the OpenAPI document generates clients.

Idempotency

Requests that create orders, move stock or money (draft orders and their completion, refunds, fulfilments, cancellations, marking paid, stock adjustments and moves, receiving transfers and purchase orders, creating customers) need an Idempotency-Key header: a random value, such as a UUID, new for each operation. If a request times out, send it again with the same key: within 24 hours it’s applied once and the retry gets the first answer. The same key with a different request is refused (idempotency_key_reused), and a retry while the first is still running gets 409 (idempotency_in_flight). Keys are up to 255 characters.

curl -X POST "https://api.sooquna.com/admin/api/2026-10/orders/$ORDER_ID/mark-paid" \
  -H "X-Sooquna-Access-Token: $SOOQUNA_TOKEN" \
  -H "Idempotency-Key: 4f7c1e8a-2b6d-4e0f-9a31-6c5d8e2b7f10"

Versions of a resource

Resources have a version. Send the version you read with an update; if someone changed the resource since, you get 409 and can read it again before retrying. PUT replaces the resource (fields left out are cleared, variants left out are deleted); PATCH changes only the fields you send.

Errors

Errors are problem details JSON with a stable code, a human detail, and errors per field for invalid input:

{ "status": 422, "code": "invalid_invalid", "detail": "Unknown sort order.", "errors": [{ "field": "sort_order", "code": "invalid", "message": "Unknown sort order." }] }

Storefront API

Public, read-mostly access for headless storefronts and mobile apps: products, collections, search, menus, pages, carts and customer sign-in.

• Base URL: /api/storefront/2026-10/… on the store’s domain or the API host.
• Auth: a public storefront token (sooquna_sf_…) from Settings › Apps and API.
• Language: ?locale= or Accept-Language, among the store’s published languages.
• Carts use the same engine as the storefront; checkout_url opens the hosted checkout.

Webhooks

Subscribe to events (orders/create, products/update…) per app. Each delivery is signed:

const crypto = require("node:crypto");
function verified(rawBody, header, secret) {
  const digest = crypto.createHmac("sha256", secret).update(rawBody).digest();
  const given = Buffer.from(header || "", "base64");
  return given.length === digest.length && crypto.timingSafeEqual(digest, given);
}

Compute the HMAC over the raw body (header X-Sooquna-Hmac-Sha256) before parsing it. Answer with a 2xx within 5 seconds and do the work afterwards; failures are retried for about 48 hours. X-Sooquna-Webhook-Id is the same across retries: use it to ignore duplicates.