查询券状态信息

我的收藏

批量查询一个订单中的券的相关状态信息，比如已核销、已退款等状态。

使用限制

单次查询不能超过 20 个。

接口说明

如果在券码核销的流程中因为某种异常无法确认当前券码的核销状态，则可以通过这个接口查询券的相关状态信息。
只能传入同一个订单下的券列表，不能跨订单查询。

基本信息

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

请求头

参考通用参数

请求参数

名称	类型	是否必填	描述	示例值
order_id	string	是	抖音开平内部交易订单号，该单号通过预下单回调传给开发者服务，长度 < 64byte。	ot123456
item_order_id_list	array(string)	否	交易系统订单号下的商品单号列表。最多支持 20 个商品单传入，超过将报错。如不传，将返回此订单下的所有子单。	["ot123", "ot456"]

名称

类型

是否必填

描述

示例值

order_id

string

是

抖音开平内部交易订单号，该单号通过预下单回调传给开发者服务，长度 < 64byte。

ot123456

item_order_id_list

array(string)

否

交易系统订单号下的商品单号列表。
最多支持 20 个商品单传入，超过将报错。

如不传，将返回此订单下的所有子单。

["ot123", "ot456"]

请求示例

curl --location --request POST 'https://open.douyin.com/api/apps/trade/v2/order/query_item_order_info' \
--header 'Content-Type: application/json' \
--header 'access-token: clt.xxx' \
--data-raw='{
        "order_id": "ot123456",
        "item_order_id_list": [
                "ot123",
                "ot456"
        ]
}'

响应参数

名称	类型	是否必填	描述	示例值
data	object	是	返回数据
extra	object	是	额外信息，参见通用参数

data 信息

名称	类型	是否必填	描述	示例值
item_list	array(object)	是	列表，返回的item单数据

item_list 信息

名称	类型	是否必填	描述	示例
item_order_id	string	是	交易系统商品单号	ot123
item_order_status	number	是	商品单的状态： 0：无效值 1：待支付 2：待使用 3：已核销 4：订单关闭 10：待预约 20：退款中 21：已退款	0
valid_start_time	number	是	商品单的有效开始时间，毫秒级的 Unix 时间戳	1658398122000
valid_end_time	number	是	商品单的有效截止时间，毫秒级的 Unix 时间戳	1658398122000
delivery_time	number	是	商品单的核销时间，毫秒级的 Unix 时间戳	1658398122000
times_card_info	object	否	次卡信息，仅次卡类型会返回

times_card_info

名称	类型	是否必填	描述	示例
total_times	int	required	总计次数	10
usable_times	int	required	可使用次数/剩余次数	4
refund_times	int	required	退款次数(退款中+退款成功)	0
actual_amount_once	int	required	商品单次现价，单位[分]	100

响应示例

正常示例

{
  "data": {
    "item_list": [
      {
        "item_order_id": "item_order_id_example_1",
        "item_order_status": 2,
        "valid_start_time": 1642491214992,
        "valid_end_time": 1642491231992,
        "delivery_time": 1642493214992,
        "times_card_info": {
          "total_times": 2,
          "usable_times": 2,
          "refund_times": 0,
          "actual_amount_once": 100
        }
      },
      {
        "item_order_id": "item_order_id_example_2",
        "item_order_status": 2,
        "valid_start_time": 1642491214992,
        "valid_end_time": 1623491214992,
        "delivery_time": 1642231214992,
        "times_card_info": {
          "total_times": 2,
          "usable_times": 2,
          "refund_times": 0,
          "actual_amount_once": 100
        }
      }
    ]
  },
  "extra": {
    "sub_error_code": 0,
    "sub_description": "success",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 0,
    "description": "success"
  }
}

异常示例

{
  "data": {
    "error_code": 13000,
    "description": "系统错误"
  },
  "extra": {
    "sub_error_code": 13000,
    "sub_description": "系统错误",
    "logid": "2022092115392201020812109511046",
    "now": 1663745962686,
    "error_code": 2191000,
    "description": ""
  }
}

错误码

HTTP 状态码	错误码	描述	排查建议
200	10000	参数错误	参数不符合规范。请根据提示检查参数。
200	13000	系统错误，请重试	内部错误，重试可解决。
200	21047	商品单 id 不合法	检查 item_order_id 是否正确。

下一篇：小程序文档指引