订单查询
通过接口查询指定范围的订单列表及订单详情:
1、查询指定状态的订单列表,用于对账或差异单最新状态确认;
2、查询指定用户的订单列表,用于积分计算、订单展示;
3、查询指定订单详情,用于接口补偿处理。
开票说明
尊敬的商家,依据税务规则与《抖音生活服务平台商户合作协议》的约定,如用户向商家申请开具发票,商家应按照用户实际支付金额向用户开具相应金额的发票。用户的实际支付金额可参考订单查询pay amount字段展示的具体金额(用户实际支付金额,不含平台等其他方补贴的金额)。
针对平台补贴需向平台开具增值税发票,请勿开具给用户。若商家向用户超额开具发票,由此导致的损失及税务风险需由商家自行承担
接口说明
- 服务商通过接口查询订单详情,支持三种查询方式(不支持查询酒店行业订单信息):
- 根据订单 ID 或第三方订单号,查询对应订单详情,入参:订单 ID/第三方订单号、商户 id;该接口为订单维度查询,不支持券维度查询。
- 根据订单状态和商户 id,查询指定时间内该商户下的订单列表,入参:商户 id、订单状态、创单起止时间/修改起止时间;
- 根据用户 id 和商户 id,查询某用户在该商户下的所有订单,入参:商户 id、用户 id、创单起止时间/修改起止时间;
- 支付后未发码/发码失败订单查询方式:限定订单状态为“已支付”,如用户下单后超过 10 分钟未发码会发起退款;
- 退款申请待审核订单查询方式:限定券状态为“退款中”,如退款状态未响应超过 72 小时会自动退款。
- 承载总qps:200 (单服务商应用默认:20)
- 订单查询接口不会透传券码明文code
- 查询时间和订单完成时间一致导致需要延长2-3秒查询或增加重试机制
使用限制
transfer_uid是条件性返回字段,仅在同时满足以下两个条件时才会返回:
订单的sale_role(销售角色)为“达人”“职人”或“店员”;
订单带有明确的room_id(直播间ID)或item_id(商品ID)等关联标识。若订单不满足上述条件(如sale_role为“商家”或“ 其他”,或无关联标识),则该字段不会出现在接口返回数据中。
SLA:支持的最大QPS:20;PCT99承诺值:2ms;基本信息
| 名称 | 描述 |
|---|---|
| HTTP URL | https://open.douyin.com/goodlife/v1/trade/order/query/ |
| HTTP Method | GET |
| Scope | life.capacity.order.query |
| 权限要求 |
|
请求参数
请求头
access-token必填String
示例:clt.943da17996fb5cebfbc70c044c3fc25a57T54DcjT6HNKGqnUdxzy1KcxFnZ
content-type必填String
固定值"application/json"
Rpc-Transit-Life-AccountString
来客商户根账户ID
Query
account_id必填String
来客商户根账户ID
page_num必填Int32
页数从1开始,如果使用page分页,页数*大小不能超过10000
page_size必填Int32
页大小,取值范围1~100
(page_num×page_size 不得超过 10000,超过一万使用 Cursor 参数查询)
create_order_end_timeInt64
创单结束时间(秒时间戳,创单起止时间必须同时传入)
create_order_start_timeInt64
创单起始时间 (秒时间戳,创单起止时间必须同时传入)
cursorArray<String>
根据游标滚动请求,直到返回结果数量小于请求的size或未返回search_after结束;
首页传"0",之后传返回参数中的CursorValue string数组拼接的string,如CursorValue返回参数["0","1"],则传"0,1";
如果传入此参数(cursor),会优先使用cursor翻页,而不是page翻页;但page_size和page_num是必填项,不传会报错
ext_order_idString
开发者系统中的订单号
get_secret_numberBool
是否需要查询配送信息
(已废弃,当前接口忽略该参数)
open_idString
抖音内部用户的一种唯一标识
如果对接了会员通,可以通过接收会员入会SPI接口获取并保存
order_idString
抖音生活服务订单ID
见抖音-团购频道-订单详情
order_statusInt32
订单状态
(0=初始化、100=待支付、101=支付取消、200=已支付、201=待使用、1=已完成、150=部分支付)
update_order_end_timeInt64
修改结束时间(秒时间戳,修改起止时间必须同时传入)
update_order_start_timeInt64
修改起始时间 (秒时间戳,修改起止时间必须同时传入)
请求示例
curl --location --request GET 'https://open.douyin.com/goodlife/v1/trade/order/query/?account_id=VHYZtvyJXr&create_order_end_time=6437135473081235215&page_size=1200168203237520754&open_id=Qb9XduWvWG&order_status=8305758486603389626&update_order_end_time=6658437922105420152&ext_order_id=MzWHfRuRIX&page_num=5786012941338310046&order_id=ZRxTGFNpaS&cursor=[ORSUoD9pIU]&get_secret_number=false&create_order_start_time=1970066883032673265&update_order_start_time=2032414416587900469' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
extra必填Struct
扩展信息
展开子属性
dataStruct
数据列表
展开子属性
响应示例
正常响应示例异常响应示例
{ "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "20261105210749D52E0C3A4A8A51C7271E", "now": 1793884074 }, "data": { "search_after": { "Size": 1028862482384858100, "CursorValue": [ "Y18AgV6k7O" ], "AllCursorValue": [ [ "9Iyi4u36Lf" ] ] }, "orders": [ { "room_id": "eNhU505XVt", "source_order_id": "tsQQlE5P9J", "merchant_info": { "account_id": "2bysndPtHd", "account_name": "ShUIRjmVQP" }, "order_type": 2906396790063102000, "certificate": [ { "combination_id": "SO0LQS7XwU", "refund_amount": 2982337250931534000, "certificate_id": "VDHw6m65xc", "item_status": 5239943504976592000, "refund_time": 1515061382736177200, "item_update_time": 3789863737038675000, "order_item_id": "y6uWAEVDwv", "fulfil_mode": 1 } ], "count": 8311346457707805000, "receipt_amount": 572639705896183700, "pay_amount": 1948561529231780600, "order_sale_info": { "sale_channel": "YILY2qlCbb", "transfer_nickName": "SI1FZy9nzo", "transfer_uid": "Ma5VGDqK8J", "transfer_douyin_uid": "mDGzyzh7Qr", "order_source": 1, "aweme_id": "InwB1zKUoO", "sale_role": "pQTkAqxIvz" }, "buyer_info": { "buyer_secret_number": "So5zLg7T5n", "buyer_real_phone": "gB2MQglolN", "enc_buyer_phone": "mzE5eOoT4w", "enc_buyer_real_phone": "4XrDZmgIHD", "buyer_phone": "kmoVjeA4ZU" }, "intention_poi_id": "GrVcM1DsO5", "poi_id": "vGefORPmye", "update_order_time": 5852941901796601000, "amount_info": { "deduct_info_list": [ { "source_platform_discount_amount": 7441973935153048000, "source_pay_amount": 2410352365828909000, "voucher_type": 1, "source_sku_id": 1043736090376530000, "source_origin_amount": 9009917754055543000, "source_product_id": 1159471927135120400, "source_order_id": "IsJ9CH3LC4", "groupon_type": 1, "source_brand_discount_amount": 2268290147537127400, "source_sku_name": "aSyNnYHV07", "source_payment_discount_amount": 2758487043025612000, "order_source": 1, "source_selling_price": 79593864083552800, "source_certificate_id": "HHzGFmJF0F", "source_provider_discount_amount": 7353958016106280000, "source_merchant_discount_amount": 108259311316030430, "source_product_name": "jH1IBQ37Up" } ], "activities_fee_amount": 4202952590784809000, "platform_deliver_freight_fee": 6900909611903748000, "deduct_amount": 1712978459542539000, "provider_discount_amount": 116547030243115230, "origin_amount": 8082637165545077000, "freight_pay_amount": 305681782408259800, "platform_discount_amount": 2940301947625842700, "sale_price": 2187561926097183700, "pay_discount_amount": 2929027130500747000, "merchant_deliver_freight_fee": 327471969474923970, "commission_amount": 5263693900525344000, "product_origin_amount": 306844009457300200, "brand_discount_amount": 7570188889763485000, "pay_amount": 8476834962786121000, "merchant_discount_amount": 2019412096112642600, "estimated_order_income": 1691026042385658600 }, "third_sku_id": "7xCEAkxwrS", "sku_name": "aFH94zEfil", "original_amount": 1428097963541025800, "discount_amount": 9181290926625097000, "delivery_info": { "deliver_model": 2764667608369656000, "shop_number": "qlz0SWQdmt", "is_book": false, "user_expect_time": "vWRehbQDFK", "sys_expect_time": "v8eiXpGKkq", "remark": "xYhgCTdZxM", "table_ware": "P7UfPX1RWQ" }, "anchor_id": 4149734334272204000, "pay_time": 2600811927844738600, "contacts": [ { "name": "fNUxaH0TsC", "phone": "bQstYnIBTO", "phone_encrypt": "q2PNQEVjkQ", "enc_name": "MuvQqvYWtQ", "enc_phone": "r5S2EQ7dXa", "enc_phone_encrypt": "4deCSiKzyc" } ], "discounts": [ { "brand_discount_amount": 8457022587365815000, "discount_type": 657885793774461000, "discount_amount": 2601877702799298000, "merchant_discount_amount": 4177871606032176600, "platform_discount_amount": 6710846761214697000, "provider_discount_amount": 5077362893483697000, "idle_time_info": { "idle_time_limit_type": 1, "WriteOffTimeLimit": { "WriteOffEndTime": 8494128235009775000, "DailyTimeRangeList": [ { "EndTime": "q6jDD53XqR", "StartTime": "2yFlT9zStE" } ], "RelativeTime": { "RelativeTimeType": 1, "RelativeTime": 6789210115088455000 }, "WeekDayList": [ 1 ], "WriteOffStartTime": 1339157387414798800 } } } ], "performance_ticket_info": { "entry_type": 284716456691850100, "ticket_type": 4087609230495978500, "show_time": 1875457672210853600, "ticket_area": "opwhjJJ97w" }, "payment_discount": 7955456408872975000, "receiver_info": { "town": "0iRzbziB4G", "receiver_real_phone": "AJQucZOxKE", "city": "5OcblgeTuH", "location_name": "t1C75mvoJI", "enc_door_plate_num": "FRdPcY5iyF", "location_address": "5Ey8FZjHkA", "lat": 0.5056317256331221, "enc_receiver_name": "LmxVL4byCs", "district": "UUrQyUrKah", "enc_location_address": "N4k4TU7Ixz", "enc_receiver_real_phone": "vsxMfIO5M1", "secret_number": "tODt5WFXpz", "province": "nrkTTJds2l", "enc_receiver_phone": "EGK5awiWfm", "receiver_phone": "pVixqDiXKI", "door_plate_num": "3GcyhRpIpN", "lng": 0.46682054489595537, "receiver_name": "y7A95XkFeD" }, "is_deliver_later": false, "buyer_reserve_info": [ { "enc_credential_numb": "SDnOstQvuu", "enc_name": "zYUgRPmEeW", "credential_type": 2973109396134722600 } ], "craftsman_uid": "usjtYRjOYX", "user_id": 7028011453227234000, "order_id": "ezgUqwxp2T", "poi": { "poi_id": "wdgv5jFIyb", "poi_name": "t3JcrTFg2D", "url": "JvWfOeiwPi" }, "order_status": 7801634368845187000, "products": [ { "third_sku_id": "67OkQGAiN0", "snapshot_product": { "product_attr": { "voucher_par_type": 1, "dynamic_par_rule": { "dynamic_par_max_amount": 3754852219667101000, "dynamic_par_rule_item_list": [ { "deductible_amount": 326683209781625800, "day_of_week": [ 1 ], "time_period": { "use_end_time": "YAjKS7mXlk", "end_time_is_next_day": false, "use_start_time": "kxSwnFQubi" } } ], "dynamic_par_rule_desc": "fMZvlZJ4So", "dynamic_par_min_amount": 795184624503424900 }, "show_channel": 1, "advance_purchase_struct": { "purchase_type": 1, "time_detail": [ { "time": 6797701615575319000, "time_type": 1 } ] }, "combo_package_verify_limit_struct": { "type": 1, "product_id_index": { "7805805315307332137": 1394738314064907800 } } }, "tag_info_list": [ { "TagKey": "yWX066EU9i", "TagName": "FBcydcXA3u", "TagValue": "Na6PL6qzZx" } ] }, "product_origin_amount": 5010685643141684000, "product_id": "lz2NhPcKXp", "num": 42199342417450710, "commodities": [ { "items": [ { "attr_list": [ "pvtDA4CB9Z" ], "sku_attr_list": [ { "num": 3451961322632386600, "attr_name": "7UH0PhcGed" } ], "desc": "4W11VQBlLS", "count": 2242663520169167600, "name": "pogeOBuwzb", "unit": "5zzhdIEV9N", "price": 5151491233904246000, "item_tag": "9gcLRML6SY" } ], "group_name": "axaHFLhkDy", "total_count": 1900305531697845000, "option_count": 6788410307545838000 } ], "ext_product_id": "1nd3hhBDRP", "origin_amount": 9200300851661839000, "sku_id": "jiDyF9s56R", "sku_sale_specs": [ { "spec_name": "wVeyiJNDky", "spec_value": "W6tFTiKdSC" } ], "product_name": "GNOvgBoF9T" } ], "sub_order_amount_infos": [ { "receipt_amount": 8690987720989354000, "discount_amount": 4404662964245792300, "discounts": [ { "brand_discount_amount": 3790318581550842000, "discount_type": 8665661957442005000, "discount_amount": 2643081861435330000, "merchant_discount_amount": 8921866271687537000, "platform_discount_amount": 2027459426000191200, "provider_discount_amount": 7181121219405935000, "idle_time_info": { "WriteOffTimeLimit": { "WeekDayList": [ 1 ], "WriteOffStartTime": 1429549413350818800, "WriteOffEndTime": 2601184991304357400, "DailyTimeRangeList": [ { "StartTime": "Q4GumC6He5", "EndTime": "9Z6LxGJObh" } ], "RelativeTime": { "RelativeTimeType": 1, "RelativeTime": 5345874799689826000 } }, "idle_time_limit_type": 1 } } ], "sub_order_id": "aIgBXnKv4L", "origin_amount": 3184753542445606400, "combination_id": "j56lzNUd2s", "pay_amount": 6565145644233945000, "sub_order_type": 7161500859429588000 } ], "create_order_time": 6582963280872687000, "pay_bill_info": { "order_source": 1, "total_pay_amount": 2529122407024669700, "is_timely_pay_bill": false }, "sku_id": "yqpV8XT9Xz", "open_id": "wu0STRuu6W", "reservation_gift": { "reserved_gift_content": "l7kzeVXbtv", "has_reserved_gift": false, "reserved_gift_quantity": "HPdAY7kIwO" } } ], "page": { "page_num": 6102227695526657000, "page_size": 467518555465246800, "total": 6889288259331454000 }, "error_code": 0, "description": "" } }
错误码
| HTTP 状态码 | 错误码 | 错误码描述 | 排查建议 |
|---|---|---|---|
| 200 | 2190002 | access_token无效 | 调用接口重新生成access_token |
| 200 | 2190004 | 应用未获得该能力, 请去https://open.douyin.com/申请 | 应用申请接口权限 |
| 200 | 2190008 | access_token过期,请刷新或重新授权 | 规范token刷新机制,检查是否有测试环境在同步刷新token |
| 200 | 2119001 | 参数不合法 | 更换参数 |
| 200 | 2119002 | 系统繁忙,请稍候再试 | 重试 |
| 200 | 2119003 | 请求太过频繁,请稍后再试 | 重试 |
| 200 | 2119005 | 应用未获商家授权 | 联系合作商家在商家后台发起授权,并在服务商后台同意授权 |
| 200 | 3000001 | 根据实际业务错误返回 | 对照接口文档规范参数并重试 |
| 200 | 4000001 | 根据实际业务错误返回 | 补充参数 |
| 200 | 4000002 | 根据实际业务错误返回 | 对照接口文档规范参数并重试 |
| 200 | 5000001 | 根据实际业务错误返回 | 联系抖音处理 |
| 200 | 2100001 | 未知错误 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
| 200 | 2100004 | 系统繁忙,此时请开发者稍候再试 | 重试接口,重试3次仍报错联系抖音生活服务技术支持 |
| 200 | 2100005 | 参数不合法 | 更换参数 |
| 200 | 3000001 | 以实际错误信息为准 | |
| 200 | 5000001 | 服务器打瞌睡了,请稍后再试。 |
附录
(1)订单维度订单状态
order | 状态 | 状态定义 |
0 | 初始化 | 创单初始值 |
100 | 待支付 | 创单成功,未完成支付,15min待支付等待期 |
101 | 支付取消 | 用户取消支付或超时未支付 |
200 | 已支付 | 用户完成支付 |
201 | 待使用 | 发码成功,商品还未使用或完成预约 |
1 | 已完成 | 订单完成履约或者全部退款 |
(2)预售-券维度的订单状态
value | B端 | 状态语义 | 驱动角色 |
0 | 初始化 | 创单初始值 | - |
100 | 待使用 | 该商品未发生预约、预订失败回滚 | 系统 |
200 | 预订中 | 用户正在确认该商品的预订单 | 商户 |
201 | 已预订 | 用户已确认预约信息,契约达成 | 用户 |
300 | 退款中 | 发起退款流程 | 用户/商户/系统/客服 |
301 | 已退款 | 退款成功 | 系统 |
400 | 履约中 | 已到履约时间,订单开始履约 | 系统 |
401 | 已履约 | 该商品完成履约 | 系统 |
(3)团购-券维度的订单状态
value | B端 | 状态语义 | 驱动角色 |
0 | 初始化 | 创单初始值 | - |
100 | 待使用 | 该商品未发生预约、预订失败回滚 | 系统 |
300 | 退款中 | 发起退款流程 | 用户/商户/系统/客服 |
301 | 已退款 | 退款成功 | 系统 |
400 | 履约中 | 已到履约时间,订单开始履约 | 系统 |
401 | 已履约 | 该商品完成履约 | 系统 |
