preview_order

对一个已算价的购物车做下单前预览：校验店铺 / 地址 / 商品、应用优惠券，返回最终价格明细，以及用于正式下单的 preview_id 与 confirmation_token。

下单链路：search_shops 得 shop_id + cart_id（已含配送坐标）→ get_shop_menu 选商品 → quote_cart 算价得 quote_id → select_address 得 address_id → preview_order 得 preview_id + confirmation_token → create_order。预览必须基于一个已存在的 cart_id。

参数

参数	类型	必填	默认	说明
`consent_grant_id`	string	是	—	用户授权 ID（`cg_` 前缀，来自 `verify_user_bind`），标识已授权用户
`shop_id`	string	是	—	店铺 ID（来自 `search_shops`）
`cart_id`	string	是	—	购物车上下文 ID（来自 `search_shops`，已封装店铺与配送坐标，故预览无需再传经纬度）
`quote_id`	string \| null	否	`null`	报价 ID（来自 `quote_cart`）；提供后会校验报价上下文
`address_id`	string	是	—	网关地址 ID（字符串），原样使用 `select_address` 返回的 `address_id`
`items`	array	是	—	商品列表（见下）
`items[].item_id`	string	是	—	商品 ID（来自 `get_shop_menu`）
`items[].sku_id`	string	否	`null`	SKU ID
`items[].quantity`	integer	是	—	数量，≥ 1
`items[].ingredient_option_ids`	string[]	否	`[]`	配料 / 做法选项 ID 列表（来自菜单项的可选项；非默认规格用该规格 `sku_options[].ingredient_options` 的 option_id）
`items[].ingredient_quantities`	array	否	`[]`	为某个选项指定份数，如「浓缩份数 x3」，格式 `[{option_id, quantity}]`；仅 `max_quantity` 大于 1 的选项可用，超出会下单失败。列在这里即视同已选，不必再写进 `ingredient_option_ids`；不传则按各选项的 `default_quantity`（商家推荐份数）
`items[].remark`	string	否	`""`	单品备注
`coupon_ids`	string[] \| null	否	`null`	优惠券选择，三态见下
`order_remark`	string	否	`""`	订单备注（给骑手）
`lang`	string	否	—	本次返回内容使用的语言，枚举 `zh` / `en` / `ja` / `ko` / `ru` / `ms` / `es`；不传则用绑定时设定的语言（默认中文）
`include_chinese`	boolean	否	false	为 `true` 时响应同时返回中文原文（`<key>_zh`），见双语响应

coupon_ids 三态：

不传该参数 → 网关自动选择最优券
传 []（空数组） → 明确不使用任何券
传 ["<coupon_id>", ...] → 使用指定券（券 ID 来自上一次预览返回的 available_coupons[].coupon_id）

所有金额字段单位为分（整数），不是元。例如 payable_price: 1500 表示 ¥15.00。

