Skip to main content

API Overview

The eshopOS public API lets approved integrations read and write commerce records through documented REST endpoints. It is intended for storefronts, merchant-approved apps, automations, and partner integrations.

For store setup, account changes, provider configuration, and team management, use the Merchant Hub dashboard.

Base URL​

All public API requests are made to your public API host:

https://api.eshop-os.com

Public endpoints live under /api/public/v1.

Versioning​

When we make backwards-incompatible changes to the API, we release a new major version. The current version is v1.

  • Breaking changes: Require a new version (e.g., v2).
  • Non-breaking changes: Added as incremental updates to the current version.

Format​

All request bodies must be JSON, and all responses will be returned in JSON.

{
  "status": "success",
  "data": { ... }
}

Idempotency​

Use idempotency keys on retryable write requests that create or advance commerce state. Idempotency helps prevent duplicate work when a client retries after a timeout or network failure.

Pass a unique Idempotency-Key header for each logical operation.

Idempotency-Key: <unique_string>

X-Idempotency-Key is accepted for older clients, but new integrations should use Idempotency-Key.

Generate a new key for each new logical operation. Reuse the same key only when retrying the same request.

Use 1-120 characters. Letters, numbers, hyphens, underscores, periods, and colons are preserved.