ShopChat REST API

ShopChat registers a REST API namespace (/wp-json/shopchat/v1/) for the chat widget. All endpoints accept POST requests with a JSON body.

Endpoints

Message Request

Endpoint: POST /wp-json/shopchat/v1/message

{
  "message": "Do you have running shoes under $80?",
  "product_id": 42,
  "nonce": "a1b2c3d4e5",
  "session_id": "abc123",
  "history": []
}

Response:

{
  "success": true,
  "message": "Yes! Here are some options under $80...",
  "session_id": "abc123"
}

Errors return "success": false with a message and an HTTP error status.

Order Lookups

When a message asks about an order (for example, "Where is my order #1234?") or starts a return, ShopChat only shares order details with the order's customer:

• a customer logged in to the account that placed the order, or
• anyone who includes the order's billing email in the message.

Otherwise, ShopChat asks the customer to log in or provide the billing email. A wrong email and an order number that doesn't exist get the same reply, so the chat never reveals whether an order exists. The same check applies to /return-request.

For a return question, the /message response has "type": "return_check", "eligible" and "order_id" - and, when eligible, the "email" the customer just used, so the widget can submit the request.

Return Request

Endpoint: POST /wp-json/shopchat/v1/return-request

The request is re-checked for ownership, status and return window. When it succeeds ("success": true), an order note is added, the Support Email is notified and the ROI Return Requests counter goes up. Ineligible orders, orders that already have a request, or a disabled Return Request Assistant return "success": false with a message.

Authentication

Every endpoint requires the shopchat_nonce value, which the widget adds automatically. For logged-in customers, the widget also sends the standard WordPress REST nonce in the X-WP-Nonce header so ShopChat can identify the customer. If that nonce has expired (for example, on a cached page), the widget retries the request as a guest.