Orders

Endpoints

Create order - POST /orders

The most powerful endpoint in the API. A single call creates a complete sale with all downstream effects handled automatically.

What happens automatically:

• Finds or creates the customer by email or phone
• Validates all product IDs belong to your business
• Creates a sales record with a unique sale number (S-0001)
• Creates sale_items for each line item
• Deducts stock from the specified (or default) warehouse
• Records stock movements for full audit trail
• Updates customer's total_spent, total_orders, last_purchase_date
• Awards 1 loyalty point per currency unit (floor)
• Creates invoices + invoice_items if send_invoice: true
• Creates a transactions income record for your finance module
• Dispatches the sale.completed webhook

Request body

items[] object

customer object

Full request example

curl -X POST \
  https://qatxonlxvtgxvqjgfxpl.supabase.co/functions/v1/api/orders \
  -H "Authorization: Bearer do_live_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Sarah Johnson",
      "email": "[email protected]",
      "phone": "+1-555-0100"
    },
    "items": [
      {
        "product_id": "a1b2c3d4-...",
        "quantity": 3,
        "discount": 5.00
      },
      {
        "product_id": "e5f6g7h8-...",
        "quantity": 1,
        "price": 49.99
      }
    ],
    "payment_method": "card",
    "tax_amount": 12.50,
    "shipping_amount": 0,
    "send_invoice": true,
    "notes": "Rush order"
  }'

const order = await client.orders.create({
  customer: {
    name: 'Sarah Johnson',
    email: '[email protected]',
    phone: '+1-555-0100',
  },
  items: [
    { product_id: 'a1b2c3d4-...', quantity: 3, discount: 5.00 },
    { product_id: 'e5f6g7h8-...', quantity: 1, price: 49.99 },
  ],
  payment_method: 'card',
  tax_amount: 12.50,
  send_invoice: true,
  notes: 'Rush order',
})

order = client.orders.create(
    items=[
        {'product_id': 'a1b2c3d4-...', 'quantity': 3, 'discount': 5.00},
        {'product_id': 'e5f6g7h8-...', 'quantity': 1, 'price': 49.99},
    ],
    customer={
        'name': 'Sarah Johnson',
        'email': '[email protected]',
    },
    payment_method='card',
    tax_amount=12.50,
    send_invoice=True,
    notes='Rush order',
)

$order = $client->orders->create(
    [
        ['product_id' => 'a1b2c3d4-...', 'quantity' => 3, 'discount' => 5.00],
        ['product_id' => 'e5f6g7h8-...', 'quantity' => 1, 'price' => 49.99],
    ],
    [
        'customer' => ['name' => 'Sarah Johnson', 'email' => '[email protected]'],
        'payment_method' => 'card',
        'tax_amount' => 12.50,
        'send_invoice' => true,
    ]
);

Response

{
  "success": true,
  "data": {
    "order_id": "9f3a8c12-...",
    "order_number": "S-0042",
    "status": "completed",
    "payment_status": "paid",
    "payment_method": "card",
    "customer_id": "7d2e1f09-...",
    "subtotal": 194.97,
    "tax_amount": 12.50,
    "shipping_amount": 0,
    "discount_amount": 5.00,
    "total": 202.47,
    "loyalty_points_earned": 202,
    "loyalty_transaction_id": "b4c5d6e7-...",
    "invoice_id": "f8g9h0i1-...",
    "invoice_number": "INV-0018",
    "items": [
      {
        "product_id": "a1b2c3d4-...",
        "product_name": "Widget Pro",
        "sku": "WDGPRO-1234",
        "quantity": 3,
        "unit_price": 49.99,
        "discount": 5.00,
        "total": 144.97
      }
    ],
    "created_at": "2026-06-02T14:30:00.000Z"
  }
}

List orders - GET /orders