Get Optional Scopes
GET/api/shopify/:integrationInstance/optional-scopes
Get the state of two Shopify access scopes: read_reports (Shopify shipping label costs in profit reports), which every authorization requests, and read_all_orders (orders older than 60 days), which Shopify must approve first and which a merchant's own Shopify app requests only once the merchant reports that approval (SKU.io's own app holds the approval and always requests it). For each one: what it unlocks, whether the next re-authorization asks for it, whether the store has granted it, and its set-up state.
integrations:readGrant this scope to your token under Settings → Developer → Personal Access Tokens.
state is one of not_requested, waiting_on_shopify (the merchant said they asked Shopify to approve the access request), ready_to_authorize (the next re-authorization asks for it), granted (Shopify reports it for this installation) or unknown (Shopify could not be asked, for example a rejected access token). Shopify does not report pending or approved access requests, so waiting_on_shopify and ready_to_authorize come from the steps recorded with Record Optional Scope Step.
Also returns how far back Shopify shares orders: readable_from (Y-m-d) is the oldest order date Shopify serves while read_all_orders is not granted, and null once it is (or when the scopes could not be read). earliest_order_in_sku is the oldest order SKU.io has downloaded. app_kind says who can add a scope: own_app (the merchant's own Dev Dashboard app), sku_app (SKU.io's public app) or access_token (an Admin API access token, managed in Shopify admin).
Authentication: Requires Bearer token.
label_costs_synced_through (Y-m-d) is the last day of Shopify shipping label costs imported into sales order cost lines, label_costs_last_run_at (ISO 8601) is when that daily import last ran, and label_costs_error says why it stopped if Shopify refused it. All three are null before the first import.
scopes_to_add_to_app lists, for a store connected through the merchant's own Shopify app, every scope the next authorization will request that the store has not granted yet. The app's released version must list them first, or Shopify refuses the authorization with invalid_scope. It is always empty for stores on SKU.io's own app.
Request
Responses
- 200
- 401
- 403
- 404
- 429
OK
Response Headers
Unauthenticated — the bearer token is missing, revoked, expired, or malformed. Never retry automatically; fix the credential. See the Errors guide.
Forbidden — the token lacks a required scope, the endpoint is not available to API tokens, or the user behind the token lacks the permission. A human must adjust the token scopes or user permissions; do not retry.
Not found — no record with the given identifier (or the route does not exist). Verify the ID before retrying.
Rate limited — platform limit is 1,000 requests/min; individual tokens may carry lower limits. Honor the Retry-After header before retrying. See the Rate Limits guide.