# 7 Dispute

# 1 Select the list of disputed products（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/disputeProducts

# CURL

curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/disputes/disputeProducts?orderId=CJPKL7160102171YQ' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Parameter	Definition	Type	Required	Length	Note
orderId	CJ order id	string	Y	100

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "orderId": "75727832844206081",
        "orderNumber": "1627572766607937536",
        "productInfoList": [
            {
                "lineItemId": "27572784056172547",
                "cjProductId": "70030020423733248",
                "cjVariantId": "70030020612476928",
                "canChoose": true,
                "price": 23.00,
                "quantity": 1,
                "cjProductName": "Hellpoo",
                "cjImage": "http://d847fcac-392f-4168-8b06-a580a8368dff.jpg",
                "sku": "CJSJ1041743",
                "supplierName": "banggood"
            }
        ]
    },
    "requestId": "11edc6cc84254bb4b3ac74299d5db197",
    "success": true
}

Field	Definition	Type	Length	Note
orderId	CJ order id	string	200
orderNumber	customer order number	string	200
productInfoList	Product information list	Object[]
lineItemId	lineItem id	string	100
cjProductId	CJ product id	string	100
cjVariantId	CJ variant id	string	100
canChoose	Is it possible to check to open a dispute	boolean		true:yes, false：no
price	product price	BigDecimal	(18,2)	Unit: $ (USD）
quantity	quantity	integer	20
cjProductName	CJ product name	string	200
cjImage	CJ product image	string	100
sku	sku	string	100
supplierName	supplier name	string	200

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

# 2 Confirm the dispute（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/disputeConfirmInfo

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/disputes/disputeConfirmInfo' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --data-raw '{
                    "orderId": "62650625018974208",
                    "productInfoList": [
                        {
                            "lineItemId": "1626506252349808640",
                            "quantity": "1"
                        }
                      ]
                    }'

Parameter	Definition	Type	Required	Length	Note
orderId	CJ order id	string	Y	100
productInfoList	product information	object[]	Y
lineItemId	lineItem id	string	N
quantity	quantity	integer	Y
price	price	BigDecimal	Y	(18,2)	Unit: $ (USD）

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "orderId": "265062501897420801",
        "orderNumber": "1626506237791440896",
        "maxProductPrice": 23.00,
        "maxPostage": 0.00,
        "maxIossTaxAmount": 0,
        "maxIossHandTaxAmount": 0,
        "maxAmount": 23.00,
        "expectResultOptionList": [
            "1"
        ],
        "productInfoList": [
            {
                "lineItemId": "1626506252349808640",
                "cjProductId": "1570030020423733248",
                "cjVariantId": "1570030020612476928",
                "canChoose": false,
                "price": 23.00,
                "quantity": 1,
                "cjProductName": "Hellpoo",
                "cjImage": "https://d847fcac-392f-4168-8b06-a580a8368dff.jpg",
                "sku": "CJSJ1041743-A",
                "supplierName": "banggood"
            }
        ],
        "disputeReasonList": [
            {
                "disputeReasonId": 1,
                "reasonName": "Unfulfilled Order Cancellation"
            }
        ]
    },
    "requestId": "af336b7bdc364e6391b9d558690b1521",
    "success": true
}

