订单查询
收藏
我的收藏通过接口查询指定范围的订单列表及订单详情:
1、查询指定状态的订单列表,用于对账或差异单最新状态确认;
2、查询指定用户的订单列表,用于积分计算、订单展示;
3、查询指定订单详情,用于接口补偿处理。
开票说明
尊敬的商家,依据税务规则与《抖音生活服务平台商户合作协议》的约定,如用户向商家申请开具发票,商家应按照用户实际支付金额向用户开具相应金额的发票。用户的实际支付金额可参考订单查询pay amount字段展示的具体金额(用户实际支付金额,不含平台等其他方补贴的金额)。
针对平台补贴需向平台开具增值税发票,请勿开具给用户。若商家向用户超额开具发票,由此导致的损失及税务风险需由商家自行承担
接口 SLA
指标 | 数值 |
可承载最大qps | 500 |
响应耗时pct99 | 1s |
服务目标可用性 | 99.9% |
接口说明
- 服务商通过接口查询订单详情,支持三种查询方式:
- 根据订单 ID 或第三方订单号,查询对应订单详情,入参:订单 ID/第三方订单号、商户 id;
- 根据订单状态和商户 id,查询指定时间内该商户下的订单列表,入参:商户 id、订单状态、创单起止时间/修改起止时间;
- 根据用户 id 和商户 id,查询某用户在该商户下的所有订单,入参:商户 id、用户 id、创单起止时间/修改起止时间;
- 支付后未发码/发码失败订单查询方式:限定订单状态为“已支付”,如用户下单后超过 10 分钟未发码会发起退款;
- 退款申请待审核订单查询方式:限定券状态为“退款中”,如退款状态未响应超过 72 小时会自动退款。
基本信息
名称 | 描述 |
---|---|
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"
Query展开全部子属性
account_id必填String
来客商户根账户ID
page_num必填Int32
页数从1开始,如果使用page分页,页数*大小不能超过10000
page_size必填Int32
页大小,取值范围1~100
create_order_end_timeInt64
创单结束时间(秒时间戳,创单起止时间必须同时传入)
create_order_start_timeInt64
创单起始时间 (秒时间戳,创单起止时间必须同时传入)
cursorList
根据游标滚动请求,直到返回结果数量小于请求的size或未返回search_after结束;首页传"0",之后传返回参数中的CursorValue string数组拼接的string,如CursorValue返回参数["0","1"],则传"0,1";如果传入此参数,会优先使用cursor翻页,而不是page翻页
展开子属性
ext_order_idString
开发者系统中的订单号
get_secret_numberBool
是否需要查询配送信息
open_idString
抖音用户id
order_idString
抖音生活服务订单ID
见抖音-团购频道-订单详情
order_statusInt32
订单状态
update_order_end_timeInt64
修改结束时间(秒时间戳,修改起止时间必须同时传入)
update_order_start_timeInt64
修改起始时间 (秒时间戳,修改起止时间必须同时传入)
请求示例
curl --location --request GET '/goodlife/v1/trade/order/query/?update_order_end_time=6848566238330650547&ext_order_id=BZWiOqRwmk&open_id=IwRkPsJt6m&update_order_start_time=5176814351276506342&get_secret_number=false&page_size=1529361527615178323&create_order_start_time=1348886143060842655&account_id=Dib1xsUleY&order_status=1010595783034910267&order_id=6eKhYBm2VD&page_num=7898256632316184657&create_order_end_time=5333812495820204773&cursor=[dJiYnCVG1X]' \ --header 'content-type: application/json' \ --header 'access-token: 0801121846735352506a356a6' \
响应参数
Body展开全部子属性
dataStruct
展开子属性
extraStruct
展开子属性
响应示例
正常响应示例异常响应示例
{ "data": { "orders": [ { "amount_info": { "activities_fee_amount": 9147111285688053000, "brand_discount_amount": 883360464124555100, "commission_amount": 1769723996664574500, "estimated_order_income": 1517859895821544400, "freight_pay_amount": 4032201118086756400, "merchant_deliver_freight_fee": 8189226865575274000, "merchant_discount_amount": 1605424424180584700, "origin_amount": 1986434555994729000, "pay_amount": 2315769497397148700, "pay_discount_amount": 8325105401868669000, "platform_deliver_freight_fee": 1459105318755943200, "platform_discount_amount": 4623116634679010000, "product_origin_amount": 7309222695820623000, "provider_discount_amount": 7180116378197532000, "sale_price": 2511694666623169500 }, "anchor_id": 2264616610925040400, "buyer_info": { "buyer_phone": "5qUntKVTrG", "buyer_real_phone": "YFt4RwbqMV", "buyer_secret_number": "szvYWKIBrr" }, "certificate": [ { "certificate_id": "QbxlGb9u5p", "combination_id": "pIOcY6CeO7", "item_status": 3111004060496235000, "item_update_time": 2531249638604416000, "order_item_id": "n5iVApvTzs", "refund_amount": 1763216999154579500, "refund_time": 6912978293656716000 } ], "contacts": [ { "name": "zBVaXKSIZR", "phone": "264Gx7wa4m", "phone_encrypt": "wTwI4AhD5a" } ], "count": 5179297770218131000, "create_order_time": 3342330577230231600, "delivery_info": { "deliver_model": 6079028265351953000, "is_book": false, "remark": "jG6x9MkdDo", "shop_number": "Ki70T8UoxX", "sys_expect_time": "uLRXGLfAkv", "table_ware": "fUJeUOt4PM", "user_expect_time": "b6yAHklYoM" }, "discount_amount": 4180963141889158700, "discounts": [ { "brand_discount_amount": 4034021270054597000, "discount_amount": 5435888835003855000, "discount_type": 2687499662142840000, "idle_time_info": { "write_off_time_limit": { "daily_time_range_list": [ { "end_time": "8UXpkYp53H", "start_time": "UwosYVd6TM" } ], "relative_time": { "relative_time": 6777788116687764000, "relative_time_type": 1 }, "week_day_list": [ 1 ], "write_off_end_time": 1022787395004234000, "write_off_start_time": 3542913573500622000 }, "idle_time_limit_type": 1 }, "merchant_discount_amount": 1512555531921883100, "platform_discount_amount": 9015924755398764000, "provider_discount_amount": 2891033597185247000 } ], "intention_poi_id": "hx1gPHGsoM", "is_deliver_later": false, "merchant_info": { "account_id": "7Y4vvVtNQg", "account_name": "X7jkhRAVi6" }, "open_id": "pzN5qu1u9t", "order_id": "76jiVYMDDT", "order_status": 4967271894712928000, "order_type": 5461835456708876000, "original_amount": 8166094681532748000, "pay_amount": 2405268923265303600, "pay_time": 7183826629119172000, "payment_discount": 7146911719502625000, "poi": { "poi_id": "MNrci7Vz76", "poi_name": "QNSO1vkxRL", "url": "qP6luoDm66" }, "poi_id": "cH8Oz5YR6V", "products": [ { "commodities": [ { "group_name": "MArFFMHPl0", "items": [ { "attr_list": [ "mrOAeMZN5A" ], "count": 6757229571991424000, "desc": "TRVWhBKb0q", "item_tag": "WAjkD0w4Ln", "name": "SR2GXxNolD", "price": 5623137922230985000, "sku_attr_list": [ { "attr_name": "3uaIegI4LG", "num": 6108460088799259000 } ], "unit": "THZoBlwGE1" } ], "option_count": 2238112139263541800, "total_count": 9046424274172208000 } ], "ext_product_id": "iNeU5ipjba", "num": 5192129801700568000, "origin_amount": 7854060090190682000, "product_id": "v2ZRKxAa4Z", "product_name": "YFHBcFTj04", "product_origin_amount": 5615536259697520000, "sku_id": "oSi12Tz1Tn", "snapshot_product": { "product_attr": { "dynamic_par_rule": { "dynamic_par_max_amount": 8814055859616470000, "dynamic_par_min_amount": 1807541147899435000, "dynamic_par_rule_desc": "zEpY9ERKho", "dynamic_par_rule_item_list": [ { "day_of_week": [ 1 ], "deductible_amount": 8188014896326283000, "time_period": { "end_time_is_next_day": false, "use_end_time": "PGySmqQU8n", "use_start_time": "TqMhF2qpMY" } } ] }, "show_channel": 1, "voucher_par_type": 1 }, "tag_info_list": [ { "tag_key": "GfjYWQZeQC", "tag_name": "hV4oFLJJW4", "tag_value": "wErfTejRIu" } ] } } ], "receipt_amount": 7631182633980670000, "receiver_info": { "city": "G2nbEo029k", "district": "MSlwWLThbR", "door_plate_num": "4ecBVhfmIy", "lat": 0.8989735375830186, "lng": 0.05792573254571142, "location_address": "n7AnJPhvEj", "location_name": "Hr0IM3Ey3J", "province": "ZO0F8SR8Yo", "receiver_name": "STR9td4pXh", "receiver_phone": "84sBLZBWsJ", "receiver_real_phone": "ScCM91p6cr", "secret_number": "EmsnHjAuCq", "town": "rBIGj3iIeg" }, "room_id": "WOfMKH85rG", "sku_id": "33xuN9gIiZ", "sku_name": "vnW6u1GPqU", "sub_order_amount_infos": [ { "combination_id": "RUa6JVUCUd", "discount_amount": 7467431600057043000, "discounts": [ { "brand_discount_amount": 6742633826629587000, "discount_amount": 4654750488860239000, "discount_type": 1839233156515625500, "idle_time_info": { "write_off_time_limit": { "daily_time_range_list": [ { "end_time": "3NBbqpezG9", "start_time": "gMfRCIxJW9" } ], "relative_time": { "relative_time": 7667229763254560000, "relative_time_type": 1 }, "week_day_list": [ 1 ], "write_off_end_time": 911978315197530200, "write_off_start_time": 2783437286892653000 }, "idle_time_limit_type": 1 }, "merchant_discount_amount": 4149660171508643300, "platform_discount_amount": 4462539489877701600, "provider_discount_amount": 1669237537254993000 } ], "origin_amount": 7264653626911115000, "pay_amount": 7658898346564793000, "receipt_amount": 2218104472554594600, "sub_order_id": "UMz1MrjBI1", "sub_order_type": 651614340746745300 } ], "third_sku_id": "qKPz6iDU3p", "update_order_time": 3568384846158681600, "user_id": 5258546185415258000 } ], "page": { "page_num": 8830103158112420000, "page_size": 9051850707462125000, "total": 2550075684454217700 }, "search_after": { "all_cursor_value": [ [ "OTEqiGWh30" ] ], "cursor_value": [ "u9y3E02H8l" ], "size": 6374474814240391000 }, "error_code": 0, "description": "" }, "extra": { "error_code": 0, "description": "", "sub_error_code": 0, "sub_description": "", "logid": "20241203113138164E5B3B64DB44003F1A", "now": 1733196698 } }
错误码
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 | 5000001 | 服务器打瞌睡了,请稍后再试。 | |
200 | 3000001 | 以实际错误信息为准 |
附录
(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 | 已履约 | 该商品完成履约 | 系统 |
点击纠错