新版淘客订单API是2019年5月24号上线最新的淘宝客订单查询接口，对新版订单接口有问题可以反馈到群里。

和旧版的订单查询接口（http://www.veapi.cn/doc/dingdanchaxunxiazai）相比，有以下特点：

（以下pub端是指淘宝联盟官网pub.alimama.com）

以下是联盟官方汇总的优化点：

1、pub/app/api报表类型、字段概念进行统一，理解成本/追溯问题成本降低

2、本次增加付款时间查询：主要解决淘客诟病，通过订单创建时间，要不断回查历史订单，容易拉不全或遗漏订单

3、增加淘宝付款时间透出：尤其解决大促时淘宝端付款和淘客付款时间对不上，以为丢单的问题

4、增加淘宝子订单编号透出：解决淘客之前用“父订单编号”，不能真正知道每个商品每笔订单的销售情况，尤其和退款订单匹配不上的问题

5、增加“提成”概念：等于之前的收入比率*分成比率，直接帮淘客算好能获得的比率，简单概念

6、pub端将”淘宝客推广明细“和”第三方服务商明细“整合到一起，解决淘客不能一次看全或下全订单的问题

7、切换底层数据表，解决之前订单明细加起来和效果统计数据对不上的问题

8、优化底层性能，解决媒体每秒获取订单受限问题(能承受度变高极多)，日常、大促批量获取订单更顺畅。

【好消息】

淘客订单查询接口新增增量查询的功能，增加参数query_type=4可选值，按照订单更新时间查询，返回值增加出参：更新字段modified_time

订单接口名词解释：

1、订单类型名词：什么是2方订单，什么是3方订单？

2方订单：就是你自己推广的订单，你自己拥有这笔订单完全佣金。

3方订单：就是你推广的客户，在领了你的淘口令或推广链接后，去下单过程中，在购物车上用了别的淘客的红包，导致订单变成别人的，而你只有这笔订单产品普通“通用佣金”的一半，而不是高佣了。

2、订单状态名词：

付款状态：这时订单已付款，等待商家发货。状态值12

订单成功：表示买家确认收货，这时状态值是14，此时一般很快就进入结算，转成状态3，并生成tk_earning_time（结算时间）值，但有的订单收完货后，联盟和商家间没有完成结算，就会导致状态值停留在14，这时返回值就没有tk_earning_time字段。

订单结算：表示在买家确认收货后，联盟和卖家结算完佣金了。这时状态是3。也就是说14状态是在3前面。

注意这时的结算不是联盟和你结算，是和卖家结算。每个月20号联盟才跟你结算佣金。

 一般买家确认收货后就变成结算状态3，少数异常情形，比如淘宝卖家帐户余额不足等，会导致一直卡在14状态值。

订单失效：表示下了单但关闭订单等情形。以及付款后全额申请退款，此时状态值13

订单维权：维权单是指付款后收到货申请部分退款，如退运费，这些订单是维权订单。维权订单依然是成功，具体参下文

3、订单接口可以查询什么样的订单？

目前订单接口不能查询“未付款”的订单，包括下了单但没付款就关闭的订单，

可以查询“已付款订单”。

一、新订单查询接口调用方法：

【调用权限】核心全能接口和订单接口会员卡
【调用接口】

http://api.veapi.cn/tbk/orderdetails?vekey=xx&start_time=...&end_time=.....

【参数详解】

具体参数可以参考官方文档：https://open.taobao.com/api.htm?docId=43755&docType=2&scopeId=16322

本文档和淘宝联盟官方文档在参数名及其大小写上保持一致。

【必知】订单的查询时间跨度：

订单查询时间跨度为“订单开始时间start_time至结束时间end_time查询时长，中间时间段跨度日常要求不超过3个小时，但如618、双11、年货节等大促期间预估时间段不可超过20分钟（推荐使用20分钟），超过会提示错误，调用时请务必注意时间段的选择，以保证能正常调用！

订单查询API最多只能查到三个月内的订单，时间超过3个月的订单获取不到。

【联盟官方推荐的订单获取频率】# 新订单api节省调用量拉取攻略#

订单api支持淘客创建时间、淘客付款时间、淘客结算时间3个查询维度，下面以淘客付款时间为例说明，其它查询维度相似。
如果查询最近20分钟有哪些订单进行了付款，建议选择淘客付款时间，
首次查询时间段设置为最近20分钟（指下面参数中的start_time和end_time时间间距），则系统会按淘客付款时间倒序分页返回订单，下一次拉取时间点向后推移20分钟，
比如00:20拉取00:00～00:19之间的订单，00:40拉取00:20～00:39之间的订单，01:00拉取00:40～00:59之间的订单，
依次类推，拉取一天所有订单。其中，查询时间段越小，性能和实时性会越好。

以下是订单接口参数说明：

