Orders

Retrieve and manage WhatsApp commerce orders. The order_source field distinguishes native cart orders from carousel campaign orders. Each WABA has its own display order_number sequence (configure via API or portal).

Setup (API or portal): Use GET/PUT /api/external/commerce/settings to configure auto-acknowledgement (text or approved template) and order numbering (prefix, pad, next). Catalog link, Meta cart toggles, and RSA keys stay in the ChatYug portal Commerce Settings page.

Commerce settings (auto-ack + numbering)

GET /api/external/commerce/settings

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

Returns settings for the API key WABA, including auto_ack_* and order_number_* fields.

PUT /api/external/commerce/settings

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

Request parameters

Field	Required	Type	Description
`autoAckEnabled`	No	boolean	When `true`, must set text body or template name
`autoAckType`	No	string	`text` or `template`
`autoAckBody`	Conditional	string	Free-text with `{{order_number}}`, `{{items}}`, `{{total}}`, `{{currency}}`, `{{customer_name}}`
`autoAckTemplateName`	Conditional	string	APPROVED Meta template name
`autoAckTemplateLanguage`	No	string	Default `en`
`autoAckTemplateVars`	No	array	Body param mapping, e.g. `["order_number","items","total"]`
`orderNumberPrefix`	No	string	e.g. `ORD-`
`orderNumberPad`	No	number	0–10 zero-pad width
`orderNumberNext`	No	number	Next sequence (≥1); does not rewrite historical orders
`autoSendCheckoutFlow`	No	boolean	Auto-send checkout Flow after cart (takes precedence over text/template ack)
`checkoutFlowId`	No	string	Meta Flow ID

Example — text ack + numbering

curl -X PUT https://chatyug.com/api/external/commerce/settings \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "autoAckEnabled": true,
    "autoAckType": "text",
    "autoAckBody": "✅ Order Received!\\n\\nOrder #{{order_number}}\\n{{items}}\\n\\nTotal: {{currency}} {{total}}",
    "orderNumberPrefix": "ORD-",
    "orderNumberPad": 4,
    "orderNumberNext": 1
  }'

Example — disable auto-ack

curl -X PUT https://chatyug.com/api/external/commerce/settings \
  -H "Authorization: Bearer ck_YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "autoAckEnabled": false }'

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_number": "ORD-0001",
      "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
}

id is the internal key for /orders/:orderId paths. order_number is the per-WABA display number shown to customers (may be null on older orders — fall back to id).

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[], shipping_address, flow_token, and checkout_submission (latest Flow Analytics submit for that token, with media attachments[], or null if not completed).

Response example

{
  "success": true,
  "order": {
    "id": 1001,
    "order_number": "ORD-0001",
    "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"
    },
    "checkout_submission": {
      "eventId": 69,
      "submittedAt": "2026-07-13T07:05:00.000Z",
      "payload": {
        "customer_name": "Rahul Sharma",
        "delivery_address": "123 Demo Street",
        "city": "Bharuch",
        "pincode": "392001",
        "payment_method": "cod"
      },
      "attachments": [
        {
          "field": "photo_id",
          "mediaType": "image",
          "downloadUrl": "https://chatyug.com/api/external/commerce/flows/analytics/events/69/media/photo_id",
          "metadataUrl": "https://chatyug.com/api/external/commerce/flows/analytics/events/69/media/photo_id?format=json"
        }
      ],
      "hasMedia": true
    },
    "total_amount": 998,
    "currency": "INR"
  }
}

Download Flow uploads with Bearer auth on attachments[].downloadUrl. See Checkout Flows — analytics and media.

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.