Quickstart

A complete retail flow: create a category, define a variant axis, add a product (with variants in TypeScript), place an order, and advance it through fulfillment. The Python flow prices and stocks products directly and identifies order items by product_id and sku.

TypeScript

import { WiilClient } from 'wiil-js';
import { OrderStatus, VariantAxisType, PreferredContactMethod } from 'wiil-core-js';

async function setupStore() {
  const client = new WiilClient({ apiKey: process.env.WIIL_API_KEY! });

  // 1. Create customer
  const customer = await client.customers.create({
    phone_number: '+15551234567',
    firstname: 'John',
    lastname: 'Doe',
    preferred_language: 'en',
    preferred_contact_method: PreferredContactMethod.EMAIL,
    isValidatedNames: false,
  });

  // 2. Create categories
  const computers = await client.products.createCategory({ name: 'Computers', description: 'Laptops and desktops', isDefault: false });
  const accessories = await client.products.createCategory({ name: 'Accessories', description: 'Peripherals', isDefault: false });

  // 3. Define a reusable variant axis
  const colorAxis = await client.productVariantAxes.create({
    name: 'Color',
    type: VariantAxisType.SWATCH,
    values: [
      { id: 'black', label: 'Black', swatchColor: '#000000', sortOrder: 0 },
      { id: 'silver', label: 'Silver', swatchColor: '#C0C0C0', sortOrder: 1 },
    ],
    isActive: true,
  });

  // 4. Create products with variants
  const laptop = await client.products.create({
    categoryId: computers.id,
    name: 'Pro Laptop 15"',
    description: '15-inch laptop with 16GB RAM',
    price: 1299.99,
    sku: 'LT-PRO-15',
    trackInventory: true,
    isActive: true,
    isAlcoholic: false,
    variants: [
      { axisValues: { Color: 'Black' }, price: 1299.99, isDefault: true, isActive: true },
      { axisValues: { Color: 'Silver' }, price: 1349.99, isDefault: false, isActive: true },
    ],
  });

  const mouse = await client.products.create({
    categoryId: accessories.id,
    name: 'Wireless Mouse',
    description: 'Ergonomic wireless mouse',
    price: 29.99,
    sku: 'MS-WL',
    trackInventory: true,
    isActive: true,
    isAlcoholic: false,
    variants: [{ axisValues: {}, price: 29.99, isDefault: true, isActive: true }],
  });

  // 5. Create an order
  const order = await client.productOrders.create({
    customerId: customer.id,
    orderDate: Date.now(),
    items: [
      { productId: laptop.id, variantId: laptop.variants[0].id, itemName: 'Pro Laptop 15" (Black)', quantity: 1, unitPrice: 1299.99, totalPrice: 1299.99 },
      { productId: mouse.id, variantId: mouse.variants[0].id, itemName: 'Wireless Mouse', quantity: 2, unitPrice: 29.99, totalPrice: 59.98 },
    ],
    pricing: { subtotal: 1359.97, total: 1359.97 },
  });

  // 6. Advance the order through fulfillment
  await client.productOrders.updateStatus(order.id, { id: order.id, status: OrderStatus.CONFIRMED });
  await client.productOrders.updateStatus(order.id, { id: order.id, status: OrderStatus.PREPARING });

  return { customer, categories: [computers, accessories], products: [laptop, mouse], order };
}

setupStore().catch(console.error);

Python

from time import time

from wiil import WiilClient
from wiil.models.business_mgt import (
    CreateBusinessProduct,
    CreateProductCategory,
    CreateProductOrder,
    OrderAddress,
    OrderPricing,
    ProductOrderItemBase,
)

client = WiilClient(api_key="your-api-key")
now_ms = int(time() * 1000)

# 1. Create a category
category = client.products.create_category(
    CreateProductCategory(name="Electronics", description="Devices and accessories", display_order=1)
)

# 2. Create a product (priced and stocked directly)
product = client.products.create(
    CreateBusinessProduct(
        name="Wireless Mouse",
        description="Ergonomic wireless mouse with 6 buttons",
        price=29.99,
        sku="WM-2024-BLK",
        barcode="123456789012",
        category_id=category.id,
        brand="TechBrand",
        track_inventory=True,
        stock_quantity=150,
        low_stock_threshold=20,
        weight=0.25,
        is_active=True,
    )
)

# 3. Place an order (Python order items use product_id + sku)
order = client.product_orders.create(
    CreateProductOrder(
        items=[
            ProductOrderItemBase(
                product_id=product.id,
                item_name=product.name,
                sku=product.sku,
                quantity=2,
                unit_price=product.price,
                total_price=product.price * 2,
            )
        ],
        customer_id="cust_123",
        pricing=OrderPricing(subtotal=59.98, tax=4.80, shipping_amount=9.99, total=74.77, currency="USD"),
        order_date=now_ms,
        shipping_address=OrderAddress(
            street="123 Main St", city="New York", state="NY", postal_code="10001", country="US"
        ),
        source="web",
    )
)

# 4. Read the order back
order_details = client.product_orders.get(order.id)

print("Created product:", product.id)
print("Order:", order.id, "->", order_details.status)

Next steps

• Categories — hierarchy, attributes, and default axes
• Products — pricing, inventory, shipping, and tax
• Variants & axes — the axis-driven variation system
• Orders — order fields, pricing, and the fulfillment lifecycle