发起下单

更新时间 2024-07-24 02:58:49

我的收藏

如果用户抖音版本过低，无法使用前端 JSAPI 下单，开发者可用该接口替用户发起下单。

使用限制

预下单 OpenAPI 只针对低版本（低于抖音 19.7.0，基础库 20.43.0.3 版本）使用，我们会统计此类订单占比，如果发现违规使用，会进行惩处。当低版本减少后，会下掉该接口，请不要应用于其它场景，否则会影响业务。

接口说明

该接口发起的下单流程中不会有预下单回调。前端 JS API 下单与服务端 OpenAPI 下单的流程区别如下：

基本信息

基本信息
HTTP URL	https://open.douyin.com/api/apps/trade/v2/order/create_order
HTTP Method	POST
Scope	aweme.industry_open.trade_order
权限要求	不需要用户授权

请求头

参考通用参数

请求参数

名称	类型	是否必填	描述	示例值
goods_list	Array<object>	否，goods_list 和 sku_list 二选一传入，不能都为空	商品信息，详情见字段描述	见请求示例
sku_list	Array<object>	否，goods_list 和 sku_list 二选一传入，不能都为空	商品sku信息，详情见 sku_list 说明	见请求示例
cp_book_info	object	否 •门票类商品下单必传	预约信息
total_amount	int64	是	订单总价，单位分	100
phone_num	string	否	用户手机号，长度 <= 128 byte	1927365435
contact_name	string	否	用户姓名，长度 <= 64 byte	张三
extra	string	否	下单备注信息，长度 <= 2048byte	extra
open_id	string	是	用户 OpenID	user
pay_notify_url	string	否	支付结果通知地址，必须是 HTTPS 类型。若不填，默认使用在行业模板配置-消息通知的支付结果通知地址。	https://order
out_order_no	string	是	开发者的单号，长度 <= 64 byte	132324
pay_expire_seconds	int64	否	支付超时时间，单位秒，例如 300 表示 300 秒后过期；不传或传 0 会使用默认值 300，最大不能超过48小时。	500
order_entry_schema	object	是	订单详情页信息，详情见字段描述	见请求示例
cp_extra	string	否	开发者自定义透传字段，不支持二进制，长度 <= 2048 byte	cp_extra
discount_amount	int64	否	折扣金额，单位分	20
price_calculation_detail	object	否	营销算价结果信息，详情见字段描述	见请求示例

goods_list 字段

POI 商品会从商品库里查询商品信息，不会使用开发者传的数据。

名称	类型	是否必填	描述	示例值
goods_image	string	否	商品图片链接，长度 <= 512 byte 注意：非 POI 商品必传	https://xxx
goods_title	string	否	商品标题/商品名称，长度 <= 256 byte 注意：非 POI 商品必传	火锅团购
labels	string	否	商品标签，最多设置三个标签，例如：随时退｜免预约｜提前3日预约（“｜”是中文类型），详见 pay-button 支付的 type 的合法值部分，注意不是 good-type 的合法值。注意：非 POI 商品必传	随时退｜免预约
date_rule	string	否	使用规则，如 “周一至周日可用”、“周一至周五可用”、“非节假日可用”，默认“周一至周日可用”	周一至周日可用
price	int64	否	商品价格，单位（分）注意：非 POI 商品必传	100
quantity	int32	是	商品数量	1
goods_id	string	是	商品 id	goods_1
goods_id_type	int32	是	商品 id 类别， •POI 商品传 1 •非 POI 商品传 2	1
goods_page	object	否	商品详情页，详情见字段描述
order_valid_time	object	否	券的有效期，详情见字段描述注意： 1.非 POI 商品必传，POI 商品会从 POI 库里查询有效期信息，不会使用开发者传的数据。 2.如果是非 POI 商品，每个 goods_id 都要传券的有效期信息，否则会下单失败。
discount_amount	int64	否	折扣金额，单位分	1
goods_book_info	object	否	预约信息，详情见字段描述注意：需要预约的商品必传
merchant_uid	string	否	开发者自定义收款商户号，须申请白名单

