API Reference

Orders

Create and manage customer orders with product items, track order status, and handle fulfillment.

The Order object

{
  "id": 42,
  "contact_id": 15,
  "customer_name": "Ahmed Al-Rashid",
  "customer_phone": "+966501234567",
  "customer_email": "ahmed@example.com",
  "status": "pending",
  "subtotal": 450.00,
  "total": 450.00,
  "currency": "SAR",
  "shipping_address": "123 King Fahd Road, Riyadh",
  "notes": "Please call before delivery",
  "created_by": "api",
  "items": [
    {
      "id": 101,
      "product_id": 5,
      "product_name": "Premium T-Shirt",
      "product_sku": "TSH-001",
      "quantity": 3,
      "unit_price": 150.00,
      "total_price": 450.00
    }
  ],
  "created_at": "2026-04-05T10:30:00.000000Z",
  "updated_at": "2026-04-05T10:30:00.000000Z"
}

Field	Type	Description
`id`	integer	Unique order ID
`contact_id`	integer\|null	Associated contact ID
`customer_name`	string	Customer's name
`customer_phone`	string\|null	Customer's phone number
`customer_email`	string\|null	Customer's email address
`status`	string	Order status (see below)
`subtotal`	number	Order subtotal before any adjustments
`total`	number	Final order total
`currency`	string	Currency code (e.g., `SAR`, `USD`)
`shipping_address`	string\|null	Delivery address
`notes`	string\|null	Optional notes
`created_by`	string	Source: `manual`, `ai_agent`, `api`, `web_chat`
`items`	array	Array of order line items
`created_at`	string	ISO 8601 creation timestamp
`updated_at`	string	ISO 8601 last update timestamp

Order statuses

Status	Description
`pending`	Order received, awaiting confirmation
`confirmed`	Order confirmed by merchant
`processing`	Order being prepared
`shipped`	Order dispatched for delivery
`delivered`	Order successfully delivered
`cancelled`	Order cancelled

List orders

GET /api/v1/orders

Query parameters

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Results per page (max 100)
`status`	string	Filter by status
`contact_id`	integer	Filter by contact
`created_by`	string	Filter by source: `manual`, `ai_agent`, `api`, `web_chat`
`date_from`	string	Filter orders from date (YYYY-MM-DD)
`date_to`	string	Filter orders to date (YYYY-MM-DD)

Example

curl "https://dashboard.skylightchat.com/api/v1/orders?status=pending&per_page=10" \
  -H "Authorization: Bearer sk_live_••••••••••••"

Response

{
  "success": true,
  "data": [
    {
      "id": 42,
      "customer_name": "Ahmed Al-Rashid",
      "status": "pending",
      "total": 450.00,
      "currency": "SAR",
      "items": [...],
      "created_at": "2026-04-05T10:30:00.000000Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 10,
    "total": 25
  },
  "message": "Orders retrieved successfully."
}

Create an order

POST /api/v1/orders

Request body

{
  "contact_id": 15,
  "customer_name": "Ahmed Al-Rashid",
  "customer_phone": "+966501234567",
  "shipping_address": "123 King Fahd Road, Riyadh",
  "items": [
    { "product_id": 5, "quantity": 3 },
    { "product_id": 8, "quantity": 1 }
  ],
  "notes": "Please call before delivery"
}

Field	Required	Description
`items`	✓	Array of products with `product_id` and `quantity`
`customer_name`	✓*	Customer name (*optional if `contact_id` provided)
`contact_id`	—	Link order to existing contact
`customer_phone`	—	Customer phone number
`customer_email`	—	Customer email address
`shipping_address`	—	Delivery address
`notes`	—	Order notes

Example

curl -X POST https://dashboard.skylightchat.com/api/v1/orders \
  -H "Authorization: Bearer sk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{
    "contact_id": 15,
    "items": [
      { "product_id": 5, "quantity": 3 }
    ],
    "shipping_address": "123 King Fahd Road, Riyadh"
  }'

Response `201 Created`

