create_order

Places the order using the preview_id and confirmation_token returned by a preview. On success it returns the platform order ID order_id, the order status, the payable amount payable_price, and (when payment is required) the payment_action.

Order flow: search_shops → shop_id + cart_id → get_shop_menu to pick items → quote_cart to price the cart and get quote_id → select_address to get address_id → preview_order → preview_id + confirmation_token → create_order → order_id + payment_action. The preview_id and confirmation_token must come from the same preview_order call and be passed back as-is — never fabricate or mix them.

This tool is idempotent, keyed on confirmation_token. The idempotency fingerprint compares preview_id + confirmation_token + payment_method, plus whether require_phone_verify is true (not callback_url). Repeating the call with the same confirmation_token: if those match the first call, it returns the first result; if any differs, it returns IDEMPOTENCY_CONFLICT. A token places exactly one order — to order again, run preview_order for a fresh token. Note: changing only callback_url (the other three unchanged) is not a conflict — it replays and restarts status tracking (so callbacks may be delivered more than once).

Parameters

Parameter	Type	Required	Default	Description
`consent_grant_id`	string	Yes	—	User consent grant ID (`cg_` prefix, from `verify_user_bind`), identifying the consenting user
`preview_id`	string	Yes	—	Preview ID (from `preview_order`, passed back as-is)
`confirmation_token`	string	Yes	—	Confirmation token (from the same `preview_order`, passed back as-is); also the idempotency key
`payment_method`	string \| null	No	`null`	Payment channel; omit to use the default channel
`callback_url`	string \| null	No	`null`	Order-status callback URL (absolute http(s) URL); when set, every status change on this order POSTs one event to that URL (see below)
`require_phone_verify`	boolean	No	`false`	When `true`, this order’s payment / detail links first ask for the last 4 digits of the ordering phone number; the order page opens only after a correct entry (see below)
`lang`	string	No	—	Language for this response. One of `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`; defaults to the language set at binding time (Chinese if unset)
`include_chinese`	boolean	No	false	When `true`, the response also includes the Chinese original (`<key>_zh`) — see Bilingual responses

About require_phone_verify: when true, every link for this order — the payment_action.action_url returned here, and the detail_url later returned by get_order_status / list_orders — first shows a confirmation page asking for the last 4 digits of the phone number used to place the order; the order page opens only after a correct entry. Once confirmed, the same browser is not asked again for 24 hours; after 5 wrong attempts the order’s links are locked for 24 hours. Useful when links travel through chat and may reach the wrong person. The setting is fixed at order creation and cannot be changed later; omitted or false leaves the links exactly as before. About callback_url: must be an absolute http/https URL; loopback / private / link-local hosts are rejected. When set, every status change on this order POSTs one event to that URL, until the order ends (completed / cancelled / failed / refunded). Status is checked roughly every 2 seconds while unpaid, and every 30 seconds after payment. If the order has not ended after 2 hours, a final timeout event is sent and tracking stops, so you are never left waiting. Callback body:

{
  "event": "order_status",
  "order_id": "ord_...",
  "seq": 3,
  "status": "delivering",
  "previous_status": "preparing",
  "status_text": "配送中",
  "event_at": "2026-08-26T12:34:56+08:00",
  "consent_grant_id": "cg_..."
}

Field	Description
`event`	`order_status`; the payment-outcome event is `order_payment` (see below)
`order_id`	Platform order ID
`seq`	Event sequence number for this order, starting at 1 and incrementing without gaps
`status`	The status just entered (enum below)
`previous_status`	Status of the previous event; `null` on the first one
`status_text`	Chinese display text for `status` (e.g. `配送中`)
`event_at`	When the change happened (ISO 8601, Beijing time)
`consent_grant_id`	The user grant this order belongs to. Rarely absent (orders whose tracking resumed after a service restart cannot recover this value) — match on `order_id` instead

status enum (8 values):

Value	Meaning
`pending_payment`	Awaiting payment
`paid`	Paid
`preparing`	Merchant preparing
`delivering`	Out for delivery
`completed`	Completed (ends tracking)
`cancelled`	Cancelled (ends tracking)
`failed`	Order or fulfillment failed (ends tracking)
`refunded`	Refunded (ends tracking)