goods_page 字段

名称	类型	是否必填	描述	示例值
path	string	否	商品详情页路径，长度 <= 512byte	goods/info
params	string	否	商品详情页路径参数，长度 <= 512byte	{\"id\":\"12312\"}

order_entry_schema 字段

名称	类型	是否必填	描述	示例值
path	string	是	订单详情页跳转路径，没有前导的“/”，长度 <= 512byte	pages/xxxindexxx
params	string	否	订单详情页路径参数，自定义的 json 结构，序列化成字符串存入该字段，平台不限制，但是写入的内容需要能够保证生成访问订单详情的 schema 能正确跳转到小程序内部的订单详情页，长度 <= 512byte	{\"id\":\"xxxxxx\"}

order_valid_time 字段

名称	类型	是否必填	描述	示例值
valid_start_time	int64	否	券的有效期开始时间，单位毫秒，须大于 0
valid_end_time	int64	否	券的有效期结束时间，单位毫秒，须大于 0，且须大于 valid_start_time 和当前时间
valid_duration	int64	否	a.券的相对有效时间，单位毫秒，须大于 0 b.与 valid_start_time、valid_end_time 组合，至少回传一个，否则会下单失败 c.都合法优先使用 valid_start_time、valid_end_time 组合 d.当 valid_duration 有效时， ◦券的有效期开始时间 S = 订单支付完成时间 ◦券的有效期结束时间 E = 1天 + 向下按天截断（S + valid_duration)）。例如：valid_duration = 86400000 ms（一天），S = 2021.1.1 6:00，E = 2021.1.3 00:00	100000

sku_list 字段说明

poi 商品会从商品库里查询商品信息，不会使用开发者传的数据

•

sku 为商品库，对应的 goods 必须是商品库

•

sku 为商品库商品，goodsInfo 可以不传

•

sku 为非商品库商品，需要传 goodsInfo

名称	类型	是否必填	描述
quantity	Int32	是	下单SKU数量
sku_id	string	是	商品sku_id
sku_id_type	int32	是	sku_id类型 1-商品库skuId 2-非商品库skuId 1.sku_id 为 POI商品库的sku_id时，goods_info 可以不传入 2.sku_id 为非POI 商品库的sku_id时，goods_info必传
price	Int64	否 •非poi的SKU必传	SKU价格
discount_amount	int64	否	优惠金额，单位（分）
atts	object	否	sku属性
goods_info	object	否	商品信息，详情见 goods_info 字段

atts 字段说明

名称	类型	是否必填	描述
ticket_name	string	否 •非POI商品库的门票类SKU必传	门票-票种类型，长度 <= 128 byte
date	string	否 •非POI商品库的门票类SKU必传	门票日期，示例 2006-01-02，日期格式需为 yy-mm-dd

goods_info 字段说明

名称	类型	是否必填	描述
goods_image	string	否 •非poi商品必传	商品图片链接，长度 <= 512 byte
goods_title	string	否 •非poi商品必传	商品标题/商品名称，长度 <= 256 byte
labels	string	否 •非poi商品必传	商品标签，最多设置三个标签，例如：随时退｜免预约｜提前3日预约（“｜”是中文类型），详见 pay-button 支付的 type 的合法值部分，注意不是 good-type 的合法值。注意：非 POI 商品必传
date_rule	string	否	使用规则，如 “周一至周日可用”、“周一至周五可用”、“非节假日可用”，默认“周一至周日可用”
goods_id	string	是	商品id
goods_id_type	int32	是	商品id类别，poi商品传 1，非poi商品传 2
goods_page	object	否	商品详情页，详情见 goods_page 说明
order_valid_time	object	否 •非poi商品必传	券的有效期，注意： 1.非poi商品必传，poi商品会从poi库里查询有效期信息，不会使用开发者传的数据 2.如果是非poi商品，每个goods_id都要传券的有效期信息，否则会下单失败详情见 order_valid_time 说明
goods_book_info	object	否 •预售券商品必传 •门票商品不用传入	预约信息，详情见 goods_book_info说明

cp_book_info 字段说明

名称	类型	是否必填	描述
out_book_no	string	是	外部预约单号
item_book_info_list	Array<object>	是	每个item的预约信息，详见 ItemBookInfo

ItemBookInfo 字段说明

名称	类型	是否必填	描述
poi_id	string	是	预约门店的poiId
shop_name	string	是	预约门店的名称，参考商铺同步接口中的店铺名称（name）
ext_shop_id	string	是	预约门店的外部店铺id，参考商铺同步接口中的接入方店铺id（supplier_ext_id）
goods_id	string	否	预约的商品id
sku_id	string	否 •goods_id 和 sku_id 只能二选一传入 •使用 sku_list 下单，传入 sku_id 即可	预约的sku_id
book_start_time	int64	是	预约的开始时间（ms），13位毫秒时间戳
book_end_time	int64	是	预约的结束时间（ms），13位毫秒时间戳
user_info_list	Array<object>	否	用户信息，详见UserInfo

UserInfo 字段说明

名称	类型	是否必填	描述
name	string	否	使用人名称
phone	string	否	电话号码
id_card_no	string	否	身份证号码

price_calculation_detail 字段

名称	类型	是否必填	描述	示例值
calculation_type	int32	是	算价类型， •1：商户单维度，item 单价格按分摊比例计算。 •2：item 单维度，item 单价格由开发者计算。	1
goods_discount_detail	Array<object>	否	商品算价结果，详情见字段描述
order_discount_detail	object	否	订单算价结果，详情见字段描述
item_discount_detail	Array<object>	否	单商品算价结果，详情见字段描述

goods_discount_detail 字段

名称	类型	是否必填	描述	示例值
goods_id	string	是	商品 id，此处为课程 id，注意这里是 string 类型	goods_1
quantity	number	是	购买数量	1
total_amount	number	是	商品总价，单位分	100
total_discount_amount	number	是	该商品总优惠金额，该商品的实付金额 = total_amount - total_discount_amount	20
marketing_detail_info	Array<object>	否	营销明细，详情见字段描述

order_discount_detail 字段

名称	类型	是否必填	描述	示例值
order_total_discount_amount	number	是	订单维度总优惠金额，单位分	10
goods_total_discount_amount	number	是	商品（SKU）维度总优惠金额，单位分	10
marketing_detail_info	Array<object>	否	营销明细，详情见字段描述

item_discount_detail 字段

名称	类型	是否必填	描述	示例值
goods_id	string	是	商品 id	goods_1
total_amount	number	是	商品总价，单位分	100
total_discount_amount	number	是	该商品总优惠金额该商品的实付金额 = total_amount - total_discount_amount	20
marketing_detail_info	Array<object>	否	营销明细，详情见字段描述

marketing_detail_info 字段

名称	类型	是否必填	描述	示例值
id	string	是	营销 id（用户身份 id、优惠券 id、积分 id 或者活动 id）	activity_id_12
type	number	是	营销类型: •1：用户身份 •2：优惠券 •3: 积分 •4：活动	4
discount_amount	number	是	该营销策略优惠金额，单位分	10
title	string	是	营销名称	[活动] 满 10.00 减 7.00 元
note	string	否	营销备注	活动优惠
discount_range	number	是	优惠范围	1
subtype	string	否	营销子类型	商家侧子营销类型
value	i64	否	不同 type 含义不同，若 type = 3，value 则为积分值

goods_book_info 字段

名称	类型	是否必填	描述	示例值
book_type	int32	是	预约类型， •1：不需要预约 •2：在线预约	2
cancel_policy	int32	否	取消政策， •1：预约后不可取消 •2：预约后可取消 •3：预约中可取消，预约成功须提前x小时取消	1
cancel_advance_hour	int64	否	提前取消的小时限制	1

请求示例

商品库 good_list 下单

text复制
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/create_order'\
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
    "goods_list": [
        {
            "quantity": 1,
            "price": 100,
            "goods_title": "火锅团购",
            "goods_image": "https://xxx",
            "labels": "随时退|免预约",
            "goods_id": "goods_1",
            "goods_id_type": 2,
            "discount_amount": xxx,
            "date_rule": "周一至周日可用",
            "goods_page": {
                "path": "goods/infoxxxx",
                "params":"{\"id\":\"xxxxxx\"}"
            },
            "order_valid_time": {
                "valid_duration": 100000
            }，
            "goods_book_info": {
                "book_type": 2，
                "cancel_policy": 1
            },
            "merchant_uid":"商户号xxx"
        }
    ],
    "total_amount": 100,
    "discount_amount": 20,
    "app_id": "tt07e3715e98c9aac0",
    "phone_num": "19273654356",
    "contact_name": "张三",
    "extra": "xxx",
    "open_id": "xxx",
    "out_order_no": "132324",
    "pay_notify_url":"https://xxxx",
    "pay_expire_seconds": 500,
    "order_entry_schema": {
        "path":"pages/xxxindexxxx",
        "params":"{\"id\":\"xxxxxx\"}"
    },
    "cp_extra": "xxxxx",
    "price_calculation_detail": {
        "calculation_type": 1,
        "order_discount_detail": {
            "goods_total_discount_amount": 1,
            "marketing_detail_info": [
                {
                    "discount_amount": 10,
                    "discount_range": 1,
                    "id": "activity_id_xxxxxxx",
                    "note": "活动优惠",
                    "subtype": "商家侧子营销类型",
                    "title": "[活动] 满 10.00 减 7.00 元",
                    "type": 4
                },
                {
                    "discount_amount": 10,
                    "discount_range": 2,
                    "id": "coupon_id_xxxxxxx",
                    "note": "用券优惠",
                    "subtype": "商家侧子营销类型默认值",
                    "title": "[券] 减 0.01 元",
                    "type": 2
                }
            ],
            "order_total_discount_amount": 20
        },
        "goods_discount_detail": [
            {
                "goods_id": "goods_1",
                "marketing_detail_info": [
                    {
                        "discount_amount": 10,
                        "discount_range": 1,
                        "id": "activity_id_xxxxxxx",
                        "note": "活动优惠",
                        "subtype": "商家侧子营销类型默认值",
                        "title": "[活动] 满 10.00 减 7.00 元",
                        "type": 4
                    },
                    {
                        "discount_amount": 10,
                        "discount_range": 2,
                        "id": "coupon_id_xxxxxxx",
                        "note": "用券优惠",
                        "subtype": "商家侧子营销类型默认值",
                        "title": "[券] 减 0.01 元",
                        "type": 2
                    }
                ],
                "quantity": 1,
                "total_amount": 100,
                "total_discount_amount": 20
            }
        ],
        "item_discount_detail": [
            {
                "goods_id": "goods_1",
                "marketing_detail_info": [
                    {
                        "discount_amount": 10,
                        "discount_range": 1,
                        "id": "activity_id_xxxxxxx",
                        "note": "活动优惠",
                        "subtype": "商家侧子营销类型默认值",
                        "title": "[活动] 满 10.00 减 7.00 元",
                        "type": 4
                    },
                    {
                        "discount_amount": 10,
                        "discount_range": 2,
                        "id": "coupon_id_xxxxxxx",
                        "note": "用券优惠",
                        "subtype": "商家侧子营销类型默认值",
                        "title": "[券] 减 0.01 元",
                        "type": 2
                    }
                ],
                "total_amount": 100,
                "total_discount_amount": 20
            }
        ]
    }
}'

