AI Ordering API

After a customer selects products in the conversation, AI drafts an order for the customer to confirm. Once the customer confirms, we ask your system to create a pending-payment order and give the customer the payment link you return. We do not store orders or handle payments.

In the admin panel's "Bot Settings", fill in the order API (if left blank, AI cannot place orders). You can also fill in the login page URL: when a customer who is not logged in wants to place an order, a "Log in" button appears in the chat window.

Prerequisites:

• Only logged-in customers can place orders. user_id comes from the user_token you issue (see Identify logged-in customers).
• Products must be synced via the open API (see Knowledge base and products); products with variants must include variants[].sku. When placing an order, we pass the sku to you unchanged.

How customers confirm:

• Web chat window: After AI drafts the order, an order card is displayed. The order is created only after the customer clicks "Confirm order"; once created, a "Pay now" button appears on the card.
• Channels that can only send text, such as WeChat Mini Programs: AI sends the customer an order summary. The order is created only after the customer replies "Confirm"; once created, a payment entry point is sent (see mp_path below).

Request

The same endpoint uses mode to distinguish between quotes and order creation. The signing and signature verification methods are the same as those for the Order lookup API; the timeout is 10 seconds.

POST {你的下单接口}
Content-Type: application/json
X-AICS-Timestamp: 1761120000
X-AICS-Signature: v1=<hex>

{
  "mode": "quote",
  "request_id": "chk_3f2a9c...",
  "user_id": "u_123",
  "conversation_id": "b3c1...",
  "channel": "widget",
  "language": "en",
  "country": "US",
  "items": [{"product_id": "w1", "sku": "w1-black", "qty": 1}]
}

Response

Quote successful:

{
  "status": "quoted",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "discounts": [{"label": "新客券", "amount": "20.00"}],
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

Order created successfully:

{
  "status": "created",
  "order_no": "T2026102300001",
  "pay_url": "https://shop.example.com/pay?orderno=T2026102300001",
  "mp_path": "pages/order/pay?orderno=T2026102300001",
  "expires_at": "2026-10-23T12:30:00Z",
  "currency": "USD",
  "goods_amount": "399.00",
  "discount": "20.00",
  "shipping_fee": "0",
  "tax": "0",
  "total": "379.00"
}

Unable to place an order:

{"status": "rejected", "code": "OUT_OF_STOCK", "message": "这款黑色暂时缺货"}

• All amounts are strings. total and currency are required; the rest may be omitted. discounts displays at most 5 entries.
• pay_url is the web payment link and must use https. If a domain allowlist is configured on the "Integration" page, it must also be on an allowlisted domain or one of its subdomains; otherwise it will not be displayed.
• mp_path is the payment page path in the Mini Program. In the WeChat channel, it is sent to the customer as a Mini Program card (using the image of the first product as the cover). If mp_path is not provided, pay_url is sent. At least one of the two must be provided.
• expires_at is the payment deadline and is displayed on the card.
• Possible values for code: OUT_OF_STOCK, SKU_UNAVAILABLE, REGION_UNAVAILABLE, NOT_LOGGED_IN, LIMIT, OTHER. message is shown directly to the customer; please use wording the customer can understand.
• If you do not want to provide a quote, you can return {"status": "unsupported"} for quote; the card will estimate the amount based on prices in the product library and note "The final amount is subject to the payment page."
• If create returns a non-200 response or an invalid format, the order confirmation is retained and the customer can click again; please make sure a duplicate request_id does not create a second order.

Limits: An order confirmation is valid for 30 minutes. Drafting a new one in the same conversation invalidates the old one. An order can contain at most 10 product types and at most 20 units of each type. A single conversation can create at most 5 orders within 24 hours.