The StoreOnCloud Developer API is a versioned REST API for automating everything you can do in the control panel: branding and design, script uploads, store settings, and your full Magento commerce data. It is the single front door for your stores — one scoped credential, consistent governance, and an OpenAPI 3.1 contract.

Authentication

Authenticate with a Personal Access Token in the Authorization header:

Authorization: Bearer soc_pat_live_xxxxxxxxxxxx

Create and manage tokens in the control panel under Settings → Developer → API Tokens. Each token is scoped to selected store(s) 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 soc_pat_live_ prefix; sandbox tokens use soc_pat_test_.

Base URL & versioning

All endpoints live under https://api.storeoncloud.com/api/v1. The machine-readable contract is published at /api/v1/openapi.json (OpenAPI 3.1) — use it to generate SDKs or explore the API in your favorite client.

Quickstart

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

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

# Update theme + tracking scripts (design:write)
curl -X PUT https://api.storeoncloud.com/api/v1/stores/STORE_ID/design \
  -H "Authorization: Bearer soc_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.storeoncloud.com/api/v1/stores/STORE_ID/commerce/orders \
  -H "Authorization: Bearer soc_pat_live_xxxxxxxxxxxx"

Permissions (scopes)

A token grants read or write per resource. Available resources: stores, design, settings, email, domains, members, webhooks, integrations, extensions, backups, deployments, orders, products, customers, inventory. write implies read. A token can never exceed the access of the account that created it.

Commerce gateway

/api/v1/stores/{storeId}/commerce/{path} transparently proxies to that store's Magento REST API (orders, products, customers, inventory, and more), governed by your token's scope. Send the Magento resource path directly, e.g. commerce/orders or commerce/products/ABC-1. For Magento-native endpoints we don't curate, you can also obtain a direct Magento token via the control panel as an advanced escape hatch.

Idempotency

Safely retry writes 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.

curl -X POST https://api.storeoncloud.com/api/v1/stores/STORE_ID/commerce/products \
  -H "Authorization: Bearer soc_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 — back off and 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 tokens like passwords: never commit them. If a token leaks, revoke it immediately in the control panel. We participate in secret-scanning programs and automatically revoke tokens reported as leaked.