Field	Definition	Type	Length	Note
orderId	CJ order id	string	200
orderNumber	customer order number	string	200
expectResultOptionList	expected result	string[]		1: Refund , 2:Reissue
maxProductPrice	Product price	BigDecimal	(18,2)	Unit: $ (USD）
maxPostage	Postage	BigDecimal	(18,2)	Unit: $ (USD）
maxIossTaxAmount	ioss tax amount	BigDecimal	(18,2)	Unit: $ (USD）
maxIossHandTaxAmount	ioss tax fee amount	BigDecimal	(18,2)	Unit: $ (USD）
maxAmount	Apply for refund amount	BigDecimal	(18,2)	Unit: $ (USD）
productInfoList	product information	Object[]
canChoose	Whether to check open dispute	boolean	2	false or ture
price	price	BigDecimal	(18,2)	Unit: $ (USD）
quantity	quantity	integer	20
lineItemId	lineItem id	string	100
cjProductId	CJ product id	string	100
cjVariantId	CJ variant id	string	100
cjProductName	CJ product name	string	200
cjImage	CJ product image	string	100
sku	CJ sku	string	100
supplierName	supplier name	string	200
disputeReasonList	dispute reason	object []
disputeReasonId	dispute reason id	integer	20
reasonName	dispute reason name (EN)	string	200

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

# 3 Create dispute（POST）

Note: Disputes can only be created via this API for orders that were created through the API. Orders that were not created through the API cannot have disputes created via this interface.

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/create

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/disputes/create' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                 --data-raw '{
                    "orderId": "275727832844206081",
                    "businessDisputeId": "0000001266",
                    "disputeReasonId": 1,
                    "expectType": 1,
                    "refundType": 1,
                    "messageText": "gfhfghfghfgh",
                    "imageUrl": [],
                    "productInfoList": [
                        {
                            "lineItemId": "1627572784056172547",
                            "quantity": "1"
                        }
                    ]
                }'

Parameter	Definition	Type	Required	Length	Note
businessDisputeId	customer business id, 唯一值	string	Y	100
orderId	CJ order id	string	Y	100
disputeReasonId	dispute reason id	integer	Y	10
expectType	expect type	integer	Y	20	1: Refund , 2:Reissue
refundType	Refund type	integer	Y	20	1:balance , 2：platform
messageText	text message	string	Y	500
imageUrl	image url	string []	N	200
videoUrl	video url	string []	N	200
productInfoList	product information	object[]
price	price	BigDecimal	Y	(18,2)	Unit: $ (USD）
lineItemId	lineItem id	string	N	100
quantity	quantity	integer	Y	10

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": true,
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
code	status code	int	20	`200` means the dispute was created successfully
result	whether the request is successful	boolean	1
message	return message	string	200
data	whether the dispute was created successfully	boolean	1	returns `true` on success
requestId	request id	string	48	used for troubleshooting
success	whether the call succeeded	boolean	1	true-success, false-failed

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

# 4 Cancel dispute（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/cancel

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/disputes/cancel' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                 --data-raw '{
                        "orderId": "J1623672949997490176",
                        "disputeId": "SH1623673863466725376"
                    }'

Parameter	Definition	Type	Required	Length	Note
orderId	CJ order id	string	Y	100
disputeId	CJ dispute id	string	Y	100

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": true,
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
code	status code	int	20	`200` means the dispute was canceled successfully
result	whether the request is successful	boolean	1
message	return message	string	200
data	whether the dispute was canceled successfully	boolean	1	returns `true` on success
requestId	request id	string	48	used for troubleshooting
success	whether the call succeeded	boolean	1	true-success, false-failed

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

# 5 Query the list of disputes（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/getDisputeList

# CURL

curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/disputes/getDisputeList' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Parameter	Definition	Type	Required	Length	Note
orderId	CJ order id	string	N	100
disputeId	dispute id	integer	N	10
orderNumber	customer order number	string	N	100
pageNum	page number	integer	N	10	default: 1
pageSize	page size	integer	N	10	default: 10

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "pageNum": 1,
        "pageSize": 10,
        "total": 1,
        "list": [
            {
                "id": "SH1623673863466725376",
                "shopId": "1588478917529051136",
                "shopName": "bo te_api",
                "status": "Processing",
                "disputeReason": "Item not received",
                "replacementAmount": 0.00,
                "resendOrderCode": "",
                "money": 0.00,
                "finallyDeal": null,
                "createDate": "2025-01-15 10:30:00",
                "productList": []
            }
        ]
    },
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
pageNum	page number	int	20
pageSize	page size	int	20
total	total	int	20
list	dispute list	List
- status	dispute status	string	20
- id	dispute id	string	100
- shopId	shop id	string	100	May be empty for archived orders
- shopName	shop name	string	200	May be empty for archived orders
- disputeReason	dispute reason	string	200
- replacementAmount	Reissue amount	BigDecimal	(18,2)	Unit: $ (USD)
- resendOrderCode	Reissue order id	string	100
- money	final refund amount	BigDecimal	(18,2)	Unit: $ (USD)
- finallyDeal	final negotiation result	integer	10	1:Refund, 2: Reissue, 3: Reject
- createDate	create date	string	50	millisecond timestamp
- updateDate	last update time	string	50	millisecond timestamp. See "About updateDate" below
- productList	product information	Object[]
-- image	product image	string	200
-- price	product price	BigDecimal	(18,2)	Unit: $ (USD)
-- lineItemId	lineItem id	string	100
-- cjProductId	CJ product id	string	100
-- cjVariantId	CJ variant id	string	100
-- productName	product name	string	200
-- supplierName	supplier name	string	200

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

# About updateDate

updateDate is the last-modified time of the dispute record. Use it to detect that a dispute has moved on (including a new reply from CJ support) without polling each dispute's detail.

Do not use updateDate as the only cursor for incremental sync

This field is the update time of the dispute record row, not the maximum timestamp across every action in the dispute lifecycle. Records exist whose updateDate is earlier than their final processing time, so pulling only updateDate > lastSyncTime will miss disputes.

Recommended usage: use updateDate for change detection, and additionally run a periodic full re-pull by create-date range as a safety net.

# 6 Get dispute detail（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/getDisputeDetail

# CURL

curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/disputes/getDisputeDetail?disputeId=12345' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

Parameter	Definition	Type	Required	Length	Note
disputeId	dispute id	string	Y	100

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "id": "SH1623673863466725376",
        "shopId": "1588478917529051136",
        "shopName": "bo te_api",
        "status": "Processing",
        "disputeReason": "Item not received",
        "replacementAmount": 0.00,
        "resendOrderCode": "",
        "money": 12.50,
        "refundAmount": 12.50,
        "finallyDeal": 1,
        "createDate": 1736928600000,
        "refundDetails": [
            {
                "type": "PRODUCT_COST",
                "typeName": "Product Cost",
                "amount": 10.00
            },
            {
                "type": "SHIPPING_COST",
                "typeName": "Shipping Cost",
                "amount": 2.50
            }
        ],
        "productList": [
            {
                "image": "https://example.com/image.jpg",
                "price": 10.00,
                "productCode": "CJPROD001",
                "productId": "pid001",
                "productName": "Sample Product",
                "standId": "vid001",
                "supplierName": "Supplier A"
            }
        ]
    },
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
id	dispute id	string	100
shopId	shop id	string	100	May be empty for archived orders
shopName	shop name	string	200	May be empty for archived orders
status	dispute status	string	20
disputeReason	dispute reason	string	200
replacementAmount	reissue amount	BigDecimal	(18,2)	Unit: $ (USD)
resendOrderCode	reissue order id	string	100
money	final refund amount	BigDecimal	(18,2)	Unit: $ (USD)
refundAmount	final refund amount	BigDecimal	(18,2)	Unit: $ (USD), same value as money
finallyDeal	final negotiation result	integer	10	1:Refund, 2: Reissue, 3: Reject
createDate	create date (timestamp ms)	long	20
refundDetails	refund cost breakdown	Object[]
- type	cost type	string	50	e.g. PRODUCT_COST / SHIPPING_COST / IOSS_TAX / IOSS_HANDLING_FEE
- typeName	cost type name	string	50	e.g. Product Cost / Shipping Cost / IOSS Tax / IOSS Handling Fee
- amount	amount	BigDecimal	(18,2)	Unit: $ (USD)
productList	product information	Object[]
- image	product image	string	200
- price	product price	BigDecimal	(18,2)	Unit: $ (USD)
- productCode	product code	string	100
- productId	product id	string	100
- productName	product name	string	200
- standId	variant id	string	100
- supplierName	supplier name	string	200

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "id": "12345",
        "status": "Processing",
        "disputeReason": "Item not received",
        "productList": []
    },
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
id	dispute id	string	100
status	dispute status	string	50
disputeReason	dispute reason	string	200
replacementAmount	Reissue amount	BigDecimal	(18,2)	Unit: $ (USD)
resendOrderCode	Reissue order id	string	100
money	final refund amount	BigDecimal	(18,2)	Unit: $ (USD)
finallyDeal	final negotiation result	integer	10	1:Refund, 2: Reissue, 3: Reject
createDate	create date	string	50
productList	product information	Object[]
- image	product image	string	200
- price	product price	BigDecimal	(18,2)	Unit: $ (USD)
- productCode	product code	string	100
- productId	product id	string	100
- productName	product name	string	200
- standId	variant id	string	100
- supplierName	supplier name	string	200

error

{
    "code": 1600100, 
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Field	Definition	Type	Length	Note
code	error code	int	20	Reference error code
result	Whether or not the return is normal	boolean	1
message	return message	string	200
data	return data	object		interface data return
requestId	requestId	string	48	Flag request for logging errors

# 7 Query dispute messages（POST）

Retrieve the conversation between you and CJ support for a dispute, including text and attachments, so you can reproduce the full negotiation history in your own system without logging in to the CJ dashboard.

Coverage

This endpoint returns all disputes under your API account, not only those on orders created via API. Disputes on Excel-imported orders, dropshipping orders and manually created orders are all included. Access is decided by dispute ownership, not by the channel the order came from.

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/getDisputeMessages

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/disputes/getDisputeMessages' \
                --header 'Content-Type: application/json' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --data '{"disputeId":"SH2607291323371283500","pageNum":1,"pageSize":10}'

Parameter	Definition	Type	Required	Length	Note
disputeId	dispute id	string	Y	100
pageNum	page number	integer	N	10	default 1
pageSize	items per page	integer	N	10	default 10, max 50

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "pageNum": 1,
        "pageSize": 10,
        "total": 2,
        "list": [
            {
                "messageId": "1770485313446354944",
                "orderId": "SD2607290935060338700",
                "userType": "1",
                "createDate": 1785331419000,
                "message": "package not received",
                "imageUrl": ["https://your-domain.com/evidence-1.jpg"],
                "videoUrl": []
            },
            {
                "messageId": "1770485313446354945",
                "orderId": "SD2607290935060338700",
                "userType": "2",
                "createDate": 1785331431000,
                "message": "The order has been refunded.",
                "imageUrl": [],
                "videoUrl": []
            }
        ]
    },
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
pageNum	current page	int	20
pageSize	items per page	int	20
total	total items	int	20	see "About pagination" below
list	message list	List		ordered by time ascending
- messageId	message id	string	100
- orderId	cj order id	string	100
- userType	sender	string	10	1 - buyer (you), 2 - CJ support
- createDate	message time	long	20	millisecond timestamp
- message	message body	string	500	may be empty when only files were sent
- imageUrl	image attachments	string[]		publicly accessible URLs, may be empty
- videoUrl	video attachments	string[]		publicly accessible URLs, may be empty

About pagination

In the current version total and list come from two different stores, so the pagination parameters are not exact: the size of list may differ from pageSize, and paging may return overlapping content.

Recommended usage: set pageSize to its maximum (50) and fetch everything in one call instead of paging. Virtually all disputes have far fewer than 50 messages. If total is greater than the number of items returned, trust list. This limitation will be fixed in a future release.

error

{
    "code": 1005,
    "result": false,
    "message": "Please check it carefully.",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Code	Meaning
1005	The dispute does not exist, or it does not belong to your account. Both cases return the same code — check the dispute id first.

# 8 Reply dispute（POST）

Append a message to an ongoing dispute, optionally with image/video evidence, so you can negotiate from your own system without logging in to the CJ dashboard.

# URL

https://developers.cjdropshipping.com/api2.0/v1/disputes/reply

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/disputes/reply' \
                --header 'Content-Type: application/json' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --data '{
                    "disputeId": "SH2607291323371283500",
                    "messageText": "Here is the unboxing video.",
                    "imageUrl": ["https://your-domain.com/evidence-1.jpg"],
                    "videoUrl": []
                }'

Parameter	Definition	Type	Required	Length	Note
disputeId	dispute id	string	Y	100
messageText	message body	string	Y	500	must not be blank; emojis are stripped
imageUrl	image attachments	string[]	N		see "About attachments" below
videoUrl	video attachments	string[]	N		see "About attachments" below

About attachments

CJ does not provide a file upload endpoint. Pass publicly accessible URLs that you host yourself in imageUrl / videoUrl, the same way as the "Create dispute" endpoint. Make sure those URLs stay reachable while the dispute is being processed.

Dispute statuses that accept replies

Only disputes in the following statuses accept new messages. Any other status returns 9063:

Status	Meaning
100	Pending processing
200	Pending review
300	Refund under finance review
400	On hold
510	Supplier self-ship refund under finance review
530	Paying
600	Completed

Replies are accepted on completed disputes (600), but such messages are for communication only and do not change the settled outcome.

This endpoint is not idempotent

Do not blindly retry on timeout or network failure — doing so inserts a duplicate message into the dispute. Call "Query dispute messages" first to check whether your previous request was already recorded, then decide whether to resend.

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": true,
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}

Field	Definition	Type	Length	Note
data	whether it was sent	boolean	1
requestId	requestId	string	48	for log lookup

error

{
    "code": 9063,
    "result": false,
    "message": "The dispute is in a status that does not accept new messages.",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}

Code	Meaning
9063	The dispute's current status does not accept new messages — see the whitelist above
1005	The dispute does not exist, or it does not belong to your account (same code for both)

← 6 Logistic 8 Webhook →