WeChat Pay Open Platform

Return Home / Customs Declaration / Query Customs Declaration API

Query Customs Declaration API

Latest update time：2020.06.02 Release notes

Merchants query additional order information submitted and declaration status by order No.

API intro

Request Url: https://apihk.mch.weixin.qq.com/global/v3/customs/orders

Request method:GET

API rules：https://wechatpay-api.gitbook.io/wechatpay-api-v3/

Applicable object:Common mode

path parameter is a path parameter.

query parameter needs to be passed in the request URL.

body parameter needs to be passed in the request JSON.

Parameter Settings

Name	Variable Name	Type	Required	Description
Institution APPID	appid	String(32)	Yes	querySpecifies Official Account ID assigned by WeChat Example：wxd678efh567hg6787
Merchant ID	mchid	String(32)	Yes	query pecifies Merchant ID assigned by WeChat Payment Example：1230000109
Order type	order_type	String(16)	Yes	query Select one of the four order types: out_trade_no - Merchant order No. transaction_id - WeChat Pay order No. sub_order_no - Merchant sub-order No. sub_order_id - WeChat sub-order No. Example：out_trade_no
Order No.	order_no	String(32)	Yes	query Specify an order No. depending on the selected order type. Example：20150806125346
Customs	customs	String(32)	Yes	query Customs for declaration. For the enumerated values, refer to Parameter Specifications Example：SHANGHAI_ZS
Offset	offset	int	No	query CA non-negative integer, which indicates the start position of requested resources, starting from 0. Optional. It is 0 by default. Example：1
Maximum number of returned records	limit	int	No	query A positive integer, which indicates the maximum number of resource records that can be returned for this request. Optional. The suggested default value is 20. Example：20

Return Data

Normal return

Name

Variable Name

Type

Required

Description

Institution APPID

appid

string(32)

Yes

Official Account ID assigned by WeChat
Example：wxd678efh567hg6787

Merchant ID

mchid

string(32)

Yes

Merchant ID assigned by WeChat Pay
Example：1230000109

WeChat order No.

transaction_id

string(32)

Yes

Order No. returned by WeChat Pay
Example：1000320306201511078440737890

Verification institution

verify_department

string(16)

Yes

Verification institution code
UNIONPAY：Unionpay
NETSUNION：NetsUnion
OTHERS：Others
Example：UNIONPAY

Transaction ID from verification institution

verify_department_trade_id

string(64)

Yes

Transaction ID from the verification institution (such as UnionPay) for the merchant to register at the customs
Example：2018112288340107038204310100000

Offset

offset

int

Yes

The offset from which the resource records are returned for the request
Example：0

Maximum number of returned records

limit

int

Yes

The maximum number of returned records for the request
Example：20

Total number of query results

total_count

int

Yes

Total number of query results
Example：1

+ Customs declaration data packet

data

Array

Yes

Total number of query results

Name	Variable Name	Type	Required	Description
Merchant sub-order No.	sub_order_no	string(32)	No	Merchant sub-order No. Example：20150806125346
WeChat sub-order No.	sub_order_id	string(32)	No	WeChat sub-order No. Example：20150806125346
WeChat sub-order No.	mch_customs_no	string(32)	No	Customs registration No. of the merchant Example：1234567
Customs code	customs	string(32)	Yes	Customs code. See Parameter Specifications. Example：SHANGHAI_ZS
Currency	fee_type	string(3)	No	The value is always CNY. Example：CNY
Sub-order amount	order_fee	int	No	Sub-order amount (in 0.01 CNY) Example：888
Tariff	duty	int	No	Tariff (in 0.01 CNY). It is not required and will not be submitted to the customs. Example：888
Logistics fee	transport_fee	int	No	Logistics fee (in 0.01 CNY) Example：888
Product price	product_fee	int	No	Product price (in 0.01 CNY) Example：888
Declaration status	state	string(32)	Yes	Declaration result status code PROCESSING：Declaration in process UNDECLARED：Undeclared SUBMITTED：Modified but not declared SUCCESS：Declaration succeeded FAIL：Declaration failed EXCEPT：Exceptional customs API Example：PROCESSING
Declaration result description	explanation	string(128)	No	Description of declaration results. The failure reason will be displayed in case of failure or exception. Example：The payment order already exists and is in a non-refund status.
Last update time	modify_time	string(32)	Yes	Last update time, which is obtained from the WeChat server. Example：2015-09-01T10:00:00+08:00

Abnormal return

Name

Variable Name

Type

Required

Description

Return Status
Code

return_code

String(32)

Yes

Error code. See the error code list for the enumerated values.
Example：INVALID_REQUEST

Returned message

message

String(256)

Yes

Returned message. If not empty, it presents the cause of the error.
Example：Parameter format verification error

+Detailed error description

detail

Object

It is returned when code is PARAM_ERROR. Details will be described below

Name	Variable Name	Type	Required	Description
Field that indicates the incorrect parameter	field	string(256)	Yes	If the incorrect parameter is in the JSON for request body, the JSON Pointer pointing to this parameter is entered. If the incorrect parameter is in the request URL or querystring, the variable Example：#/properties/payer
Value of the incorrect paramet	value	string(256)	Yes	Value of the incorrect parameter Example：1346177081915535577
Cause of error	issue	string(256)	Yes	Cause of error Example：Inconsistent with XXX
Location of the incorrect parameter	location	string(256)	No	body: The incorrect parameter is in the JSON for request body url:The incorrect parameter is in the request URL. query:The incorrect parameter is in the querystring of the request. Example：body

Example：

Normal return


  {
	"appid": "wxd678efh567hg6787",
	"mchid": "1230000109",
	"transaction_id": "1000320306201511078440737890",
	"verify_department": "UNIONPAY",
	"verify_department_trade_id": "2018112288340107038204310100000",
	"offset": 0,
	"limit": 20,
	"total_count": 1,
	"data": [
  {
	"sub_order_no": "20150806125346",
	"sub_order_id": "20150806125346",
	"mch_customs_no": "1234567",
	"customs": "SHANGHAI_ZS",
	"fee_type": "CNY",
	"order_fee": 888,
	"duty": 888,
	"transport_fee": 888,
	"product_fee": 888,
	"state": "PROCESSING",
	"explanation": "The payment order already exists and is in a non-refund status",
	"modify_time": "2015-09-01T10:00:00+08:00"
  }
	]
  }

Error Codes

Error Codes	Description	Solution
INVALID_REQUEST	No customs declaration for this order.	No declaration is made for this order. Make a declaration before a query.
	The specified record does not exist. Select a different query criterion.	The record to be queried does not exist. Make a query again by a different query criterion.
	Customs information is not configured.	The customs declaration API is only accessible after the customs information has been configured for the merchant. Please configure the customs information by referring to the customs registration guidelines above.
NOAUTH	The merchant has not registered with the current customs	The merchant has not registered with the current customs. Try again after the registration is completed.
NOAUTH	Self-Clearance is not enabled.	Check whether the Self-Clearance tool has been enabled for the merchant ("WeChat Pay Merchants Platform" > "Product Center" > "Apply for Self-Clearance").
PARAM_ERROR	Parameter error	Invalid parameter. The parameter may be incorrect or is missing. Check whether the API parameters have been summited as required.
SYSTEMERROR	System error	Declare again, or contact WeChat Pay Assistant to find out the reason.

WeChat Pay

Feedback

Feedback

Submitted successfully

Feedback

Network exception, please try again later

Customs Declaration API

Query Customs Declaration API

API intro

Parameter Settings

Return Data

Normal return

Abnormal return

Example：

Error Codes

Release notes