Spwig API Documentation

Build powerful e-commerce integrations with our comprehensive REST API and real-time webhooks.

What is Spwig?

Spwig is a self-hosted, single-tenant e-commerce platform designed for merchants who want full control over their online store. Unlike SaaS solutions, each Spwig installation runs on your own infrastructure, giving you complete data ownership, unlimited customization, and no recurring platform fees.

The Spwig API enables you to build custom headless storefronts, mobile applications, POS integrations, and automated workflows. Whether you're syncing inventory with an ERP, building a custom checkout experience, or integrating with third-party fulfillment services, the API provides everything you need.

Self-Hosted

Multi-Language

Multi-Currency

Theme System

Plugin Architecture

Your Data, Your Rules

Getting Started →

Install Spwig on your server with a single command. System requirements, installation options, and first steps for your new store.

API Reference (ReDoc)

Clean, readable API documentation with three-panel design. Perfect for exploring endpoints and schemas.

API Explorer (Swagger)

Interactive API explorer. Try endpoints directly in your browser with live request/response testing.

Webhooks

Real-time event notifications for orders, payments, shipments, and more. Includes payload schemas and security guidance.

Quick Start

Get started with the Spwig API in minutes. Choose your integration path:

Headless Storefront

Build a custom frontend with React, Vue, or any framework. Fetch products, manage cart, and process checkout.

Admin Integration

Sync inventory with ERP, automate order fulfillment, or build custom admin tools.

Webhook Integration

React to events in real-time—new orders, payment updates, inventory changes.

Get Your API Key

Generate an API key from your Spwig admin panel at Settings > API > API Keys. Store it securely—it grants full access to your store data.

Make Your First Request

Fetch your product catalog with your API key:

// Using fetch (browser or Node 18+)
const response = await fetch('https://your-store.com/api/v1/products/', {
  headers: {
    'Authorization': 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
});
const { results: products } = await response.json();
console.log(`Found ${products.length} products`);

import requests

response = requests.get(
    'https://your-store.com/api/v1/products/',
    headers={'Authorization': 'Token YOUR_API_KEY'}
)
products = response.json()['results']
print(f"Found {len(products)} products")

curl -X GET "https://your-store.com/api/v1/products/" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json"

Create a Cart and Add Items

For headless storefronts, manage shopping carts programmatically:

// Create a cart (or use session-based cart)
const cart = await fetch('https://your-store.com/api/v1/cart/', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  }
}).then(r => r.json());

// Add a product variant to cart
await fetch(`https://your-store.com/api/v1/cart/${cart.id}/items/`, {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    variant_id: 'var_abc123',
    quantity: 2
  })
});

import requests

headers = {'Authorization': 'Token YOUR_API_KEY'}
base_url = 'https://your-store.com/api/v1'

# Create a cart
cart = requests.post(f'{base_url}/cart/', headers=headers).json()

# Add item to cart
requests.post(
    f'{base_url}/cart/{cart["id"]}/items/',
    headers=headers,
    json={'variant_id': 'var_abc123', 'quantity': 2}
)

# Create cart
curl -X POST "https://your-store.com/api/v1/cart/" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json"

# Add item (replace CART_ID)
curl -X POST "https://your-store.com/api/v1/cart/CART_ID/items/" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"variant_id": "var_abc123", "quantity": 2}'

Initiate Checkout

Convert the cart to a checkout session and collect customer details:

// Create checkout session from cart
const checkout = await fetch('https://your-store.com/api/v1/checkout/', {
  method: 'POST',
  headers: {
    'Authorization': 'Token YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    cart_id: cart.id,
    email: '[email protected]',
    shipping_address: {
      first_name: 'John',
      last_name: 'Doe',
      address_line_1: '123 Main St',
      city: 'New York',
      postal_code: '10001',
      country: 'US'
    }
  })
}).then(r => r.json());

// checkout.payment_url - redirect customer to complete payment

checkout = requests.post(
    f'{base_url}/checkout/',
    headers=headers,
    json={
        'cart_id': cart['id'],
        'email': '[email protected]',
        'shipping_address': {
            'first_name': 'John',
            'last_name': 'Doe',
            'address_line_1': '123 Main St',
            'city': 'New York',
            'postal_code': '10001',
            'country': 'US'
        }
    }
).json()

# Redirect customer to checkout['payment_url']

curl -X POST "https://your-store.com/api/v1/checkout/" \
  -H "Authorization: Token YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cart_id": "CART_ID",
    "email": "[email protected]",
    "shipping_address": {
      "first_name": "John",
      "last_name": "Doe",
      "address_line_1": "123 Main St",
      "city": "New York",
      "postal_code": "10001",
      "country": "US"
    }
  }'

Handle Order Webhooks

Receive real-time notifications when orders are placed, paid, or shipped:

// Express.js webhook handler
app.post('/webhooks/spwig', express.json(), (req, res) => {
  const event = req.body;

  switch (event.type) {
    case 'order.created':
      console.log('New order:', event.data.order_number);
      // Sync to ERP, send notification, etc.
      break;
    case 'order.paid':
      console.log('Payment received:', event.data.order_number);
      // Start fulfillment process
      break;
    case 'shipment.created':
      console.log('Shipped:', event.data.tracking_number);
      // Send shipping notification to customer
      break;
  }

  res.status(200).send('OK');
});

# Flask webhook handler
from flask import Flask, request

app = Flask(__name__)

@app.route('/webhooks/spwig', methods=['POST'])
def handle_webhook():
    event = request.json

    if event['type'] == 'order.created':
        print(f"New order: {event['data']['order_number']}")
        # Sync to ERP, send notification, etc.
    elif event['type'] == 'order.paid':
        print(f"Payment received: {event['data']['order_number']}")
        # Start fulfillment process
    elif event['type'] == 'shipment.created':
        print(f"Shipped: {event['data']['tracking_number']}")
        # Send shipping notification

    return 'OK', 200

Configure webhook endpoints in Settings > Webhooks. See Webhooks documentation for signature verification and event types.

SDKs & Tools

Theme SDK: Build custom storefronts with our VS Code Extension or GitHub
Headless SDK: Coming soon — for now, use the OpenAPI spec with tools like openapi-generator to generate type-safe clients
OpenAPI Spec: Machine-readable API definition at /latest/openapi.json

Resources

Additional documentation and tools to help you build.

Authentication

API keys, token auth, and session handling

Errors & Rate Limits

Error codes, handling, and rate limiting

Webhooks

Real-time events and signature verification

Concepts

Core objects: products, orders, customers

Machine-readable API specification:

/latest/openapi.json