商品库 SKU、商品库 Goods 下单

text复制
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/create_order'\
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
  "sku_list": [
    {
      "quantity": 2,
      "sku_id": "7128346098909300749",
      "sku_id_type": 1,
      "discount_amount": 0,
      "goods_info": {
        "date_rule": "周一至周日可用",
        "goods_id": "7128346098909300749",
        "goods_id_type": 1
      }
    }
  ],
  "total_amount": 480,
  "discount_amount": 0,
  "phone_num": "31",
  "contact_name": "且题化话",
  "extra": "nisi sit",
  "open_id": "xxxxxxx",
  "out_order_no": "27753r4e5rrr7fer43",
  "order_entry_schema": {
    "path": "2qerrw"
  }
}'

非商品库 SKU、商品库 Goods 下单

text复制
curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/create_order'\
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
  "sku_list": [
    {
      "quantity": 2,
      "sku_id": "7128346098909300749",
      "sku_id_type": 2,
      "price": 240,
      "discount_amount": 0,
      "goods_info": {
        "date_rule": "周一至周日可用",
        "goods_id": "7128346098909300749",
        "goods_id_type": 1
      }
    }
  ],
    "total_amount": 480,
    "discount_amount": 0,
    "phone_num": "31",
    "contact_name": "且题化话",
    "extra": "nisi sit",
    "open_id": "xxxxxxx",
    "out_order_no": "27753r4e5rrr7fer43",
    "order_entry_schema": {
        "path": "2qerrw"
    }
}'

