Quick Start

This page is the generic Dev API quickstart.If your real goal is:

theme editing with AI -> start with Build and Customize a Theme with AI
theme automation endpoints -> read Editing Themes

This page is best when you want your first normal /dev/v1/* request.

If you prefer an official SDK instead of raw fetch or requests, start with SDKs & Libraries — we have packages for Node.js/Bun (@shoppexio/sdk), Python (shoppexio), and PHP (shoppexio/shoppex-php).

Get Your API Key

Log in to dashboard.shoppex.io
Go to Settings → API Keys
Click Generate New Key
Copy the key (starts with shx_)

API keys are shown only once. Store it securely before closing the dialog.

Make Your First Request

Let’s fetch your shop information to verify everything works:

curl https://api.shoppex.io/dev/v1/me \
  -H "Authorization: Bearer shx_your_api_key"

const response = await fetch('https://api.shoppex.io/dev/v1/me', {
  headers: {
    'Authorization': 'Bearer shx_your_api_key'
  }
});

const { data } = await response.json();
console.log(data.name); // Your shop name

import requests

response = requests.get(
    'https://api.shoppex.io/dev/v1/me',
    headers={'Authorization': 'Bearer shx_your_api_key'}
)

data = response.json()['data']
print(data['name'])  # Your shop name

import { ShoppexClient } from '@shoppexio/sdk';

const client = new ShoppexClient({
  apiKey: process.env.SHOPPEX_API_KEY!,
});

const me = await client.me.get();
console.log(me.data?.name);

from shoppexio import ShoppexClient

client = ShoppexClient(api_key='shx_your_api_key')
me = client.me.get()
print(me.data.name)

Response:

{
  "data": {
    "id": 12345,
    "name": "My Awesome Shop",
    "currency": "USD",
    "created_at": 1704067200
  }
}

Create a Payment

Now let’s create a payment link:

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

const response = await fetch('https://api.shoppex.io/dev/v1/payments', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer shx_your_api_key',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    title: 'Order #123',
    email: '[email protected]',
    value: 29.99,
    currency: 'USD'
  })
});

const { data } = await response.json();
console.log(data.url); // Checkout URL

import requests

response = requests.post(
    'https://api.shoppex.io/dev/v1/payments',
    headers={
        'Authorization': 'Bearer shx_your_api_key',
        'Content-Type': 'application/json'
    },
    json={
        'title': 'Order #123',
        'email': '[email protected]',
        'value': 29.99,
        'currency': 'USD'
    }
)

data = response.json()['data']
print(data['url'])  # Checkout URL

import { ShoppexClient } from '@shoppexio/sdk';

const client = new ShoppexClient({
  apiKey: process.env.SHOPPEX_API_KEY!,
});

const payment = await client.payments.create({
  title: 'Order #123',
  email: '[email protected]',
  value: 29.99,
  currency: 'USD',
});

console.log(payment.data?.url);

from shoppexio import ShoppexClient

client = ShoppexClient(api_key='shx_your_api_key')
payment = client.payments.create({
    'title': 'Order #123',
    'email': '[email protected]',
    'value': 29.99,
    'currency': 'USD',
})

print(payment.data.url)

Response:

{
  "data": {
    "uniqid": "abc123def456...",
    "url": "https://checkout.shoppex.io/invoice/abc123def456...",
    "url_branded": "https://checkout.shoppex.io/invoice/abc123def456...?shop=12345",
    "total": 29.99,
    "currency": "USD",
    "status": "PENDING",
    "created_at": 1704067200
  }
}

Redirect your customer to the url to complete payment.

POST /payments creates a generic developer payment — it does not trigger Shoppex product fulfillment. Use it when you want a payable invoice or hosted checkout URL. Use POST /orders instead when you need Shoppex product line items, delivery, and automatic fulfillment.

If you force gateway: "PANDABASE", the response can also include:

checkout_url: the direct Pandabase checkout session URL
session_id: the Pandabase session reference stored by Shoppex for automatic webhook reconciliation

If you want hosted checkout to open directly on a concrete crypto coin or network, use a merchant crypto provider together with crypto_gateway.Simple example:

{
  "gateway": "OXAPAY",
  "crypto_gateway": "TRON"
}

That returns a url like:

https://checkout.shoppex.io/invoice/abc123def456...?selected_gateway=TRON&auto_start_gateway=1&auto_start_crypto=1

Handle the Result

After payment, Shoppex sends a webhook to your server:

{
  "event": "order:paid",
  "data": {
    "uniqid": "inv_def456",
    "customer_email": "[email protected]",
    "total": 29.99,
    "currency": "USD"
  }
}

Webhooks Guide

Learn how to set up and verify webhooks

Dynamic Product Delivery

Implement the fulfillment callback for DYNAMIC products

You just made your first API call and created a payment. From here, most developers either hook up webhooks for automated fulfillment or explore the full endpoint reference.

Next Steps

Theme Guide

Use this if your actual goal is AI-assisted theme editing, not generic API onboarding.

Authentication

API key security best practices

SDKs & Libraries

Official JS, Python, and PHP SDKs for /dev/v1/*

Error Handling

Handle errors gracefully

Pagination

Navigate large result sets

Full API Reference

Explore all endpoints

Start Here

Concepts

Webhooks

Headless Commerce

Use Cases

Embed SDK

Webhooks Guide

Dynamic Product Delivery

Next Steps

Theme Guide

Authentication

SDKs & Libraries

Error Handling

Pagination

Full API Reference

Webhooks Guide

Dynamic Product Delivery

​Next Steps

Theme Guide

Authentication

SDKs & Libraries

Error Handling

Pagination

Full API Reference

Next Steps