Quickstart

You need an installed app — its client id, client secret, signing secret — and the store’s primary domain. If the store created the app itself (Settings → Apps → Create app), all three secrets were shown once at creation. Below, the store is www.example-store.com.

1. Exchange your credentials for a token.

   curl -X POST https://www.example-store.com/apps/token \
     -d grant_type=client_credentials \
     -d client_id=ciqra_ci_... \
     -d client_secret=ciqra_cs_...

   The body must be form-encoded (application/x-www-form-urlencoded). The response:

   {
     "accessToken": "ciqra_at_...",
     "tokenType": "Bearer",
     "expiresIn": 3600,
     "scope": "read_products write_products read_webhooks write_webhooks",
     "scopeNotYetEnforced": ""
   }

   The keys are camelCase

   The response uses accessToken / tokenType / expiresIn, not the access_token form RFC 6749 specifies, so a stock OAuth client library will not read it. Parse the JSON yourself. See known limitations.

   The token lives one hour and there is no refresh token: when it is about to expire, run this call again. scope is what you may actually do (a write_ scope includes its read_); scopeNotYetEnforced lists the granted scopes that no endpoint honours yet.

2. Call the API with the token.

   curl https://www.example-store.com/apps/catalog/products?take=10 \
     -H "Authorization: Bearer ciqra_at_..."

   { "total": 1284, "skip": 0, "take": 10, "items": [ { "id": "…", "name": "…", "status": "Active", "…": "…" } ] }

   Requires read_products. Pages are skip/take; see requests & pagination.

3. Change something — idempotently.

   curl -X POST https://www.example-store.com/apps/catalog/products/bulk \
     -H "Authorization: Bearer ciqra_at_..." \
     -H "Idempotency-Key: 7c4a1e0e-rename-run-1" \
     -H "Content-Type: application/json" \
     -d '{"products":[{"id":"<product id>","metaTitle":"Winter coat — free shipping"}]}'

   Requires write_products. Writes that create side effects require an Idempotency-Key; if the network drops and you retry with the same key and body, you get the first response back instead of a second write. See idempotency.

4. Subscribe to events.

   curl -X POST https://www.example-store.com/apps/webhooks/subscriptions \
     -H "Authorization: Bearer ciqra_at_..." \
     -H "Content-Type: application/json" \
     -d '{"url":"https://hooks.your-app.example/ciqra","eventTypes":["order.paid"]}'

   Requires write_webhooks. Deliveries are signed with your installation’s signing secret — verify every one.

If something fails

You see	It means
401 from /apps/token, empty body	Wrong id or secret, the app is suspended, or it is not installed on this domain’s store.
401 on an API call, empty body	Token expired, revoked, the installation was removed, or the store is not active. Get a new token once; if that also fails, the installation is gone.
403, empty body	Your installation lacks the scope that operation requires. The reference names it on every operation.
429	You exceeded a rate limit. Wait Retry-After seconds.

Details: errors.