start_time 必需参数，订单查询开始时间。需2019-04-23之后的时间点，并且必须小于end_time时间。

                  示例：2019-04-05 12:18:22

end_time 必须参数：订单查询结束时间。需2019-04-23之后的时间点，且必须大于start_time时间。它和start_time时间间距为20分钟或3小时，参考上面说明。

query_type 可选参数（默认值为1）：指查询时间类型，可选值：1-按照订单淘客创建时间查询，2-按照订单淘客付款时间查询，3-按照订单淘客结算时间查询，4-按照订单更新时间（订单增量查询）。

position_index 可选参数（默认值为空）：位点，除第1页之外，其它页都需要传递本参数。用法：本参数把第一页调用的返回值position_index，做为第2页的入参即可。同样，第2页的position_index返回值，做为第3页的入参。

page_no 可选参数（默认值1）：页码

page_size 可选参数（默认值20，最大值100）：每页返回的订单最大笔数

member_type 可选参数（默认值为空，表示所有角色）：推广者角色类型,2:二方，3:三方，不传则表示所有角色。

tk_status 可选参数（默认值为空，表示所有状态）：淘客订单状态：12-付款，13-关闭，14-确认收货，3-结算成功;不传，表示所有状态。注意：如果一个订单全额退款，这时订单是失效关闭状态，虽然它付款过，但此时关闭状态，你用tk_status=12是查不到的，必须用tk_status=13或不用这个参数才能查的到。

jump_type 可选参数（默认值1）：跳转类型，当向前或者向后翻页必须提供,-1: 向前翻页,1：向后翻页

order_scene 可选参数（默认值1）：场景订单场景类型，1:常规订单，2:渠道订单，3:会员运营订单，默认为1

sessionkey：多用户专用。如果您的会员卡是多用户版订单查询接口，若要查不同的帐号，请提供该帐号授权的sessionkey值，

【特别提示】

order_scene默认值1是查常规订单，如果您想查渠道订单，务必设置order_scene=2，

同理，查会员订单order_scene=3。

否则不会返回relation_id和special_id值。

二、订单查询接口调用频率：

【重要】在调用订单接口前，请了解一下 要如何安排订单查询频率？

三、新订单接口返回值：

返回值字段类型参考官方文档：https://open.taobao.com/api.htm?docId=43755&docType=2&scopeId=16322   

注意新旧订单接口部分订单字段名有变动。

接口返回的订单默认是按订单创建时间倒序。

关于订单佣金如何计算，参考下文第4节。

【特别强调】为什么我的获取的订单号和联盟后台不一致？

以PHP开发为例，因为订单返回值中的订单号是长整数，有的人会发现：把接口返回值转成数组时，PHP把订单号转成科学计数法，导致最终保存的订单号和联盟上的订单一致。解决办法：

转数组时用 json_decode($resp, true , 512 , JSON_BIGINT_AS_STRING); 同时，你的数据库保存订单号字段要用varchar类型。

其它语言也存在这个问题，比如node.js，请自行百度该语言处理长整型数据。

tip: 在浏览器显示时，请使用 json-handle 插件，才能正确显示订单号，其它插件不能正确显示订单号。

【订单返回值】

字段含义参考官方文档 https://open.taobao.com/api.htm?docId=43755&docType=2&scopeId=16322 ：

双11时注意这几个字段：

tk_deposit_time 预售时期，用户对预售商品支付定金的付款时间，可能略晚于在淘宝付定金时间

tb_deposit_time 预售时期，用户对预售商品支付定金的付款时间

deposit_price 预售时期，用户对预售商品支付的定金金额

【附】如何判断双11预售订单？

参考http://www.veapi.cn/taokelianmeng/529.html 

返回值字段变动官方公告：

淘宝客私域用户管理产品上线渠道专项服务费后，订单API在5月22日进行相关字段更新。变更信息如下：

①新增“渠道专项服务费”、“渠道专项服务费率”字段；

②原“专项服务费”、“专项服务费率”字段名称更新成“内容专项服务费”、“内容专项服务费率”

附1：

[新返回值]：新增字段 flow_source，值为“自主推广”，就表示比价订单。

附2：

淘宝联盟订单查询接口的子订单号trade_id和父订单号trade_parent_id是什么区别？

参考：http://www.veapi.cn/taokelianmeng/273.html 

四、新版淘宝联盟订单接口如何计算佣金？

新版订单接口返回值中直接就已经有佣金计算字段了，分别是“付款预估收入pub_share_pre_fee”和“结算预估收入pub_share_fee”，分别适用于订单在结算前和结算后。

直接取这2个字段即可得到佣金计算值：

1、订单结算前：

pub_share_pre_fee 付款预估收入=付款金额*提成。

指买家付款金额为基数，预估您可能获得的收入。因买家退款等原因，可能与结算预估收入不一致

