Orders

Retrieve and manage WhatsApp commerce orders. The order_source field distinguishes native cart orders from carousel campaign orders.

List orders

GET /api/external/orders

Auth: Authorization: Bearer ck_<api_key> (required)

Query parameters

Field	Required	Type	Description
`status`	No	string	Filter by status
`page`	No	number	Page number (default `1`)
`pageSize`	No	number	Items per page (default `20`)
`dateFrom`	No	string	Start date `YYYY-MM-DD`
`dateTo`	No	string	End date `YYYY-MM-DD`
`dateFromUtc`	No	string	ISO 8601 UTC start (overrides `dateFrom`)
`dateToUtc`	No	string	ISO 8601 UTC end (overrides `dateTo`)

Response example

{
  "success": true,
  "orders": [
    {
      "id": 1001,
      "order_source": "catalog_cart",
      "status": "pending",
      "customer_phone": "919876543210",
      "customer_name": "Rahul Sharma",
      "meta_catalog_id": "900000000000003",
      "flow_token": "order_1720856400000_abc123",
      "items": [
        {
          "product_retailer_id": "SKU-DEMO-001",
          "product_name": "Demo Cotton T-Shirt",
          "quantity": 2,
          "item_price": 499,
          "currency": "INR"
        }
      ],
      "total_amount": 998,
      "currency": "INR"
    }
  ],
  "total": 1,
  "page": 1,
  "pageSize": 20
}

order_source values stored by ChatYug:

catalog_cart — native WhatsApp cart checkout (default)
carousel_campaign — customer tapped Buy on a carousel card
carousel_inquiry — text inquiry on a commerce carousel

Get order

GET /api/external/orders/:orderId

Auth: Authorization: Bearer ck_<api_key> (required)

Returns full order details including parsed items[] and shipping_address.

Response example

{
  "success": true,
  "order": {
    "id": 1001,
    "order_source": "catalog_cart",
    "status": "confirmed",
    "customer_phone": "919876543210",
    "flow_token": "order_1720856400000_abc123",
    "items": [
      {
        "product_retailer_id": "SKU-DEMO-001",
        "product_name": "Demo Cotton T-Shirt",
        "quantity": 2,
        "item_price": 499,
        "currency": "INR"
      }
    ],
    "shipping_address": {
      "customer_name": "Rahul Sharma",
      "delivery_address": "123 Demo Street",
      "city": "Bharuch",
      "pincode": "392001",
      "payment_method": "cod"
    },
    "total_amount": 998,
    "currency": "INR"
  }
}

Update status

PUT /api/external/orders/:orderId/status

Auth: Authorization: Bearer ck_<api_key> (required)

Request parameters

Field	Required	Type	Description
`status`	Yes	string	One of: `pending`, `confirmed`, `shipped`, `delivered`, `cancelled`
`note`	No	string	Status note appended to customer notification
`notifyCustomer`	No	boolean	Send WhatsApp status update (default `true`)

Response example

{
  "success": true,
  "message": "Order status updated to shipped",
  "notifySent": true
}

Add note

POST /api/external/orders/:orderId/note

Auth: Authorization: Bearer ck_<api_key> (required)

Request parameters

Field	Required	Type	Description
`note`	Yes	string	Note text to attach to the order

Response example

{ "success": true, "message": "Note added to order" }

Notify customer

POST /api/external/orders/:orderId/notify

Auth: Authorization: Bearer ck_<api_key> (required)

Request parameters

Field	Required	Type	Description
`message`	No	string	Custom WhatsApp message body. A default status message is sent if omitted.

Response example

{
  "success": true,
  "message": "Notification sent to customer",
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSQjAwMDAwMDAwMDAwMDAwAA=="
}

Code samples — update status

curl -X PUT https://chatyug.com/api/external/orders/1001/status \
  -H "Authorization: Bearer ck_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{ "status": "shipped", "note": "Dispatched via BlueDart" }'

const axios = require('axios');

await axios.put('https://chatyug.com/api/external/orders/1001/status', {
  status: 'shipped',
  note: 'Dispatched via BlueDart'
}, { headers: { Authorization: 'Bearer ck_your_api_key_here' } });

import requests

requests.put('https://chatyug.com/api/external/orders/1001/status', json={
    'status': 'shipped',
    'note': 'Dispatched via BlueDart'
}, headers={'Authorization': 'Bearer ck_your_api_key_here'})

$client = new GuzzleHttp\Client();
$client->put('https://chatyug.com/api/external/orders/1001/status', [
    'headers' => ['Authorization' => 'Bearer ck_your_api_key_here'],
    'json' => ['status' => 'shipped', 'note' => 'Dispatched via BlueDart']
]);

Related webhook: Native cart orders trigger eventType: order when Meta sends the cart checkout event. Carousel orders are created internally with order_source carousel_campaign or carousel_inquiry — use GET /orders to retrieve them. See Event Reference.