API introduction

​

API retirements

​

Guide vs reference

• /themes/* explains the ThemeDocument workflow and when to use settings, document, preview, and publish operations
• /api-reference/* explains the Dev API shape, auth, scopes, and endpoint details

​

Official SDKs

​

Base URL

https://api.shoppex.io/dev/v1

​

Authentication

• an API key like shx_..., for server-to-server integrations you manage directly
• an OAuth2 access token like shpat_..., for installable third-party apps

Authorization: Bearer shx_your_api_key_here

​

Request format

• Use Content-Type: application/json
• Send JSON-encoded request bodies
• Include the Authorization header

curl https://api.shoppex.io/dev/v1/invoices \
  -H "Authorization: Bearer shx_your_api_key_or_shpat_access_token" \
  -H "Content-Type: application/json"

​

OAuth2 flow

​

Payment retries and gateway switches

​

Orders & disputes

• use GET /orders for your operational order queue
• use POST /orders when your backend wants to create a pending order from catalog line items
• use POST /orders/:id/fulfill for a server-side fulfillment trigger on a pending order
• use POST /orders/:id/refund for merchant-driven refunds without the dashboard
• use POST /orders/:id/ship and POST /orders/:id/deliver to ship physical items and mark them delivered (see Physical products)
• use GET /disputes for chargebacks and payment-risk review

​

Invoices & payments

• use GET /invoices when you need the lower-level invoice resource directly
• use POST /payment-links or POST /payment-links/:id/toggle for sales-link workflows
• use GET /coupons/code/:code for server-side coupon validation by code

​

Subscriptions & customers

• use POST /subscriptions/:id/pause or PATCH /subscriptions/:id/custom-fields for recurring billing workflows
• use POST /customers/:id/wallet/credit or POST /customers/:id/wallet/debit for store-credit adjustments
• use GET /customers/:id?include_affiliate=true when you need customer detail plus affiliate summary in one response

​

Products & variants

• use GET /products?include_variants=true when you need product reads with inline variant prices
• use GET /shipping-zones, POST /shipping-zones, PUT /shipping-zones/:id, or DELETE /shipping-zones/:id to manage the flat shipping rates of physical products (products.* scopes, see Shipping zones)

​

Analytics & affiliates

• use GET /analytics/revenue for revenue totals and a daily timeline in the shop’s time zone
• use GET /affiliates/customers or POST /affiliates/applications/:id/approve for affiliate program automation

​

Workflows

​

Telegram

​

Store & themes

• use GET /store/branding, POST /store/domains/additional, GET /store/domains/additional/:id/verification, or PUT /store/layout for storefront automation
• use GET /themes/:id/control/document/draft, PUT /themes/:id/control/document, and POST /themes/:id/control/publish for revision-gated ThemeDocument automation
• use GET/POST /themes/:id/control/settings for settings-derived themes and POST /themes/:id/control/preview for previews

​

Licenses & webhooks

• use GET /licenses, POST /licenses, PATCH /licenses/:id, or DELETE /licenses/:id for license support workflows
• use POST /webhooks/logs/:id/retry or POST /webhooks/:id/rotate-secret for webhook ops workflows

​

Security

• use GET /security/audit-trail or GET /security/session-trail/:session_id for security and support workflows

• the public storefront flow already had POST /v1/storefront/coupons/check
• GET /coupons/code/:code is the server-to-server Dev API equivalent

​

Theme automation shortcut

• GET /themes
• POST /themes/control/create
• GET /themes/{id}/control/settings
• POST /themes/{id}/control/settings
• GET /themes/{id}/control/document
• GET /themes/{id}/control/document/draft
• PUT /themes/{id}/control/document
• POST /themes/{id}/control/document/validate
• GET /themes/{id}/control/document/schema
• POST /themes/{id}/control/preview
• DELETE /themes/{id}/control/preview/{sessionId}
• POST /themes/{id}/control/publish

1. Editing with AI
2. Visual themes
3. this API reference for the exact endpoint details

​

Response format

{
  "data": {
    "id": "abc123",
    "status": "COMPLETED"
  }
}

{
  "data": [
    { "id": "abc123" },
    { "id": "def456" }
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MTIzfQ",
    "has_more": true
  }
}

{
  "error": {
    "code": "VALIDATION_ERROR",
    "message": "Invalid email address",
    "details": [
      { "field": "email", "message": "must be a valid email" }
    ],
    "doc_url": "https://docs.shoppex.io/api-reference/errors"
  }
}

​

HTTP status codes

​

Request tracing

X-Request-Id: sync-run-42

​

Rate limiting

​

Idempotency

• Idempotency-Key
• X-Idempotency-Key

curl https://api.shoppex.io/dev/v1/payments \
  -X POST \
  -H "Authorization: Bearer shx_your_api_key" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: payment-create-123" \
  -d '{"title":"Order #1001","email":"[email protected]","value":49.99,"currency":"USD"}'

• created when the request created a new payment
• cached when Shoppex replayed the stored response
• processing when the same key is still in flight
• bypassed when idempotency was intentionally skipped

• the replay key is scoped to your authenticated key, the route, and the idempotency key
• Shoppex also checks the request body for the same method and path
• the replay window is currently 24 hours
• 5xx responses are not cached for replay
• a refusal that changed nothing is not cached either when the endpoint says so (for example the theme document save, and a stale or missing If-Match): the key stays free, so the corrected request may reuse it

• same key + same body -> cached response
• same key + different body -> validation error
• same key while the first request is still in flight -> processing
• key sent but Shoppex cannot check it right now -> 503 SERVICE_UNAVAILABLE, the request did not run; retry with the same key

​

Pagination

GET /products?limit=25

{
  "data": [
    { "uniqid": "prod_001", "title": "Product A" },
    { "uniqid": "prod_002", "title": "Product B" },
    // ... 23 more items
  ],
  "pagination": {
    "next_cursor": "eyJpZCI6MjUsImNyZWF0ZWRfYXQiOiIyMDI0LTAxLTAxIn0",
    "has_more": true
  }
}

GET /products?limit=25&cursor=eyJpZCI6MjUsImNyZWF0ZWRfYXQiOiIyMDI0LTAxLTAxIn0

{
  "data": [
    { "uniqid": "prod_099", "title": "Product Y" },
    { "uniqid": "prod_100", "title": "Product Z" }
  ],
  "pagination": {
    "next_cursor": null,
    "has_more": false
  }
}

async function fetchAllProducts(): Promise<Product[]> {
  const allProducts: Product[] = [];
  let cursor: string | null = null;

  do {
    const url = new URL('https://api.shoppex.io/dev/v1/products');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url.toString(), {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    const { data, pagination } = await response.json();

    allProducts.push(...data);
    cursor = pagination.next_cursor;
  } while (cursor);

  return allProducts;
}

def fetch_all_products():
    all_products = []
    cursor = None

    while True:
        params = {'limit': 100}
        if cursor:
            params['cursor'] = cursor

        response = requests.get(
            'https://api.shoppex.io/dev/v1/products',
            headers={'Authorization': f'Bearer {API_KEY}'},
            params=params
        )

        result = response.json()
        all_products.extend(result['data'])

        if not result['pagination']['has_more']:
            break

        cursor = result['pagination']['next_cursor']

    return all_products

async function* fetchProductsStream(): AsyncGenerator<Product> {
  let cursor: string | null = null;

  do {
    const url = new URL('https://api.shoppex.io/dev/v1/products');
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url.toString(), {
      headers: { 'Authorization': `Bearer ${API_KEY}` }
    });

    const { data, pagination } = await response.json();

    for (const product of data) {
      yield product;
    }

    cursor = pagination.next_cursor;
  } while (cursor);
}

// Usage
for await (const product of fetchProductsStream()) {
  console.log(product.title);
}

# Get completed invoices, paginated
GET /invoices?filters=status:COMPLETED&limit=50

# Continue with cursor
GET /invoices?filters=status:COMPLETED&limit=50&cursor=eyJ...

GET /orders?filters=status:COMPLETED,customer_email:[email protected]&sorts=-created_at
GET /customers?filters=city:Berlin&sorts=created_at

GET /webhooks/logs?page=2&limit=10

{
  "data": [
    { "uniqid": "log_001", "status": "success" }
  ],
  "pagination": {
    "total": 37,
    "page": 2,
    "limit": 10,
    "total_pages": 4,
    "has_more": true
  }
}

​

Pagination best practices

​

Filtering

# Filter by exact fields
GET /orders?filters=status:COMPLETED,customer_email:[email protected]

# Sort oldest first
GET /customers?sorts=created_at

# Sort newest first (default)
GET /invoices?sorts=-created_at

• GET /customers
• GET /orders
• GET /invoices

filters=status:COMPLETED,customer_email:[email protected]
sorts=created_at     # oldest first
sorts=-created_at    # newest first (default)

​

API changelog

​

Clarified — Coupon subscription fields on update (R3, 2026-10-26)

​

Changed — Affiliate payout approval (2.0, 2026-10-08)

​

Removed — Replacement Rules (2026-10-03)

​

Disputes pagination and amounts — Dashboard 9 release