响应参数

名称	类型	是否必填	描述	示例值
data	Json Object	否	返回数据信息
extra	object	是	额外信息

data 字段说明

名称	类型	是否必填	描述	示例值
order_id	string	是	抖音开平侧生成的订单号	ot7072366682238
out_order_no	string	是	开发者系统生成的订单号	121321432
pay_order_id	string	是	调起收银台的支付订单号	12423414234
pay_order_token	string	是	调起收银台的 token	544352343
item_order_info_list	Array<object>	是	商品 item_order 信息，详情见字段描述
item_order_detail_list	Array<object>	是	商品item_order信息，详情 item_order_detail_list部分
open_book_info	object	否	响应的预约信息

item_order_info_list 字段

名称	类型	是否必填	描述	示例值
goods_id	string	是	商品 id	700843652
item_order_id_list	Array	是	item_order_id 列表，id 个数与下单时对应 goods_id 的 quantity 一致
item_order_detail	Array<object>	是	商品 item_order 详细信息，详情见字段描述

item_order_detail 字段说明

名称	类型	是否必填	描述	示例值
item_order_id	string	是	item 单 id	ot70939408076069
price	i64	是	商品优惠后价格	80

item_order_detail_list 字段说明

名称	类型	是否必填	描述
item_order_id	string	是	item单id
price	i64	是	商品优惠后价格
goods_id	string	是	商品id
goods_id_type	int32	是	商品id类别， 1-商品库goods_id 2-非商品库商品goods_id
sku_id	string	否	商品sku_id
sku_id_type	int32	否	sku_id类型 1-商品库skuId 2-非商品库skuId

open_book_info 字段说明

名称	类型	是否必填	描述
book_id	string	是	预约单id

extra 信息

名称	类型	是否必填	描述	示例值
error_code	int	是	错误码，0为成功	0
description	string	是	错误码描述	success
sub_error_code	int	是	子错误码	0
sub_description	string	是	子错误码描述	success
logid	string	是	请求id	2022092115392201020812109511046
now	int	是	毫秒级时间戳	1663745962686

响应示例

正常示例

json复制
{
  "data": {
    "order_id": "ot7072366682238",
    "out_order_no": "121321432",
    "pay_order_id": "12423414234",
    "pay_order_token": "544352343",
    "item_order_info_list": [
      {
        "item_order_id_list": ["ot70939408076069"],
        "goods_id": "700843652",
        "item_order_detail": [
          {
            "item_order_id": "ot70939408076069",
            "price": 80
          }
        ]
      }
    ]
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  }
}

异常示例

json复制
{
  "data": {
    "error_code": 2190004,
    "description": "应用未获得该能力, 请去https://open.douyin.com/申请"
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2190004,
    "description": "应用未获得该能力, 请去https://open.douyin.com/申请"
  }
}