Order creation itself does not get its own event — the create_order response is the receipt for that. The first event is normally pending_payment.

The payment-outcome event carries two extra fields, in exactly the previous callback format, so existing receivers need no changes:

{
  "event": "order_payment",
  "ispay": "success",
  "...": "all other fields as above"
}

`ispay`	Meaning
`success`	Payment went through
`closed`	Cancelled or closed
`timeout`	Order still not ended after 2 hours
`unknown`	Grant revoked / rotated; the gateway can no longer query this order

Use seq to detect missed events: seq increments without gaps per order. If you receive 1, 2, 4, event 3 never arrived — call get_order_status to fetch the current state. Deduplication: delivery is at-least-once; the same event may arrive more than once, so dedupe on (order_id, seq). A failed delivery is retried three times (after 1 / 2 / 4 seconds) and then dropped, without affecting the order itself. Without callback_url, nothing is pushed — poll get_order_status yourself.

Returns

{
  "order_id": "ord_8c1d...",
  "status": "pending_payment",
  "payable_price": 1500,
  "payment_action": {
    "action_id": "act_3f9a...",
    "action_type": "open_h5",
    "action_url": "https://...",
    "expires_at": "2026-06-16T12:30:00+00:00"
  },
  "callback_registered": true
}

The payable_price field is in cents (integer), not yuan. e.g. payable_price: 1500 means ¥15.00.

Field	Type	Description
`order_id`	string	Platform order ID (`ord_` prefix), passed to `get_order_status` for status
`status`	string	Order status enum (see below)
`payable_price`	integer	Payable amount (cents)
`payment_action`	object \| null	Payment action; returned when payment is required, otherwise `null`
`payment_action.action_id`	string	Action ID (`act_` prefix)
`payment_action.action_type`	string	Action type, currently `open_h5` (open the H5 payment page)
`payment_action.action_url`	string	Payment page URL to guide the user through payment; for orders created with `require_phone_verify: true`, it first asks for the last 4 digits of the ordering phone number
`payment_action.expires_at`	string	Action expiry (ISO 8601, UTC); valid for ~30 minutes
`callback_registered`	boolean	Whether a payment callback was registered (i.e. whether the request carried a valid `callback_url`)

status enum: created, pending_payment, paid, preparing, delivering, completed, cancelled, failed, refunded.

Error Codes

code	Description
`CONSENT_GRANT_REQUIRED`	Missing consent grant (no `consent_grant_id`)
`CONSENT_GRANT_INVALID`	Consent grant is invalid
`CONSENT_GRANT_EXPIRED`	Consent grant has expired; re-authorization required
`CAP_NOT_BOUND`	The delivery capability is not enabled for this agent
`CONSENT_GRANT_WRONG_CAP`	Consent grant belongs to a different capability / provider
`PUBLIC_REFERENCE_INVALID`	`preview_id` / `confirmation_token` invalid or expired, the two do not match (not from the same preview), or `callback_url` is invalid
`IDEMPOTENCY_CONFLICT`	The same `confirmation_token` was reused but `preview_id`, `payment_method` or `require_phone_verify` differs from the first call; re-preview for a fresh token
`ORDER_FAILED`	Order creation failed; re-preview and retry
`ELEME_ERROR`	Upstream order API error; retry later

See Error Handling for the full list.

Example Call

{
  "name": "create_order",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "preview_id": "<from preview_order>",
    "confirmation_token": "<from preview_order>"
  }
}

With phone confirmation on the links:

{
  "name": "create_order",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "preview_id": "<from preview_order>",
    "confirmation_token": "<from preview_order>",
    "require_phone_verify": true
  }
}

Overview

Integration

Guides

Authorization

Shops

Addresses

Order

Payment

create_order

create_order

Parameters

Returns

Error Codes

Example Call

​create_order

​Parameters

​Returns

​Error Codes

​Example Call

create_order

Parameters

Returns

Error Codes

Example Call