开发者发起下单
收藏
我的收藏

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

使用限制

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

接口说明

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

基本信息

基本信息
HTTP URL	https://developer.toutiao.com/api/apps/trade/v2/create_order
HTTP Method	POST

请求头

参见通用参数。

请求参数

名称	类型	是否必填	描述	示例值
goods_list	Array<object>	是	商品信息，详情见 goods_list 字段	见请求示例
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://developer.open-douyin.com/microapp/ttf4d2826f6becc24001/pay`页面设置的支付回调地址。 `ttf4d2826f6becc24001`为小程序的 `AppID`。	https://order
out_order_no	string	是	开发者的单号，长度 <= 64 byte	132324
pay_expire_seconds	int64	否	支付超时时间，单位秒，例如 300 表示 300 秒后过期；不传或传 0 会使用默认值 300，最大不能超过48小时。	500
order_entry_schema	object	是	订单详情页信息，详情见 order_entry_schema 字段	见请求示例
cp_extra	string	否	开发者自定义透传字段，不支持二进制，长度 <= 2048 byte	cp_extra
discount_amount	int64	否	折扣金额，单位分	20
price_calculation_detail	object	否	营销算价结果信息，详情见 price_calculation_detail 字段	见请求示例

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	否	商品详情页，详情见 goods_page 字段
order_valid_time	object	否	券的有效期，详情见 order_valid_time 字段注意： 1.非 POI 商品必传，POI 商品会从 POI 库里查询有效期信息，不会使用开发者传的数据。 2.如果是非 POI 商品，每个 goods_id 都要传券的有效期信息，否则会下单失败。
discount_amount	int64	否	折扣金额，单位分	1
goods_book_info	object	否	预约信息，详情见 goods_book_info 字段注意：需要预约的商品必传
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

price_calculation_detail 字段

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

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>	否	营销明细，详情见 marketing_detail_info 字段

order_discount_detail 字段

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

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 字段

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

请求示例

text复制
curl --location --request POST '\
--header 'Content-Type: application/json' \
--header 'Byte-Authorization: SHA256-RSA2048 appid="ttxxx",nonce_str="DC10180A100073E70A48F195DA2AF2E6",timestamp="1623934869",key_version="1",signature="nwd1L3wCX+01/TVTkILeovF1DtYeghC1VHjrcjTHVkh7+gRaONEQkC2Y72Mw8JdSnIyeAtyp/pDHzyKGywjVqv5+JOBEhQG1/pvwNHN49wD26qg3AJL4hXw0fMJSRiTQEV1MszwDLuaabvo/qM9OXL9KyYiEPwVJqYtzmho4cHXT6mYgzNOW1xt5d7RDf4QO74JI3i4dtk9Uj8svJTrrBabML6AUcqcx2OP/7xukdaUgPdPf+IqmMG6GC4n52LUDogcL5n/osLdfHg9l6kW5gDcDjBfNDaggz07QMPHGdVao7pnQ2ub7VqcFIuY6Q3cBL7ndQdDGKrv+WBy5Q90QjQ=="'
--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
            }
        ]
    }
}'

响应参数

名称	类型	是否必填	描述	示例值
err_no	int64	是	状态码 0，业务处理成功，具体错误码参见后文错误码	0
err_tips	string	是	错误提示信息	success
data	Json 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_info_list 字段

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_detail 字段

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

响应示例

正常示例

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
          }
        ]
      }
    ]
  },
  "err_tips": "success",
  "err_no": 0
}

异常示例

json复制
{
    "err_no": 10000，
    "err_tips": "参数错误"
}

错误码

详情参见错误码/返回码。

该文档是否有帮助？

本页导读

order_entry_schema 字段

order_valid_time 字段

price_calculation_detail 字段

goods_discount_detail 字段

order_discount_detail 字段

item_discount_detail 字段

marketing_detail_info 字段

goods_book_info 字段

请求示例

响应参数

item_order_info_list 字段

开发者发起下单收藏我的收藏

​使用限制​

​接口说明​

​基本信息​

​请求头​

​请求参数​

​goods_list 字段​

​goods_page 字段​

​order_entry_schema 字段​

​order_valid_time 字段​

​price_calculation_detail 字段​

​goods_discount_detail 字段​

​order_discount_detail 字段​

​item_discount_detail 字段​

​marketing_detail_info 字段​

​goods_book_info 字段​

​请求示例​

​响应参数​

​item_order_info_list 字段​

​item_order_detail 字段​

​响应示例​

​正常示例​

​异常示例​

​错误码​

开发者发起下单
收藏
我的收藏

使用限制

接口说明

基本信息

请求头

请求参数

goods_list 字段

goods_page 字段

order_entry_schema 字段

order_valid_time 字段

price_calculation_detail 字段

goods_discount_detail 字段

order_discount_detail 字段

item_discount_detail 字段

marketing_detail_info 字段

goods_book_info 字段

请求示例

响应参数

item_order_info_list 字段

item_order_detail 字段

响应示例

正常示例

异常示例

错误码