API Overview

Core concepts, architecture, and standards for the Spwig e-commerce API.

What is Spwig?

Spwig is a self-hosted, single-tenant e-commerce platform built for merchants who need full control over their online store. Unlike SaaS platforms where you share infrastructure with other stores, each Spwig installation runs independently on your own servers.

Key Differentiators: Self-hosted (your infrastructure, your data), single-tenant (one installation = one store), extensible via themes and plugins, no recurring platform fees.

The Spwig API follows REST conventions and returns JSON responses. It enables you to:

Build custom headless storefronts (React, Vue, mobile apps)
Integrate with ERP, PIM, and fulfillment systems
Automate inventory management and order processing
Create custom admin dashboards and reporting tools
Sync data with third-party marketplaces

Architecture

Spwig follows a traditional monolithic architecture with a clear separation between the admin backend, the customer-facing storefront, and the API layer. All three access the same database and business logic.

┌─────────────────────────────────────────────────────────────────┐
│                        Your Infrastructure                       │
├─────────────────────────────────────────────────────────────────┤
│                                                                  │
│   ┌──────────────┐    ┌──────────────┐    ┌──────────────┐     │
│   │   Custom     │    │   Mobile     │    │   Third      │     │
│   │   Frontend   │    │   App        │    │   Party      │     │
│   └──────┬───────┘    └──────┬───────┘    └──────┬───────┘     │
│          │                   │                   │              │
│          └───────────────────┼───────────────────┘              │
│                              │                                   │
│                              ▼                                   │
│                    ┌─────────────────┐                          │
│                    │   Spwig API     │◄────── Webhooks          │
│                    │   /api/v1/      │                          │
│                    └────────┬────────┘                          │
│                             │                                    │
│          ┌──────────────────┼──────────────────┐                │
│          ▼                  ▼                  ▼                │
│   ┌────────────┐    ┌────────────┐    ┌────────────┐           │
│   │   Admin    │    │ Storefront │    │   Celery   │           │
│   │   Panel    │    │  (Themes)  │    │  Workers   │           │
│   └────────────┘    └────────────┘    └────────────┘           │
│          │                  │                  │                 │
│          └──────────────────┼──────────────────┘                │
│                             ▼                                    │
│                    ┌─────────────────┐                          │
│                    │    Database     │                          │
│                    │   (PostgreSQL)  │                          │
│                    └─────────────────┘                          │
│                                                                  │
└─────────────────────────────────────────────────────────────────┘

Core Concepts

Understanding these core objects will help you navigate the API effectively:

Store

The top-level entity representing your e-commerce business. Contains settings for currency, tax, shipping, and branding.

Product

An item for sale. Products have a name, description, images, and pricing. Can have multiple variants.

Variant

A specific version of a product (e.g., "Blue / Large"). Each variant has its own SKU, price, and inventory.

Stock Location

A physical location where inventory is stored. Variants track stock levels per location.

Cart

A temporary collection of items a customer intends to purchase. Becomes an order at checkout.

Order

A completed purchase. Contains line items, shipping address, payment status, and fulfillment state.

Customer

A registered user who can place orders, save addresses, and track order history.

Payment

A financial transaction associated with an order. Supports multiple payment methods per order.

Shipment

A package sent to fulfill part or all of an order. Contains tracking info and line items.

Refund

A return of funds to a customer. Can be full or partial, and may involve inventory return.

Theme

A template package that controls storefront appearance. Installed via the component system.

Plugin

An extension that adds functionality: payment gateways, shipping providers, marketing tools, etc.

Order Lifecycle

Orders progress through these states:

Pending — Order created, awaiting payment
Processing — Payment received, preparing for shipment
Shipped — Items dispatched to customer
Delivered — Customer received the order
Completed — Order finalized (after return window)
Cancelled — Order cancelled before fulfillment

API Standards

Base URL

All API requests are made to your store's domain:

https://your-store.com/api/v1/

HTTP Methods

Method	Usage
`GET`	Retrieve resources (list or detail)
`POST`	Create new resources
`PUT`	Replace a resource entirely
`PATCH`	Partially update a resource
`DELETE`	Remove a resource

Response Format

All responses return JSON. Successful single-object responses:

{
  "id": 123,
  "name": "Example Product",
  "created_at": "2024-01-15T10:30:00Z",
  ...
}

List responses include pagination metadata:

{
  "count": 142,
  "next": "https://your-store.com/api/v1/products/?page=2",
  "previous": null,
  "results": [...]
}

Pagination

List endpoints return 20 items per page by default. Use these query parameters:

Parameter	Description	Default
`page`	Page number (1-indexed)	1
`page_size`	Items per page (max 100)	20

Example request for page 3 with 50 items:

GET /api/v1/products/?page=3&page_size=50

Filtering & Sorting

Most list endpoints support filtering via query parameters:

# Filter products by category
GET /api/v1/products/?category=electronics

# Filter orders by status
GET /api/v1/orders/?status=processing

# Filter by date range
GET /api/v1/orders/?created_at__gte=2024-01-01&created_at__lte=2024-01-31

# Sort by field (prefix with - for descending)
GET /api/v1/products/?ordering=-created_at

# Search by text
GET /api/v1/products/?search=wireless+headphones

Localization

Multi-Language Support

Set the Accept-Language header to receive localized content:

Accept-Language: fr-FR

Translatable fields (product names, descriptions) will return in the requested language if available.

Multi-Currency

Price fields include currency information:

{
  "price": {
    "amount": "99.99",
    "currency": "USD"
  },
  "compare_at_price": {
    "amount": "129.99",
    "currency": "USD"
  }
}

Currency conversion is handled automatically based on store settings and exchange rates.

Next Steps: Learn about Authentication, understand Error Handling, or dive into the API Reference.