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:

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

   Standard OAuth fields

   The response carries the RFC 6749 fields access_token / token_type / expires_in, so a stock OAuth client library reads it. The camelCase accessToken / tokenType / expiresIn are kept for existing apps; new code should use the snake_case ones. You may also send the credentials as an HTTP Basic header.

   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, {"error":"invalid_client",…}	Wrong id or secret, the app is suspended, or it is not installed on this domain’s store.
401 on an API call, error.code invalid_token or tenant_not_active	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, error.code missing_scope	Your installation lacks the scope that operation requires; error.scope names it. wrong_store means the token belongs to another store. The reference names the scope on every operation.
429, error.code rate_limited	You exceeded a rate limit. Wait Retry-After seconds.

Details: errors.