CJ Docs

# 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 if your links may expire, copy them to CJ via "9 Upload dispute attachment" first
videoUrl video url string [] N 200 same as above
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
startDate Created-time lower bound long N 20 UTC milliseconds, exclusive; pair with endDate, maximum 90 days
endDate Created-time upper bound long N 20 UTC milliseconds, exclusive; not earlier than startDate
status V2 dispute status string N Comma-separated codes, e.g. 100,200; omit for no status filter

# 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 long 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.

# Date and status semantics

startDate/endDate filter creation time, not updateDate. Omitted filters retain previous behavior. Use overlapping reconciliation windows and deduplicate by dispute ID because both boundaries are exclusive. V2 status codes: 100=Pending processing, 200=Pending review, 300=Finance review, 400=On hold, 500=Customer confirmation, 510=Supplier refund finance review, 520=Awaiting payment, 530=Payment processing, 540=Arbitration reserved, 600=Completed, 700=Cancelled, 800=Arbitration cancelled. DISPUTE webhook types 1–5 are not these filter codes. updateDate is a nullable long in milliseconds and remains a change indicator, not a complete incremental cursor. Existing DISPUTE webhooks are unchanged.

# 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

Pass publicly accessible URLs in imageUrl / videoUrl, the same way as the "Create dispute" endpoint, and make sure they stay reachable while the dispute is being processed. If your own links expire, copy them to CJ with "9 Upload dispute attachment" first and use the returned URL — it does not expire, and images open directly in the browser.

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)

# 9 Upload dispute attachment（POST）

Copy your image or video to CJ: give the attachment's URL, CJ downloads and stores it right away, and returns a CJ-hosted URL to put in imageUrl / videoUrl of "Create dispute" and "Reply dispute". If your own attachment links expire (for example helpdesk links that expire after 1 hour), copy the file here first, so it stays reachable while the dispute is being processed.

# URL

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

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/disputes/uploadFile' \
                --header 'Content-Type: application/json' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --data '{"fileUrl": "https://your-helpdesk.com/attachments/8f3a?sig=xxx"}'
Parameter Definition Type Required Length Note
fileUrl attachment's URL string Y 2000 see "URL requirements" and "File requirements" below

One file per request; call it once per attachment.

URL requirements

  • Must be a publicly accessible http:// / https:// URL on the default port (80 / 443), without user:password; private-network addresses are rejected.
  • The URL must still be valid when you call: CJ downloads it synchronously within this call; once stored, the original URL is no longer needed.
  • Redirects are followed up to 3 times; every redirect target must also be a public address.
  • The source must start responding within 20 seconds, the whole download must finish within 120 seconds, and it must return HTTP 200.
  • URLs without a file extension or with signature parameters are fine — CJ detects the type from the file content.

File requirements

Type Formats Max per file Max per account per day
Image jpg / jpeg / png / webp / gif 10MB 50
Video mp4 / mov / webm 10MB 10
  • Images and videos together are limited to 2GB per account per day. Days are counted in Beijing time (UTC+8).
  • The format is detected from the file content, regardless of the extension in the URL; svg, html and similar content is rejected.
  • Failed copies do not count toward the daily limits.
  • Each call costs 20 points (see API points), charged per call, including calls rejected by validation.

About the returned URL

  • The URL is on a CJ domain and is publicly accessible without login:
    • Images open directly in the browser as a preview, not as a download;
    • Videos play directly in the browser (mp4 and webm work in all major browsers; whether a mov plays depends on its codec, so prefer mp4).
  • The URL does not expire; CJ does not delete it automatically, so it stays reachable during and after the dispute.
  • Anyone with the URL can open it — do not copy files that contain personal data, passwords or other sensitive information.
  • Put it in imageUrl when fileType is IMAGE, and in videoUrl when it is VIDEO.

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "url": "https://oss.cjdropshipping.com/cj-openapi-rest/dispute/2026/09/28/xxxx/3f2a9c1e0b7d4e5f8a6b2c1d0e9f8a7b.mp4",
        "fileType": "VIDEO",
        "size": 10485760
    },
    "requestId": "0242ad78-eea2-481d-876a-7cf64398f07f",
    "success": true
}
Field Definition Type Length Note
data.url attachment URL string 300 public URL on a CJ domain; images open directly in the browser. Put it in imageUrl or videoUrl
data.fileType attachment type string 10 IMAGE: use in imageUrl; VIDEO: use in videoUrl
data.size file size long in bytes
requestId request ID string 48 for troubleshooting

error

{
    "code": 1607024,
    "result": false,
    "message": "Failed to download fileUrl (HTTP 404)",
    "data": null,
    "requestId": "323fda9d-3c94-41dc-a944-5cc1b8baf5b1"
}
Code Meaning
1600300 fileUrl is empty or longer than 2000 characters
1607023 fileUrl (or a redirect target) is not a public http/https address on the default port
1607024 Download failed; the parentheses give the reason: an HTTP status such as HTTP 404 (often an expired link) / timeout / connection failed / unknown host / too many redirects
1607017 The file at the URL is empty
1607018 Unsupported format (detected from the content)
1607019 File exceeds the per-file limit (10MB for both images and videos)
1607020 Daily limit exceeded (count or the 2GB total); resets the next day, Beijing time
1607021 Too many video copies in progress, please retry later
1607022 Storing failed; the parentheses name the failed step: storage authorization failed / storage write failed / storage confirmation failed / temp file failed. Safe to retry; not counted toward the daily limits

# Example: copy first, then create the dispute

  1. Copy the attachment and take data.url from the response:
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/disputes/uploadFile' \
                --header 'Content-Type: application/json' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --data '{"fileUrl": "https://your-helpdesk.com/attachments/broken-item.jpg"}'
  1. Put data.url in imageUrl / videoUrl of "3 Create dispute" (or "8 Reply dispute"):
curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/disputes/create' \
                --header 'Content-Type: application/json' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --data '{
                    "businessDisputeId": "your-dispute-001",
                    "orderId": "SD2609280000000000000",
                    "disputeReasonId": 1,
                    "expectType": 1,
                    "refundType": 1,
                    "messageText": "The item arrived broken.",
                    "imageUrl": ["<image url returned in step 1>"],
                    "videoUrl": ["<url returned when copying the video>"],
                    "productInfoList": [{"lineItemId": "xxx", "quantity": 1, "price": 9.9}]
                }'

← 8 Webhook →