2、订单结算后：

pub_share_fee 从结算佣金中分得的收入，结算预估收入=结算金额*提成。

以买家确认收货的付款金额为基数，预估您可能获得的收入。因买家退款（维权订单，参考下文第6节）、违规推广等原因，可能与您最终收入不一致。最终收入以月结后您实际收到的为准。

如果有进行内容场景推广，还需要减去专项的技术服务费用，公式：

1、订单结算前：

pub_share_pre_fee - tk_commission_pre_fee_for_media_platform （预估专项服务费）

2、订单结算后：

pub_share_fee - tk_commission_fee_for_media_platform （结算专项服务费）

五、如何查询渠道订单？为什么订单中没有渠道id（relation_id）：

很多客户困惑于怎么查询渠道订单，或不知道为什么订单中没有渠道ID（relationId），在这里统一说明：

1、如何生成渠道订单？必须在高佣转链环节（即下单人领券阶段）满足2个条件：A、传递relationId参数，B、PID参数必须使用渠道专属PID。

满足这2个条件的高佣转链淘口令或推广链接，下的订单才是渠道订单。

渠道专属PID在哪找？

进入联盟后台，在“推广管理—>渠道管理—>渠道专属推广位”可看到专属PID，如果没有可以在这里创建

2、正常下单：首先要确保你有渠道订单，可以在淘宝联盟后台“效果报表—>渠道效果报表”那查看，如果联盟后台没有看到渠道订单，可能有2个原因：A、可能第一步转链环节参数不正确，请检查。B、客户下单过程出现异常，比如用了别人的红包，比如双11的超红。

3、查订单时加参数order_scene=2：当联盟后台效果报表看到渠道订单后，就可以查到渠道订单relationId。

4、如果订单是第三方订单，还需要加参数member_type。

5、注意时间参数默认是订单创建时间，而联盟后台默认显示是付款时间（需要下载EXCEL会看到创建时间），当您没有查询到订单，请注意本参数类型是否正确。

总之，调试时，在保证有渠道订单的情形下，若未找到渠道订单，把所有参数都细细检查一下就可以了。

六、如何处理维权订单（维权指申请退款的订单）：

现在维权订单（维权即有退款订单）主要是靠新订单接口中refund_tag字段为1时，就多多注意这些维权订单，

暂时还没有办法通过接口来获取维权订单，订单接口不会根据维权情况变更订单金额和订单状态（也就是说，即使客户维权成功退款一部分金额，但订单接口的金额和订单状态仍然不会变化），因此暂时无法通过接口来判断订单的维权详情。目前接口只能做到返回refund_tag字段告知是维权订单。

您可以到联盟后台“效果报表—订单明细报表—维权退款订单”对照。下载EXCEL导入到你的系统进行处理。这需要你开发相应的系统解析EXCEL文件。

对于渠道维权订单，你可以用维权接口查询，参考http://www.veapi.cn/doc/taokeweiquandingdanjiekou，该接口还不能查普通维权订单。

七、如何区分饿了么订单？

订单API里有个字段 order_type 标了“饿了么”的，可以筛选出“饿了么”订单。

这里有一个饿了么从“推广—下单—查订单”的全过程演示：

http://www.veapi.cn/taokelianmeng/482.html

另外，饿了么订单号也比普通淘客订单的订单号短，比如“2100042665”，

附：新零售和餐饮订单有什么不同？

可以按照一级类目来区分。

【饿了么餐饮一级类目】快餐便当、特色菜系、全球美食、小吃夜宵、甜品饮品、香锅火锅

【饿了么新零售一级类目】商店超市、鲜花绿植、医药健康、水果、厨房生鲜

八、错误码：

具体错误码参考 http://www.veapi.cn/doc/taobaokeapijiekoucuowuma

附：淘客订单接口相关参考：

《订单报表名词解释》http://www.veapi.cn/taokelianmeng/428.html

《有时淘宝联盟APP有订单而淘宝联盟PC端没有？》http://www.veapi.cn/taokelianmeng/432.html

《订单接口为什么有时获取的订单数量变少了？》http://www.veapi.cn/taokelianmeng/423.html 

《淘宝订单查询接口的返回值中，哪个是付款字段？》http://www.veapi.cn/taokelianmeng/264.html 

《淘宝联盟订单查询接口的子订单号和父订单号是什么区别？怎样区分每个订单》http://www.veapi.cn/taokelianmeng/273.html 

《如何区分订单是哪个客户下单的？如何用PID绑定订单和客户？》http://www.veapi.cn/taokelianmeng/265.html

《淘宝联盟APP中订单预估收入和详情页预估收入有误差？》http://www.veapi.cn/taokelianmeng/348.html

《淘宝客维权订单接口在退款过程状态值怎么变？》http://www.veapi.cn/taokelianmeng/373.html