Skip to content
Developers

Developer API

Manage your store's products, orders, customers, design and settings through a REST API, with tokens limited to the scopes you choose.

The Stoily Developer API is a versioned REST API. Use it to manage your store's design, scripts and settings, and its Magento commerce data: products, orders, customers and inventory. One scoped token covers all of it, and the contract is published as OpenAPI 3.1.

Authentication

Authenticate with a Personal Access Token in the Authorization header:

http
Authorization: Bearer stoily_pat_live_xxxxxxxxxxxx

Create and manage tokens in your admin under Settings → Developer → API Tokens. Each token is scoped to the stores you select, with per-resource permissions, shown once on creation, and can be rotated or revoked at any time. Tokens may carry an expiry and optional IP allowlist. Live tokens use the stoily_pat_live_ prefix; sandbox tokens use stoily_pat_test_. Tokens issued before the Stoily rebrand carry a soc_pat_ prefix and still work. There is nothing to rotate.

Base URL and versioning

All endpoints live under https://api.stoily.com/api/v1. The machine-readable contract is published at /api/v1/openapi.json (OpenAPI 3.1). Use it to generate an SDK or to load the API into your HTTP client.

Quickstart

bash
# List the stores your token can access
curl https://api.stoily.com/api/v1/stores \
  -H "Authorization: Bearer stoily_pat_live_xxxxxxxxxxxx"

# Read a store's design document
curl https://api.stoily.com/api/v1/stores/STORE_ID/design \
  -H "Authorization: Bearer stoily_pat_live_xxxxxxxxxxxx"

# Update theme + tracking scripts (design:write)
curl -X PUT https://api.stoily.com/api/v1/stores/STORE_ID/design \
  -H "Authorization: Bearer stoily_pat_live_xxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"design":{"primaryColor":"#111827","customCodeSnippets":[]}}'

# Talk to the store's Magento commerce data through the gateway (orders:read)
curl https://api.stoily.com/api/v1/stores/STORE_ID/commerce/orders \
  -H "Authorization: Bearer stoily_pat_live_xxxxxxxxxxxx"

Permissions (scopes)

A token grants read or write per resource. write implies read. A token can never exceed the access of the account that created it. Available resources:

ResourceAccess
storesstores:read · stores:write
designdesign:read · design:write
settingssettings:read · settings:write
emailemail:read · email:write
domainsdomains:read · domains:write
membersmembers:read · members:write
webhookswebhooks:read · webhooks:write
integrationsintegrations:read · integrations:write
extensionsextensions:read · extensions:write
backupsbackups:read · backups:write
deploymentsdeployments:read · deployments:write
ordersorders:read · orders:write
productsproducts:read · products:write
customerscustomers:read · customers:write
inventoryinventory:read · inventory:write

Commerce gateway

GET/api/v1/stores/{storeId}/commerce/{path}

Passes your request through to that store's Magento REST API (orders, products, customers, inventory and more), limited by your token's scopes. Send the Magento resource path directly, e.g. commerce/orders or commerce/products/ABC-1. For a Magento endpoint the gateway does not cover, you can get a direct Magento token from your admin.

Idempotency

Retry a write safely by sending an Idempotency-Key header. The first response is recorded for 24 hours; a retry with the same key replays it (Idempotent-Replayed: true), and reusing a key with a different body returns 422.

bash
curl -X POST https://api.stoily.com/api/v1/stores/STORE_ID/commerce/products \
  -H "Authorization: Bearer stoily_pat_live_xxxxxxxxxxxx" \
  -H "Idempotency-Key: 9f1c5b8e-..." \
  -H "Content-Type: application/json" \
  -d '{ "product": { "sku": "ABC-1", "name": "Widget" } }'

Rate limits

Responses carry RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers. Exceeding the limit returns 429 with a Retry-After header. Wait that long, then retry.

Errors

Errors use application/problem+json (RFC 9457) with type, title, status, and detail. Commerce responses are returned verbatim from Magento with the upstream status code.

Security

Treat a token like a password and never commit it to a repository. If a token leaks, revoke it in your admin straight away.

Build on these