字段	类型	说明
`preview_id`	string	预览 ID（`prv_`），传给 `create_order`；有效期约 10 分钟
`confirmation_token`	string	确认令牌（`cf_`），与 `preview_id` 一起传给 `create_order`
`shop.name`	string	店铺名称
`shop.logo_url`	string \| null	店铺 logo URL，与 `get_shop_menu` 的 `shop.logo_url` 同源；无则为 `null`
`shop.lat`	number \| null	店铺纬度，与 `get_shop_menu` 的 `shop.lat` 同源同值；坐标系同请求 `lat` / `lng`（高德 GCJ-02）；菜单阶段未取到坐标时为 `null`
`shop.lng`	number \| null	店铺经度，其余同 `shop.lat`
`address.display_name`	string	地址显示名
`address.address_detail`	string	门牌等详情
`address.city`	string	城市名（如「武汉」）。早期创建的地址为空串，表示未知，不代表在其他城市。
`items[].item_id`	string	商品 ID
`items[].name`	string	商品名
`items[].quantity`	integer	数量
`items[].price`	integer	单品价（分）
`items[].min_purchase`	integer \| null	起购份数回显；同 `quote_cart` 的 `items[].min_purchase`
`items[].available_quantity`	integer \| null	库存余量回显；同 `quote_cart` 的 `items[].available_quantity`
`items[].image_url`	string \| null	商品图 URL，无图为 `null`
`items[].specs`	array	该项已选规格，`[{name, value}]`（如 `{"name":"规格","value":"大杯"}`）；无规格时为 `[]`
`items[].selected_ingredients`	array	该项已选配料/做法，`[{group_name, name, price_delta, quantity}]`；`group_name` 可为 `null`，`price_delta` 为选 1 份的加价（分），`quantity` 为生效份数（未指定时＝该选项的 `default_quantity`）。加多份不是 `price_delta × quantity`，分档价见 `get_item_options` 的 `price_steps`；无则为 `[]`
`price.goods_price`	integer	商品小计（分）
`price.delivery_fee`	integer	配送费（分）
`price.packing_fee`	integer	打包费（分）
`price.original_price`	integer	优惠前总额（分）= 应付 + 优惠；满足 `original_price − discount = payable_price`
`price.discount`	integer	优惠金额（分）
`price.payable_price`	integer	应付金额（分）
`delivery.estimated_time_text`	string \| null	预计送达文案
`delivery.delivery_type`	string \| null	配送类型（当前为 `null`）
`payment.requires_payment`	boolean	是否需要支付
`payment.available_methods`	string[]	可用支付方式
`warnings`	array	预览告警（如商品变更）
`available_coupons`	array	可用优惠券；`coupon_id` 可回传到 `coupon_ids`
`available_coupons[].amount`	integer	券面额（分）
`available_coupons[].threshold`	integer	使用门槛（分）
`available_coupons[].available`	boolean	是否可用
`available_coupons[].unavailable_reason`	string \| null	不可用原因
`selected_coupons`	array	本次已应用的券（含 `coupon_id` / `name` / `amount`）
`shop_activities`	object	店铺活动（店铺满减 / 首次光顾立减 / 满返红包），上游服务端自动应用、不在 `available_coupons`、不走选券链路；无活动时 `total_discount` 为 `0`、`activities` 为 `[]`
`shop_activities.total_discount`	number	本单店铺活动立减合计（单位元，非分）；只累加 `type=discount` 的活动
`shop_activities.activities[].name`	string	活动名称，如「店铺满70减3」「首次光顾立减」
`shop_activities.activities[].type`	string	`discount`=本单立减（本次订单立即抵扣，计入 `total_discount`）；`return`=满返红包（返到下一单使用，不抵本单）
`shop_activities.activities[].amount`	number \| null	本单立减金额（单位元，非分）；`type=discount` 时为立减额，`type=return` 时为 `null`
`shop_activities.activities[].desc`	string	展示文案，如「-¥3」「实付0元返2元店铺专享红包」
`shop_activities.activities[].tag`	string \| null	活动角标，如「减」「新」「返」；无则 `null`

shop_activities.total_discount / activities[].amount 单位为元（浮点，如 3.0），是本响应「金额单位为分」规则的唯一例外。本单立减（type=discount）通常已体现在 price.payable_price 中，total_discount 仅供展示，勿再从应付额扣减。

shop_activities 形态示例（带店铺活动的店铺）：

{
  "total_discount": 4.0,
  "activities": [
    {"name": "店铺满70减3", "type": "discount", "amount": 3.0, "desc": "-¥3", "tag": "减"},
    {"name": "满返红包", "type": "return", "amount": null, "desc": "实付0元返2元店铺专享红包", "tag": "返"}
  ]
}

错误码

code	说明
`CONSENT_GRANT_REQUIRED`	缺少用户授权（未传 `consent_grant_id`）
`CONSENT_GRANT_INVALID`	用户授权无效
`CONSENT_GRANT_EXPIRED`	用户授权已过期，需重新授权
`CAP_NOT_BOUND`	该 Agent 未开通外卖能力
`CONSENT_GRANT_WRONG_CAP`	授权属于其它能力 / 服务商
`PUBLIC_REFERENCE_INVALID`	`cart_id` / `quote_id` 无效或过期、`shop_id` 与 `cart_id` 不匹配，或 `address_id` 无效
`MISSING_REQUIRED_SELECTION`	购物车未选满店铺必选商品组（如麻辣烫「必选好汤」）。需从 `get_shop_menu` 响应 `required_groups[].candidate_item_ids` 补选商品后重试；`message` 指明缺哪个组
`BELOW_MIN_PURCHASE`	商品数量低于起购下限（见菜单 / `get_item_options` 的 `items[].min_purchase`）。按 `message` 明细调高对应商品 `quantity` 后重试
`ELEME_ERROR`	上游预览 API 错误；稍后重试

完整错误码见错误处理。

调用示例

{
  "name": "preview_order",
  "arguments": {
    "consent_grant_id": "cg_your_consent_grant",
    "shop_id": "<来自 search_shops>",
    "cart_id": "<来自 search_shops>",
    "address_id": "<来自 select_address>",
    "items": [
      {"item_id": "670685166551", "sku_id": "5014584502270", "quantity": 1}
    ]
  }
}

概览

接入

指南

授权

店铺

地址

下单

支付

preview_order

preview_order

参数

返回

错误码

调用示例

​preview_order

​参数

​返回

​错误码

​调用示例

preview_order

参数

返回

错误码

调用示例