Concepts & Terminology
Deep dive into Spwig's data models, relationships, and core concepts.
Product Data Model
Spwig uses a hierarchical product structure to support both simple products and complex products with multiple variants. Understanding this hierarchy is essential for catalog management.
┌─────────────────────────────────────────────────────────────────────┐
│ PRODUCT │
│ ├─ id, name, slug, description │
│ ├─ category, collections, tags │
│ ├─ status: draft | active | archived │
│ └─ seo_title, seo_description │
│ │
│ ┌──────────────────────┬──────────────────────┐ │
│ ▼ ▼ ▼ │
│ ┌─────────┐ ┌─────────┐ ┌─────────┐ │
│ │ VARIANT │ │ VARIANT │ │ VARIANT │ │
│ │ Blue/S │ │ Blue/M │ │ Red/S │ │
│ ├─────────┤ ├─────────┤ ├─────────┤ │
│ │ sku │ │ sku │ │ sku │ │
│ │ price │ │ price │ │ price │ │
│ │ weight │ │ weight │ │ weight │ │
│ │ barcode │ │ barcode │ │ barcode │ │
│ └────┬────┘ └────┬────┘ └────┬────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌────────────┐ ┌────────────┐ ┌────────────┐ │
│ │ STOCK_ITEM │ │ STOCK_ITEM │ │ STOCK_ITEM │ │
│ │ warehouse_a│ │ warehouse_a│ │ warehouse_a│ │
│ │ qty: 25 │ │ qty: 12 │ │ qty: 8 │ │
│ └────────────┘ └────────────┘ └────────────┘ │
│ ┌────────────┐ ┌────────────┐ │
│ │ STOCK_ITEM │ │ STOCK_ITEM │ │
│ │ warehouse_b│ │ warehouse_b│ │
│ │ qty: 10 │ │ qty: 5 │ │
│ └────────────┘ └────────────┘ │
└─────────────────────────────────────────────────────────────────────┘
Key Relationships
| Relationship | Type | Description |
|---|---|---|
| Product → Variant | One-to-Many | A product can have multiple variants. Simple products have exactly one variant. |
| Variant → StockItem | One-to-Many | Each variant has stock tracked per warehouse/location. |
| Product → Category | Many-to-One | Products belong to a single primary category. |
| Product → Collection | Many-to-Many | Products can appear in multiple curated collections. |
| Variant → Option Values | Many-to-Many | Variants are defined by combinations of option values (Color: Blue, Size: M). |
API Tip: When fetching products, use ?expand=variants,variants.stock_items to include nested data in a single request.
Order Lifecycle
Orders progress through a defined state machine. Understanding these states helps you build integrations that respond appropriately to order changes.
Order Status Flow
| Status | Description | Triggers |
|---|---|---|
pending |
Order created, awaiting payment confirmation | Checkout completed |
processing |
Payment received, preparing for fulfillment | Payment webhook received |
shipped |
All items dispatched to customer | Shipment created with tracking |
delivered |
Customer received the order | Carrier delivery confirmation |
completed |
Order finalized (return window closed) | Auto-complete after configured days |
cancelled |
Order cancelled, payment refunded | Admin action or customer request |
Payment Status (Separate from Order Status)
Cart → Checkout → Order Flow
The customer purchase journey involves three distinct stages, each with its own API resources:
┌──────────────────────────────────────────────────────────────────────┐
│ CUSTOMER JOURNEY │
├──────────────────────────────────────────────────────────────────────┤
│ │
│ 1. CART 2. CHECKOUT 3. ORDER │
│ ───────── ────────── ───────── │
│ ┌──────────────┐ ┌──────────────┐ ┌────────────┐ │
│ │ Cart Items │ │ Session Data │ │ Finalized │ │
│ │ - variant_id │ ──────► │ - cart_id │ ──────► │ - customer │ │
│ │ - quantity │ convert │ - email │ payment │ - items │ │
│ │ - metadata │ │ - addresses │ confirm │ - payments │ │
│ └──────────────┘ │ - shipping │ │ - shipments│ │
│ │ - payment │ └────────────┘ │
│ Mutable: └──────────────┘ │
│ - Add/remove items Immutable: │
│ - Update quantities Locks pricing - Snapshot of │
│ - Apply vouchers and shipping prices at │
│ rates at time purchase time│
│ │
└──────────────────────────────────────────────────────────────────────┘
API Endpoints for Each Stage
| Stage | Endpoint | Key Operations |
|---|---|---|
| Cart | /api/v1/cart/ |
Create cart, add/remove items, apply vouchers |
| Checkout | /api/v1/checkout/ |
Create session, set addresses, select shipping/payment |
| Order | /api/v1/orders/ |
Read order details, update fulfillment, process refunds |
Multi-Currency & Exchange Rates
Spwig supports multi-currency storefronts with automatic currency conversion. Exchange rates are captured at the time of order creation to ensure pricing accuracy.
How Currency Conversion Works
- Store Base Currency: All prices are stored in your store's base currency (e.g., USD).
- Display Currency: When customers browse, prices are converted using current exchange rates.
- Order Snapshot: At checkout, the exchange rate is captured and stored with the order.
- Reporting: Orders can be reported in both the display currency and base currency.
┌─────────────────────────────────────────────────────────────────────┐
│ MULTI-CURRENCY FLOW │
├─────────────────────────────────────────────────────────────────────┤
│ │
│ Product Price (Base) Customer View Order │
│ ────────────────── ───────────── ───── │
│ │
│ ┌─────────────┐ Exchange ┌─────────────┐ Snapshot │
│ │ $99.00 USD │ ──────────► │ €91.08 EUR │ ────────────► │
│ │ (stored) │ Rate: │ (displayed) │ │
│ └─────────────┘ 0.92 └─────────────┘ │
│ │
│ ┌────────────────┐│
│ │ Order #1234 ││
│ Exchange rates updated via │ ││
│ configured provider: │ display_total: ││
│ - Open Exchange Rates │ €91.08 EUR ││
│ - Fixer.io │ ││
│ - CurrencyLayer │ base_total: ││
│ - ExchangeRatesAPI │ $99.00 USD ││
│ │ ││
│ │ exchange_rate: ││
│ │ 0.92 ││
│ └────────────────┘│
│ │
└─────────────────────────────────────────────────────────────────────┘
Currency Fields in API Responses
{
"price": {
"amount": "99.00",
"currency": "USD"
},
"converted_price": {
"amount": "91.08",
"currency": "EUR",
"exchange_rate": "0.92"
}
}Inventory & Stock Management
Spwig supports multi-warehouse inventory tracking with stock allocations and reservations during checkout.
Stock States
| Field | Description |
|---|---|
quantity_on_hand |
Physical stock in the warehouse |
quantity_allocated |
Reserved for pending orders (not yet shipped) |
quantity_available |
on_hand - allocated = available for new orders |
Allocation Flow
- Checkout Created: Stock is allocated (reserved) for items in the checkout.
- Order Confirmed: Allocation remains until fulfillment.
- Shipment Created: Allocated stock is decremented from on_hand.
- Order Cancelled: Allocation is released back to available.
Component & Plugin Lifecycle
Spwig uses a component-based architecture for themes, plugins, and integrations. Components are installed from Spwig's update server and follow a defined lifecycle.
Component Types
| Type | Description | Examples |
|---|---|---|
| Theme | Controls storefront appearance | Default Theme, Minimal, Boutique |
| Payment Provider | Payment gateway integration | Stripe, PayPal, Square |
| Shipping Provider | Carrier rate calculation & tracking | FedEx, UPS, USPS |
| Email Provider | Transactional email delivery | SendGrid, Mailgun, SMTP |
| Exchange Rate Provider | Currency conversion rates | Open Exchange Rates, Fixer |
Update Channels
Components are delivered through update channels with different stability levels:
- stable — Production-ready releases (default)
- beta — Pre-release testing
- dev — Development builds
- security — Critical security patches (auto-installed)
Localization & Fallback Chains
Spwig supports 200+ languages with intelligent fallback chains for missing translations.
Language Fallback Chain
When content isn't available in the requested language, Spwig follows this fallback order:
- Requested language: e.g.,
fr-CA(French Canadian) - Base language: e.g.,
fr(French) - Store default language: e.g.,
en(English)
Translation Coverage
Different content types have different translation requirements:
| Content Type | Translation Method |
|---|---|
| Product names, descriptions | Merchant-provided or AI translation service |
| Category names | Merchant-provided |
| UI strings (buttons, labels) | Theme translation files |
| Email templates | Per-language template variants |
| SEO metadata | Merchant-provided or AI translation service |
API Header: Use Accept-Language: fr-CA to request content in a specific language. The response will use the fallback chain if the exact locale isn't available.
Next Steps: See Workflows for integration patterns, or explore the API Reference.