Product Documentation General instructions Access Guidelines FAQs

Modify Customs Declaration Info

Update Time：2025.02.20

This API allows merchants to modify additional order information.

Tips：

This API will generate new data for declaration while invalidating the old application data. There is no need to call the re-push API. This API can be used to modify only the merchant's customs registration No., tariff, sub-order amount, logistics fee, and product price. If the merchant's customs registration No. is modified, the new registration No. and registered name of the merchant will be obtained for declaration again.

API intro

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

Request method: PATCH

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.

Request Parameters

Name	Variable Name	Type	Required	Description
Institution APPID	appid	String(32)	Yes	body Specifies Official Account ID assigned by WeChat Example：wxd678efh567hg6787
Merchant ID	mchid	String(32)	Yes	body Specifies Merchant ID assigned by WeChat Payment Example：1230000109
Merchant order No.	out_trade_no	String(32)	Yes	body internal order No. of the merchant system. Should be within 32 characters and can only contain numbers, uppercase and lowercase letters, and _-\|*@. It is unique for a merchant ID. Example：20150806125346
WeChat order No.	transaction_id	String(32)	Yes	body Order No. returned by WeChat Pay Example：1000320306201511078440737890
Customs	customs	String(32)	Yes	body Customs for declaration. For the enumerated values, refer to Parameter Specifications Example：SHANGHAI_ZS
Merchant's customs registration No.	merchant_customs_no	String(32)	Yes	body Customs registration No. of the merchant Example：123456
Tariff	duty	int	No	body Tariff (in 0.01 CNY). It is not required and will not be submitted to the customs. Example：88
Merchant sub-order No.	sub_order_no	String(32)	No	body Merchant sub-order No. It is required if there is a split order. Example：20150806125346
Sub-order amount	order_fee	int	No	body Sub-order amount (in 0.01 CNY). Cannot exceed the original order amount. order\_fee=transport_fee+product_fee (payable amount = logistics fee + product price). It is required if there is a split order Example：888
Logistics fee	transport_fee	int	No	body Logistics fee (in 0.01 CNY). It is required if there is a split order. Example：888
Product price	product_fee	int	No	body Product price (in 0.01 CNY). It is required if there is a split order. Example：888

Example：

1{
2 "appid": "wxd678efh567hg6787",
3   "mchid": "1230000109",
4   "out_trade_no": "20150806125346",
5   "transaction_id": "1000320306201511078440737890",
6   "sub_order_no": "20150806125346",
7   "customs": "SHANGHAI_ZS",
8   "merchant_customs_no": "123456",
9   "duty": 888,
10   "order_fee": 888,
11   "transport_fee": 888,
12   "product_fee": 888
13}

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
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
Merchant order No.	out_trade_no	string(32)	Yes	internal order No. of the merchant system. Should be within 32 characters and can only contain numbers, uppercase and lowercase letters, and _-\|*@. It is unique for a merchant ID. Example：20150806125346
WeChat order No.	transaction_id	string(32)	Yes	Order No. returned by WeChat Pay Example：1000320306201511078440737890
Merchant sub-order No.	sub_order_no	string(32)	No	Merchant sub-order No., which is returned for a split order. Example：20150806125346
WeChat sub-order No.	sub_order_id	string(32)	No	WeChat sub-order No., which is returned for a split order. Example：20150806125346
Last update time	modify_time	string(32)	No	Last update time, which is obtained from the WeChat server. Example：2015-09-01T10:00:00+08:00
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

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

No

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

Detailed error description

Example：

1{
2    "appid": "wxd678efh567hg6787",
3    "mchid": "1230000109",
4    "state": "SUBMITTED",
5    "out_trade_no": "20150806125346",
6    "transaction_id": "1000320306201511078440737890",
7    "sub_order_no": "20150806125346",
8    "sub_order_id": "20150806125346",
9    "modify_time": "2015-09-01T10:00:00+08:00",
10    "verify_department": "UNIONPAY",
11    "verify_department_trade_id": "2018112288340107038204310100000"
12}

Error Codes

Error Codes	Description	Solution
INVALID_REQUEST	Customs declaration record does not exist.	The customs declaration record does not exist. Please apply again or contact WeChat Pay Assistant to find out the reason.
	Declaration is in process for the payment order. You cannot modify the declaration information.	support modifying the information of a payment order that is in the process of declaration. You can modify the payment order information using the modification API after the declaration is completed.
	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.
	Order amount does not match.	The order amount for declaration must be same as the payment amount. Check whether the order amount for declaration is correct.
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	Currency is not set.	Currency is required for split declaration. Check whether fee_type is empty.
	Transaction currency is different from merchant's settlement currency.	Check whether the currency parameter (fee_type) is empty
	Parameter error	Invalid parameter. The parameter may be incorrect or is missing. Check whether the API parameters have been summited as required.
	Incorrect order amount	The order amount is different from the payment order amount. Make a check and declare again.
	Incorrect transaction order information	The transaction order information is incorrect. Make a check and declare again.
	Merchant's split declaration amount is incorrect.	The merchant's split order amount is greater than the amount of the original payment order. Make a check and declare again.
	Transaction currency is different from merchant's settlement currency.	Declare again, or contact WeChat Pay Assistant to find out the reason
	Missing parameters in split declaration.	Parameters fee_type, order_fee, transport_fee, and product_fee are required for split order.
SYSTEMERROR	System error	Declare again, or contact WeChat Pay Assistant to find out the reason.