{
  "success": true,
  "data": {
    "id": 42,
    "contact_id": 15,
    "customer_name": "Ahmed Al-Rashid",
    "status": "pending",
    "total": 450.00,
    "currency": "SAR",
    "items": [
      {
        "id": 101,
        "product_id": 5,
        "product_name": "Premium T-Shirt",
        "quantity": 3,
        "unit_price": 150.00,
        "total_price": 450.00
      }
    ],
    "created_at": "2026-04-05T10:30:00.000000Z"
  },
  "message": "Order created successfully."
}

Duplicate Prevention: The API includes built-in duplicate detection. If an identical order (same contact + same products + same quantities) is created within 5 minutes, the existing order is returned instead of creating a duplicate. The response will include "is_duplicate": true.

Get an order

GET /api/v1/orders/{id}

Example

curl "https://dashboard.skylightchat.com/api/v1/orders/42" \
  -H "Authorization: Bearer sk_live_••••••••••••"

Update an order

PUT /api/v1/orders/{id}

Update order status, notes, or shipping address.

{
  "status": "confirmed",
  "notes": "Updated delivery instructions"
}

Field	Description
`status`	New status (valid transitions only)
`notes`	Order notes
`shipping_address`	Delivery address
`cancellation_reason`	Required when changing status to `cancelled`

Valid status transitions

From	Can transition to
`pending`	`confirmed`, `cancelled`
`confirmed`	`processing`, `cancelled`
`processing`	`shipped`, `cancelled`
`shipped`	`delivered`
`delivered`	—
`cancelled`	—

Example

curl -X PUT https://dashboard.skylightchat.com/api/v1/orders/42 \
  -H "Authorization: Bearer sk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "status": "confirmed" }'

Cancel an order

POST /api/v1/orders/{id}/cancel

Cancel a pending or confirmed order. Stock is automatically restored.

{
  "reason": "Customer requested cancellation"
}

Example

curl -X POST https://dashboard.skylightchat.com/api/v1/orders/42/cancel \
  -H "Authorization: Bearer sk_live_••••••••••••" \
  -H "Content-Type: application/json" \
  -d '{ "reason": "Customer requested cancellation" }'

Response

{
  "success": true,
  "data": { "id": 42, "status": "cancelled" },
  "message": "Order cancelled successfully."
}

Update order items

PUT /api/v1/orders/{id}/items

Replace all items in a pending order. Stock adjustments are handled automatically.

{
  "items": [
    { "product_id": 5, "quantity": 2 },
    { "product_id": 12, "quantity": 1 }
  ]
}

This endpoint is only available for orders with pending status. Once an order is confirmed or further along, items cannot be modified.

List products

GET /api/v1/products

Retrieve available products that can be ordered.

Query parameters

Parameter	Type	Description
`page`	integer	Page number
`per_page`	integer	Results per page (max 100)
`search`	string	Search by name, SKU, or category
`category`	string	Filter by category

Example

curl "https://dashboard.skylightchat.com/api/v1/products?search=shirt" \
  -H "Authorization: Bearer sk_live_••••••••••••"

Response

{
  "success": true,
  "data": [
    {
      "id": 5,
      "name": "Premium T-Shirt",
      "description": "100% cotton premium quality t-shirt",
      "sku": "TSH-001",
      "category": "Clothing",
      "price": 150.00,
      "currency": "SAR",
      "stock_quantity": 50,
      "in_stock": true
    }
  ],
  "meta": {
    "current_page": 1,
    "per_page": 25,
    "total": 12
  },
  "message": "Products retrieved successfully."
}

Webhooks

Orders trigger webhook events that you can subscribe to:

Event	Description
`order.created`	New order placed
`order.updated`	Order details updated
`order.cancelled`	Order cancelled
`order.delivered`	Order marked as delivered

See Webhooks for setup instructions.

Bookings

Create bookings, check available slots, and manage appointment resources.

Webhooks API

Manage webhook configurations, test deliveries, and inspect logs via the REST API.