Scopes
Complete list of all 18 API key scopes, their permissions, and which scope bundles include them.
Scopes
API keys are assigned granular scopes that control which endpoints they can access. This page is the complete reference for all available scopes.
All scopes
| Scope | Description | Requires sk_ | Pay bundle | Store bundle | Full bundle |
|---|---|---|---|---|---|
pay.intents:read | List and retrieve payment intents | No | Yes | -- | Yes |
pay.intents:write | Create, update, cancel, and refund payment intents | Yes | Yes | -- | Yes |
store.products:read | List and retrieve products | No | -- | Yes | Yes |
store.products:write | Create, update, and delete products | Yes | -- | Yes | Yes |
store.orders:read | List and retrieve orders | No | -- | Yes | Yes |
store.orders:write | Update order status, fulfill orders | Yes | -- | Yes | Yes |
store.inventory:read | Read inventory levels | No | -- | Yes | Yes |
store.inventory:write | Update stock quantities | Yes | -- | Yes | Yes |
store.import:write | Import products via CSV | Yes | -- | Yes | Yes |
enterprise.transfers:read | List and retrieve transfers | No | -- | -- | Yes |
enterprise.transfers:write | Create transfers | Yes | -- | -- | Yes |
enterprise.bulk:write | Create bulk transfers | Yes | -- | -- | Yes |
enterprise.bills:write | Pay bills | Yes | -- | -- | Yes |
enterprise.ledger:read | Read ledger entries | No | -- | -- | Yes |
webhooks.endpoints:read | List webhook endpoints | No | Yes | Yes | Yes |
webhooks.endpoints:manage | Create, update, and delete endpoints | Yes | Yes | Yes | Yes |
webhooks.deliveries:read | List webhook event deliveries | No | Yes | Yes | Yes |
webhooks.deliveries:retry | Retry failed deliveries | Yes | Yes | Yes | Yes |
Scope bundles
When creating an API key, you can select individual scopes or use a predefined bundle for convenience.
Pay bundle
Includes all Pay API scopes plus webhooks and account read. Ideal for payment integrations.
Scopes: pay.intents:read, pay.intents:write, webhooks.endpoints:read, webhooks.endpoints:manage, webhooks.deliveries:read, webhooks.deliveries:retry
Store bundle
Includes all Store API scopes plus webhooks and account read. Ideal for inventory and order management integrations.
Scopes: store.products:read, store.products:write, store.orders:read, store.orders:write, store.inventory:read, store.inventory:write, store.import:write, webhooks.endpoints:read, webhooks.endpoints:manage, webhooks.deliveries:read, webhooks.deliveries:retry
Full bundle
Includes every scope. Use with caution -- grant only the permissions your integration needs.
Scopes: All 18 scopes listed above.
Scope enforcement
- Read scopes (
:read) are required forGETrequests to the corresponding resource. - Write scopes (
:write) are required forPOST,PATCH,PUT, andDELETErequests. - If a request is missing a required scope, the API returns a
403error with codeSCOPE_REQUIRED. - Webhook event subscriptions require the corresponding read scope. For example, subscribing to
order.acceptedrequiresstore.orders:read.
Publishable vs secret key scopes
- Publishable keys (
pk_) can only use:readscopes. Even if:writescopes are assigned, they are ignored for publishable keys. - Secret keys (
sk_) can use both:readand:writescopes.
Next steps
- Authentication -- how to pass API keys
- Error Codes --
SCOPE_REQUIREDerror details - Going Live -- scope recommendations for production
Was this page helpful?