Orders

Create, retrieve, and manage orders. Orders can be created by the AI agent during conversations or programmatically via the API.

Create an Order

POST/v1/orders

Parameter	Type	Description
customer Required	object	Customer details: name, phone, email, address.
items Required	array	Array of line items with product_id, quantity, and optional unit_price override.
channel Optional	string	Source channel: 'whatsapp', 'web', 'api'. Defaults to 'api'.
notes Optional	string	Internal notes about the order.
metadata Optional	object	Arbitrary key-value pairs.

curl

curl -X POST https://api.handl-ng.com/v1/orders \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "customer": {
      "name": "Amara Obi",
      "phone": "+2348012345678"
    },
    "items": [
      { "product_id": "prod_jollof", "quantity": 2 },
      { "product_id": "prod_chapman", "quantity": 1 }
    ],
    "notes": "Extra spicy"
  }'

javascript

const order = await fetch('https://api.handl-ng.com/v1/orders', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer sk_live_...',
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    customer: { name: 'Amara Obi', phone: '+2348012345678' },
    items: [
      { product_id: 'prod_jollof', quantity: 2 },
      { product_id: 'prod_chapman', quantity: 1 },
    ],
    notes: 'Extra spicy',
  }),
}).then(r => r.json());

console.log(order.id); // "ord_1042"

Response

json

{
  "id": "ord_1042",
  "object": "order",
  "status": "pending",
  "customer": {
    "name": "Amara Obi",
    "phone": "+2348012345678"
  },
  "items": [
    {
      "product_id": "prod_jollof",
      "name": "Jollof Rice (Large)",
      "quantity": 2,
      "unit_price": 3500,
      "subtotal": 7000
    },
    {
      "product_id": "prod_chapman",
      "name": "Chapman",
      "quantity": 1,
      "unit_price": 1500,
      "subtotal": 1500
    }
  ],
  "subtotal": 8500,
  "total": 8500,
  "currency": "NGN",
  "payment_status": "unpaid",
  "channel": "api",
  "notes": "Extra spicy",
  "created_at": "2025-06-15T14:30:00Z"
}

List Orders

GET/v1/orders

Parameter	Type	Description
status Optional	string	Filter: 'pending', 'confirmed', 'preparing', 'delivered', 'cancelled'.
payment_status Optional	string	Filter: 'unpaid', 'paid', 'refunded'.
created_after Optional	string	ISO 8601 timestamp. Only orders created after this time.
limit Optional	integer	Number of results (1–100). Default 25.
starting_after Optional	string	Cursor for pagination.

curl

curl "https://api.handl-ng.com/v1/orders?status=pending&limit=10" \
  -H "Authorization: Bearer sk_live_..."

Retrieve an Order

GET/v1/orders/:id

Update an Order

PATCH/v1/orders/:id

Update order status, notes, or metadata. To add/remove items, cancel the order and create a new one.

Parameter	Type	Description
status Optional	string	Transition to: 'confirmed', 'preparing', 'out_for_delivery', 'delivered', 'cancelled'.
notes Optional	string	Update internal notes.
metadata Optional	object	Merge new metadata. Existing keys are preserved unless overwritten.

curl

curl -X PATCH https://api.handl-ng.com/v1/orders/ord_1042 \
  -H "Authorization: Bearer sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{ "status": "confirmed" }'

ℹ️

When an order status changes, the customer is automatically notified through their original channel (if auto-notifications are enabled in Settings → AI Agent).

Order Statuses

pendingOrder created, awaiting confirmation

confirmedOrder accepted by the business

preparingOrder is being prepared/picked

out_for_deliveryOrder dispatched for delivery

deliveredOrder completed and delivered

cancelledOrder cancelled (terminal state)