Quick start

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

theme editing with AI -> start with Editing with AI
theme automation endpoints -> read Visual 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. Shoppex has 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

This request fetches your shop information to verify that 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 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": "customer@example.com",
    "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: 'customer@example.com',
    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': 'customer@example.com',
        '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: 'customer@example.com',
  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': 'customer@example.com',
    '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 Shoppex stores to match the webhook to this payment automatically

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": "customer@example.com",
    "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 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 at API introduction.

Start here

Invoices and payments

Webhooks

Headless commerce

Storefront SDK

Checkout embeds

Integrations

Resellers

Email marketing

Tutorials

Webhooks Guide

Dynamic Product Delivery