# 5 交易

# 涉及的平台物流订单流程，请查阅文档

# 1 订单

# 1.1 创建订单 V2（POST）

创建订单
payType=1 或不传：页面支付（默认），会返回 cjPayUrl
payType=2：余额支付，会继续执行加购、确认订单、余额支付流程
payType=3：不发起支付，仅创建订单，不会继续执行加购和确认订单流程
header中新增platformToken参数, 获取platformToken的方式与CJ Access Token的方式相同, 如果不是被要求，该值可以为空. (2025-01-08 更新)

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/createOrderV2

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/createOrderV2' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'platformToken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "orderNumber": "1234",
                    "shippingZip": "123",
                    "shippingCountry": "123",
                    "shippingCountryCode": "US",
                    "shippingProvince": "123",
                    "shippingCity": "132",
                    "shippingCounty": "",
                    "shippingPhone": "111",
                    "shippingCustomerName": "123213",
                    "shippingAddress": "123213",
                    "shippingAddress2": "123213",
                    "taxId": "123",
                    "remark": "note",
                    "email": "",
                    "consigneeID": "",
                    "payType": "",
                    "shopAmount": "",
                    "logisticName": "PostNL",
                    "fromCountryCode": "CN",
                    "houseNumber": "123",
                    "platform": "shopify",
                    "iossType": "",
                    "iossNumber": "",
                    "orderFlow": 1,
                    "products": [
                        {
                            "vid": "92511400-C758-4474-93CA-66D442F5F787",
                            "quantity": 1,
                            "storeLineItemId": "test-lineItemId-1111"
                        }
                    ]
                }'

Parameter	Definition	Type	Required	Length	Note
orderNumber	订单编号	string	是	50
shippingZip	目的地邮编	string	否	20
shippingCountryCode	目的地国家简码	string	是	20	参照:国家信息, 请使用二字码
shippingCountry	目的地国家	string	是	50
shippingProvince	目的地省	string	是	50
shippingCity	目的地城市	string	是	50
shippingCounty	目的地县	String	否	50
shippingPhone	收货人电话	string	否	20
shippingCustomerName	收货人名称	string	是	50
shippingAddress	收货人地址	string	是	200
shippingAddress2	收货人地址2	string	否	200
houseNumber	门牌号	String	否	20
email	邮箱	String	否	50
taxId	税号	string	否	20
remark	订单备注	string	否	500
consigneeID	收货人id	string	否	20
payType	支付方式	int	否	10	可选值：1=页面支付（默认，返回 `cjPayUrl`），2=余额支付，3=不发起支付、仅创建订单
isSandbox	是否沙盒订单	integer	否	1	默认传0。0-正常订单；1-沙盒订单，无论payType为何值都会自动走假支付/模拟支付流程，不会产生真实扣费、真实物流或履约
shopAmount	订单金额	BigDecimal	否	20
logisticName	物流名称	string	是	50
fromCountryCode	发货国家	string	是	20	参照:国家信息, 请使用二字码
platform	平台类型, 默认值: Api	String	N	20	如果未传值，使用默认值API. 参考平台列表
shopLogisticsType	发货模式, 默认值：2	int	N	20	运输类型，选项：1=平台物流（CJ仓库id由你指定，必填，选择平台物流模式时，仓库会在上传面单后才开始作业，请及时上传面单，上传面单与发货信息），2=商家物流（CJ仓库id不会被使用），3=平台物流(CJ仓库ID由CJ指定)。无要求时，请使用2=商家物流。上线于2025-11-18
storageId	CJ仓库id	String	N	40	当shopLogisticsType为=1时，该值有效, 上线于2025-11-18
iossType	ioss类型	int	否	20	IOSS类型，选项：1=无IOSS（在没有IOSS的情况下申报订单时，收款人将被要求支付增值税和其他相关费用。），2=用我自己的IOSS申报（请确保提供的IOSS是有效的，并与欧盟的目的地国家相关联。如果目的地国家没有与正确的IOSS相关联，申报将在没有IOSS的情况下进行。），3=用CJ的IOSS进行申报（建议申报您的商店订单金额。如果您选择用CJ订单金额申报，您将对相关风险负责。CJ的IOSS不适用于价值超过150欧元的订单，收款人需要支付增值税。), 设置界面 (opens new window)
iossNumber	ioss编号	String	否	10	如果iosType=3，则该值固定为CJ-IOSS
storeName	店铺名称	String	否	50	如果填写，系统校验必须和CJ系统中API模块中店铺名称一致。如果未填写，订单将归属到默认API店铺
storeOrderTime	订单下单时间	Long	否	20	时间戳格式（秒）。代表订单在消费者在店铺的下单时间或者消费者实际的下单时间。如果该时间晚于当前系统时间，则返回报错
orderFlow	订单流程类型, 默认值：1	int	否	10	订单流程类型。选项：1=手工订单流程（使用CJ变体创建订单，默认值），2=店铺订单流程（支持使用店铺sku创建订单，需要在My CJ的Store Product关联CJ商品）。上线于2025-05-19
products		list	是	20
- vid	CJ 变体 id	string	否	50	vid与sku不能都为空，如果vid为空，则使用sku查询CJ变体，如果都提供，会校验两者必须是相同的变体，不相同则校验失败。如果客户维度开通了可以传非CJsku权限，则vid为必传项
- sku	CJ 变体 sku	string	否	50	vid与sku不能都为空，如果sku为空，则使用vid查询CJ变体，如果都提供，会校验两者必须是相同的变体，不相同则校验失败
- storeProductId	店铺商品id	String	否	64	作为店铺商品的平台商品id保存到店铺商品表并传给订单中心；上线于2026-06-02
- storeProductImg	店铺商品图片	String	否	500	作为店铺商品的平台商品图片保存到店铺商品表并传给订单中心；上线于2026-06-02
- quantity	变体数量	int	是	10
- unitPrice	商品单价	BigDecimal	否	20	unit: $ (USD)
- storeLineItemId	店铺订单的lineItemId	String	否	125
- podProperties	POD定制信息	String	否	500	podProperties是一个字符串，1：Pod2.0 示例:[{"areaName":"LogoArea","links":["<https://cc-west-usa.oss-us-west-1.aliyuncs.com/9f0b99e6-17ec-4dcd-8916-fc5d644be993_LOGO_NavyBlue.png"],"type":"1"]}] 2：Pod3.0 示例:{"links": ["生产图URL (支持多张)"],"effectImgs": ["效果图URL (只支持一张)"]}

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "orderNumber": "",
        "orderId": "123434",
        "shipmentOrderId": "",
        "iossAmount": "",
        "iossTaxHandlingFee": "",
        "postageAmount": "",
        "productAmount": "",
        "productOriginalAmount": "",
        "productDiscountAmount": "",
        "postageDiscountAmount": "",
        "postageOriginalAmount": "",
        "totalDiscountAmount": "",
        "actualPayment": "",
        "orderOriginalAmount": "",
        "cjPayUrl": "",
        "orderAmount": "",
        "logisticsMiss": "",
        "productInfoList": [
            {
                "storeLineItemId": "test-lineItemId-1111",
                "lineItemId": "",
                "variantId": "",
                "isGroup": true,
                "quantity": 10,
                "subOrderProducts": [
                    {
                        "lineItemId": "",
                        "variantId": "",
                        "quantity": 1
                    }
                ]
            }
        ],
        "orderStatus": "",
        "interceptOrderReasons": [
            {
                "code": 1001,
                "message": ""
            }
        ]
    },
    "requestId": "9eddf3f5-bd3d-4fae-a4f2-028cbb90db97",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

data information

Field	Definition	Type	Length	Note
orderId	CJ 订单号	string	200	如果传入的商品vid非CJ的SKU，因为订单号会变化，则不会返回CJ订单号。您可以监听webhook获取到最新的CJ订单号
orderNumber	客户订单号	string	200
shipmentOrderId	母订单号Id	string	200
iossAmount	ioss金额	BigDecimal	（18，2）	Unit: $ (USD）
iossTaxHandlingFee	ioss税费	BigDecimal	（18，2）	Unit: $ (USD）
postageAmount	物流费用	BigDecimal	（18，2）	Unit: $ (USD）
productAmount	商品金额	BigDecimal	（18，2）	Unit: $ (USD）
productOriginalAmount	商品总金额(折前)	BigDecimal	（18，2）	Unit: $ (USD）
productDiscountAmount	商品优惠金额	BigDecimal	（18，2）	Unit: $ (USD）
postageDiscountAmount	运费折扣金额	BigDecimal	（18，2）	Unit: $ (USD）
postageOriginalAmount	运费折扣前金额	BigDecimal	（18，2）	Unit: $ (USD）
totalDiscountAmount	订单优惠后的总金额	BigDecimal	（18，2）	Unit: $ (USD）
actualPayment	实付金额	BigDecimal	（18，2）	Unit: $ (USD）
orderOriginalAmount	订单原总金额	BigDecimal	（18，2）	Unit: $ (USD）
cjPayUrl	CJ支付页跳转地址	string	200
orderAmount	订单金额	BigDecimal	200
logisticsMiss	物流缺失标识	Boolean	10
orderStatus	订单状态	string	10	参考订单状态
productInfoList	订单商品信息	list
interceptOrderReasons	订单拦截信息	list

product information

Field	Definition	Type	Length	Note
storeLineItemId	店铺订单的lineItemId	String	否	125
lineItemId	CJ订单item的唯一id	string	50
variantId	变体 id	string	50
quantity	数量	int	20
isGroup	是否组合主商品	boolean	10
subOrderProducts	组合子商品	list	10
- lineItemId	CJ订单item的唯一id	string	50
- variantId	变体 id	string	50
- quantity	数量	int	20

Order interception information

Field	Definition	Type	Length	Note
code	code	int	50
message	拦截信息	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

# 1.2 创建订单 V3（POST）

创建订单
header中新增platformToken参数, 获取platformToken的方式与CJ Access Token的方式相同, 如果不是被要求，该值可以为空. (2025-01-08 更新)

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/createOrderV3

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/createOrderV3' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'platformToken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "orderNumber": "1234",
                    "shippingZip": "123",
                    "shippingCountry": "123",
                    "shippingCountryCode": "US",
                    "shippingProvince": "123",
                    "shippingCity": "132",
                    "shippingCounty": "",
                    "shippingPhone": "111",
                    "shippingCustomerName": "123213",
                    "shippingAddress": "123213",
                    "shippingAddress2": "123213",
                    "taxId": "123",
                    "remark": "note",
                    "email": "",
                    "consigneeID": "", 
                    "shopAmount": "",
                    "logisticName": "PostNL",
                    "fromCountryCode": "CN",
                    "houseNumber": "123",
                    "platform": "shopify",
                    "iossType": "",
                    "iossNumber": "",
                    "orderFlow": 1,
                    "products": [
                        {
                            "vid": "92511400-C758-4474-93CA-66D442F5F787",
                            "quantity": 1,
                            "storeLineItemId": "test-lineItemId-1111"
                        }
                    ]
                }'

Parameter	Definition	Type	Required	Length	Note
orderNumber	订单编号	string	是	50
shippingZip	目的地邮编	string	否	20
shippingCountryCode	目的地国家简码	string	是	20	参照:国家信息, 请使用二字码
shippingCountry	目的地国家	string	是	50
shippingProvince	目的地省	string	是	50
shippingCity	目的地城市	string	是	50
shippingCounty	目的地县	String	否	50
shippingPhone	收货人电话	string	否	20
shippingCustomerName	收货人名称	string	是	50
shippingAddress	收货人地址	string	是	200
shippingAddress2	收货人地址2	string	否	200
houseNumber	门牌号	String	否	20
email	邮箱	String	否	50
taxId	税号	string	否	20
remark	订单备注	string	否	500
consigneeID	收货人id	string	否	20
shopAmount	订单金额	BigDecimal	否	20
logisticName	物流名称	string	是	50	参考物流试算
fromCountryCode	发货国家	string	是	20	参照:国家信息, 请使用二字码
platform	平台类型, 默认值: Api	String	N	20	如果未传值，使用默认值API. 参考平台列表
shopLogisticsType	发货模式, 默认值：2	int	N	20	运输类型，选项：1=平台物流（CJ仓库id由你指定，必填，选择平台物流模式时，仓库会在上传面单后才开始作业，请及时上传面单，上传面单与发货信息），2=商家物流（CJ仓库id不会被使用），3=平台物流(CJ仓库ID由CJ指定)。无要求时，请使用2=商家物流。上线于2025-11-18
storageId	CJ仓库id	String	N	40	当shopLogisticsType为=1时，该值有效, 上线于2025-11-18
iossType	ioss类型	int	否	20	IOSS类型，选项：1=无IOSS（在没有IOSS的情况下申报订单时，收款人将被要求支付增值税和其他相关费用。），2=用我自己的IOSS申报（请确保提供的IOSS是有效的，并与欧盟的目的地国家相关联。如果目的地国家没有与正确的IOSS相关联，申报将在没有IOSS的情况下进行。），3=用CJ的IOSS进行申报（建议申报您的商店订单金额。如果您选择用CJ订单金额申报，您将对相关风险负责。CJ的IOSS不适用于价值超过150欧元的订单，收款人需要支付增值税。), 设置界面 (opens new window)
iossNumber	ioss编号	String	否	10	如果iosType=3，则该值固定为CJ-IOSS
storeName	店铺名称	String	否	50	如果填写，系统校验必须和CJ系统中API模块中店铺名称一致。如果未填写，订单将归属到默认API店铺
storeOrderTime	订单下单时间	Long	否	20	时间戳格式（秒）。代表订单在消费者在店铺的下单时间或者消费者实际的下单时间。如果该时间晚于当前系统时间，则返回报错
isSandbox	是否沙盒订单	integer	否	1	默认传0。0-正常订单；1-沙盒订单，无论payType为何值都会自动走假支付/模拟支付流程，不会产生真实扣费、真实物流或履约
orderFlow	订单流程类型, 默认值：1	int	否	10	订单流程类型。选项：1=手工订单流程（使用CJ变体创建订单，默认值），2=店铺订单流程（支持使用店铺sku创建订单，需要在My CJ的Store Product关联CJ商品）。上线于2025-05-19
products		list	是	20
- vid	CJ 变体 id	string	否	50	vid与sku不能都为空，如果vid为空，则使用sku查询CJ变体，如果都提供，会校验两者必须是相同的变体，不相同则校验失败。如果客户维度开通了可以传非CJsku权限，则vid为必传项。
- sku	CJ 变体 sku	string	否	50	vid与sku不能都为空，如果sku为空，则使用vid查询CJ变体，如果都提供，会校验两者必须是相同的变体，不相同则校验失败
- storeProductId	店铺商品id	String	否	64	作为店铺商品的平台商品id保存到店铺商品表并传给订单中心；上线于2026-06-02
- storeProductImg	店铺商品图片	String	否	500	作为店铺商品的平台商品图片保存到店铺商品表并传给订单中心；上线于2026-06-02
- quantity	变体数量	int	是	50
- storeLineItemId	店铺订单的lineItemId	String	否	125
- unitPrice	商品单价	BigDecimal	否	50
- podProperties	POD定制信息	String	否	500	podProperties是一个字符串，1：Pod2.0 示例:[{"areaName":"LogoArea","links":["<https://cc-west-usa.oss-us-west-1.aliyuncs.com/9f0b99e6-17ec-4dcd-8916-fc5d644be993_LOGO_NavyBlue.png"],"type":"1"]}] 2：Pod3.0 示例:{"links": ["生产图URL (支持多张)"],"effectImgs": ["效果图URL (只支持一张)"]}

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "orderNumber": "",
        "orderId": "123434",
        "shipmentOrderId": "",
        "iossAmount": "",
        "iossTaxHandlingFee": "",
        "postageAmount": "",
        "productAmount": "",
        "productOriginalAmount": "",
        "productDiscountAmount": "",
        "postageDiscountAmount": "",
        "postageOriginalAmount": "",
        "totalDiscountAmount": "",
        "actualPayment": "",
        "orderOriginalAmount": "",
        "cjPayUrl": "",
        "orderAmount": "",
        "logisticsMiss": "",
        "productInfoList": [
            {
                "storeLineItemId": "test-lineItemId-1111",
                "lineItemId": "",
                "variantId": "",
                "isGroup": true,
                "quantity": 10,
                "subOrderProducts": [
                    {
                        "lineItemId": "",
                        "variantId": "",
                        "quantity": ""
                    }
                ]
            }
        ],
        "orderStatus": "",
        "interceptOrderReasons": [
            {
                "code": 1001,
                "message": ""
            }
        ]
    },
    "requestId": "9eddf3f5-bd3d-4fae-a4f2-028cbb90db97"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

data information

Field	Definition	Type	Length	Note
orderId	CJ 订单号	string	200	如果传入的商品vid非CJ的SKU，因为订单号会变化，则不会返回CJ订单号。您可以监听webhook获取到最新的CJ订单号
orderNumber	客户订单号	string	200
shipmentOrderId	母订单号Id	string	200
iossAmount	ioss金额	BigDecimal	（18，2）	Unit: $ (USD）
iossTaxHandlingFee	ioss税费	BigDecimal	（18，2）	Unit: $ (USD）
postageAmount	物流费用	BigDecimal	（18，2）	Unit: $ (USD）
productAmount	商品金额	BigDecimal	（18，2）	Unit: $ (USD）
productOriginalAmount	商品总金额(折前)	BigDecimal	（18，2）	Unit: $ (USD）
productDiscountAmount	商品优惠金额	BigDecimal	（18，2）	Unit: $ (USD）
postageDiscountAmount	运费折扣金额	BigDecimal	（18，2）	Unit: $ (USD）
postageOriginalAmount	运费折扣前金额	BigDecimal	（18，2）	Unit: $ (USD）
totalDiscountAmount	订单优惠后的总金额	BigDecimal	（18，2）	Unit: $ (USD）
actualPayment	实付金额	BigDecimal	（18，2）	Unit: $ (USD）
orderOriginalAmount	订单原总金额	BigDecimal	（18，2）	Unit: $ (USD）
cjPayUrl	CJ支付页跳转地址	string	200
orderAmount	订单金额	BigDecimal	200
logisticsMiss	物流缺失标识	Boolean	10
orderStatus	订单状态	string	10	参考订单状态
productInfoList	订单商品信息	list
interceptOrderReasons	订单拦截信息	list

product information

Field	Definition	Type	Length	Note
storeLineItemId	店铺订单的lineItemId	String	否	125
lineItemId	CJ订单item的唯一id	string	50
variantId	变体 id	string	50
quantity	数量	int	20
isGroup	是否组合主商品	boolean	10
subOrderProducts	组合子商品	list	10
- lineItemId	CJ订单item的唯一id	string	50
- variantId	变体 id	string	50
- quantity	数量	int	20

Order interception information

Field	Definition	Type	Length	Note
code	code	int	50
message	拦截信息	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

# 1.3 加入购物车（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/addCart

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/addCart' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "cjOrderIdList": ["SD25080109282603297001"]
                }'

参数名称	参数意义	参数类型	是否必传	长度	备注
cjOrderIdList	CJ 订单 id列表	list	是	200	查询条件

# 返回

success

{
    "success": true,
    "code": 200,
    "message": "Congratulation! Well done!",
    "data": {
        "successCount": 1,
        "addSuccessOrders": [
            "SD25080109282603297001"
        ],
        "unInterceptAddressCount": 0,
        "interceptOrders": []
    }
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回(订单号)
requestId	请求Id	string	48	用于日志查询错误

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.4 购物车确认（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/addCartConfirm

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/addCartConfirm' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "cjOrderIdList": ["SD25080109282603297001"]
                }'

参数名称	参数意义	参数类型	是否必传	长度	备注
cjOrderIdList	订单 id	list	是	200	查询条件

# 返回

success

{
    "success": true,
    "code": 200,
    "message": "Congratulation! Well done!",
    "data": {
        "successCount": 1,
        "submitSuccess": true,
        "shipmentsId": "",
        "result": 0,
        "interceptOrders": []
    }
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
- successCount	成功数量
- submitSuccess	是否提交成功
- shipmentsId	Shipment Order Id			请记录好
- result
- interceptOrders		List		被拦截的订单id列表
requestId	请求Id	string	48	用于日志查询错误

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.5 保存提交母单（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/saveGenerateParentOrder

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/saveGenerateParentOrder' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "shipmentOrderId": "SD25080109282603297001"
                }'

参数名称	参数意义	参数类型	是否必传	长度	备注
shipmentOrderId	Shipment Order Id	string	是	200	查询条件

# 返回

success

{
  "success": true,
  "message": "",
  "data": {
    "orderMoney": 99.99,
    "payExpireTime": "2024-12-31 23:59:59",
    "payId": "PAY123456789",
    "result": 0,
    "submitSuccess": true,
    "unMatchOrderCodes": ["ORDER001", "ORDER002"],
    "successOrders": ["ORDER003", "ORDER004"],
    "unMatchProductCodes": ["PROD001", "PROD002"],
    "paymentInformation": {
      "actualPayment": 89.99,
      "balanceDeduction": 10.00,
      "billAmount": 12.50,
      "canDeduct": true,
      "commodityDiscount": 5.00,
      "commodityTotalAmount": 94.99,
      "couponAmount": 15.00,
      "freight": 5.00,
      "iossAmount": 2.50,
      "iossNumber": "IOSS123456",
      "iossTaxHandlingFee": 0.50,
      "iossTaxes": 2.00,
      "iossType": 3,
      "orderOriginalAmount": 104.99,
      "orderProductAmount": 94.99,
      "payableAmount": 89.99,
      "postageDiscount": 0.00,
      "serviceFee": 1.00
    },
    "interceptOrders": [
    ]
  }
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.6 订单列表（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/list?pageNum=1&pageSize=10

# CURL

curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/list?pageNum=1&pageSize=10' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

参数名称	参数意义	参数类型	是否必传	长度	备注
pageNum	页数	int	否	20	默认 1
pageSize	每页返回多少条	int	否	20	默认 20
orderIds	订单ID	`List<string>`	否	100	查询条件
shipmentOrderId	母订单ID	string	否	100	查询条件
status	订单状态	string	否	20	默认值: CANCELLED, 可选值:CREATED,IN_CART,UNPAID,UNSHIPPED,SHIPPED,DELIVERED,CANCELLED,OTHER

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "pageNum": 1,
        "pageSize": 10,
        "total": 100,
        "list": [
            {
                "orderId": "210823100016290555",
                "orderNum": "api_52f268d40b8d460e82c0683955e63cc9",
                "cjOrderId": null,
                "shippingCountryCode": "US",
                "shippingProvince": "Connecticut",
                "shippingCity": "ftdsr",
                "shippingPhone": "43514123",
                "shippingAddress": "rfdxf rfdesr",
                "shippingCustomerName": "Xu Old",
                "remark": null,
                "orderWeight": 20,
                "orderStatus": "CREATED",
                "orderAmount": 4.25,
                "productAmount": 0.57,
                "postageAmount": 3.68,
                "logisticName": "CJPacket Ordinary",
                "trackNumber": null,
                "trackingProvider": "Yun_Standard",
                "createDate": "2021-08-23 11:31:45",
                "paymentDate": null,
                "productList": [
                    {
                        "vid": "1392053744945991680",
                        "quantity": 1,
                        "sellPrice": 0.57
                    }
                ]
            }
        ]
    },
    "requestId": "3adccdcb-d41b-4808-996b-c7c5c833d77d"
}

返回字段	字段意思	字段类型	长度	备注
orderId	订单ID	string	200
orderNum	订单号	string	200
cjOrderId	CJ订单ID	string	200
shippingCountryCode	交易国家	string	200
shippingProvince	交易省份	string	200
shippingCity	交易城市	string	200
shippingAddress	交易地址	string	200
shippingCustomerName	交易接收人	string	200
shippingPhone	交易电话	string	200
remark	订单备注	string	500
logisticName	物流名称	string	200
trackNumber	追踪单号	string	200
trackingProvider	物流服务提供商	string	200
trackingUrl	追踪号轨迹URL	string	200
orderWeight	订单重量	int	200
orderAmount	订单金额	BigDecimal	（18，2）	单位：$（美元）
productAmount	商品金额	BigDecimal	（18，2）	单位：$（美元）
postageAmount	物流金额	BigDecimal	（18，2）	单位：$（美元）
orderStatus	订单状态	string	200	参考订单状态
createDate	创建时间	string	200
paymentDate	支付时间	string	200
storeCreateDate	店铺订单创建时间	DateTime	1	UTC时间, 示例: 2025-03-14 13:21:07
isSandbox	是否沙盒订单	integer	1	0-否，1-是
privateOutboundOrder	是否私有库存出库单	boolean		true=私有库存出库单, false=普通订单。与 webhook 订单消息一致
productList		list	200
- vid	变体ID	string	200
- quantity	数量	int	200
- sellPrice	售价	BigDecimal	（18，2）	单位：$（美元）

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.7 订单查询（GET）

a1. Maximum return of 200 data per page.

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/getOrderDetail?orderId=210711100018043276

# CURL

curl --location --request GET 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/getOrderDetail?orderId=2107111000180432766&features=f1&features=f2' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

# Request参数

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	订单 id	string	是	200	支持id: 客户订单id, CJ订单id
features	启用的特性功能	`List<String>`	false	20	如果传入相关特性,会启用相关的功能,启动多个特性时, 传入多个features参数

# 特性枚举

枚举编码	说明
LOGISTICS_TIMELINESS	启用查询物流时效,传入该特性枚举后,结果中会返回 logisticsTimeliness

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "orderId": "210823100016290555",
        "orderNum": "api_52f268d40b8d460e82c0683955e63cc9",
        "platformOrderId": "6387689586969",
        "cjOrderId": null,
        "shippingCountryCode": "US",
        "shippingProvince": "Connecticut",
        "shippingCity": "ftdsr",
        "shippingPhone": "43514123",
        "shippingAddress": "rfdxf rfdesr",
        "shippingCustomerName": "Xu Old",
        "remark": null,
        "orderWeight": 20,
        "orderStatus": "CREATED",
        "orderAmount": 4.25,
        "productAmount": 0.57,
        "postageAmount": 3.68,
        "logisticName": "CJPacket Ordinary",
        "trackNumber": null,
        "trackingProvider": "Yun_Standard",
        "createDate": "2021-08-23 11:31:45",
        "paymentDate": null,
        "isComplete":1,
        "fromCountryCode":"CN",
        "disputeId": null,
        "productList": [
            {
                "vid": "1392053744945991680",
                "quantity": 1,
                "sellPrice": 0.57,
                "podPropertiesInfo": null,
                "lineItemId": "2505170958390976500",
                "storeLineItemId": "16045188153625",
                "productionOrderStatus": 1,
                "abnormalType": [
                    6,
                    9
                ]
            }
        ]
    },
    "requestId": "3adccdcb-d41b-4808-996b-c7c5c833d77d"
}

pod订单查询返回信息

{
	"code": 200,
	"result": true,
	"message": "Success",
	"data": {
		"orderId": "210823100016290555",
		"orderNum": "api_52f268d40b8d460e82c0683955e63cc9",
		"cjOrderId": null,
		"shippingCountryCode": "US",
		"shippingProvince": "Connecticut",
		"shippingCity": "ftdsr",
		"shippingPhone": "43514123",
		"shippingAddress": "rfdxf rfdesr",
		"shippingCustomerName": "Xu Old",
		"remark": null,
		"orderWeight": 20,
		"orderStatus": "CREATED",
		"orderAmount": 4.25,
		"productAmount": 0.57,
		"postageAmount": 3.68,
		"logisticName": "CJPacket Ordinary",
		"trackNumber": null,
		"trackingProvider": "Yun_Standard",
		"createDate": "2021-08-23 11:31:45",
		"paymentDate": null,
		"isComplete": 1,
		"fromCountryCode": "CN",
		"productList": [
			{
				"vid": "1392053744945991680",
				"quantity": 1,
				"sellPrice": 0.57,
				"podPropertiesInfo": null,
                "lineItemId": "2505170958390976500",
                "storeLineItemId": "16045188153625",
                "productionOrderStatus": 1,
                "abnormalType": [
                    6,
                    9
                ],
				"podPropertiesInfo": {
                    "image": "https://pod-picture.oss-cn.aliyuncs.com/LX/PO-211-12729261699191806-1.jpg",
                    "isFixedCustom": false,
                    "podVersion": 3,
                    "failedList": [],
                    "effectImgList": [
                        "https://pod-picture.oss-cn.aliyuncs.com/LX/PO-211-1.jpg?podThumbnailUrl=https%3A%2F%2Fpod-picture.oss-cn.aliyuncs.com%2Fpod%2F250428%2Fpod-picture_oss-cn-211-12729261699191806-1_jpg.1440x1440.webp&podOriginSize=638820&podOriginPxUrl=https%3A%2F%2Fpod-picture.oss-cn-hangzhou.aliyuncs.com%2Fpod_infinity%2F250428%2Fpod-picture_oss-cn-hangzhou_aliyuncs_com_LX_PO-211-12729261699191806-1_jpg.InfinityxInfinity.webp&podOriginPx=1936_1854&podOriginOss=https%3A%2F%2Fpod-picture.oss-cn-hangzhou.aliyuncs.com%2Fpod_origin%2F250428%2Fpod-picture_oss-cn-hangzhou_aliyuncs_com_LX_PO-211-1_jpg.InfinityxInfinity.jpg"
                    ],
                    "finish": 1,
                    "customResources": [],
                    "type": 5,
                    "customMessgae": {
                        "podType": 1,
                        "color": {},
                        "zone": {
                            "back": {},
                            "front": {}
                        }
                    },
                    "productionImgList": [
                        "https://pod-picture.oss-cn.aliyuncs.com/LX/PO-211-1.jpg?podThumbnailUrl=https%3A%2F%2Fpod-picture.oss.aliyuncs.com%2Fpod%2F250428%2Fpod-picture_oss-cn-hangzhou_aliyuncs_com_LX_PO-211-12729261699191806-1_jpg.1440x1440.webp&podOriginSize=638820&podOriginPxUrl=https%3A%2F%2Fpod-picture.oss-cn-hangzhou.aliyuncs.com%2Fpod_infinity%2F250428%2Fpod-picture_oss-cn-hangzhou_aliyuncs_com_LX_PO-211-12729261699191806-1_jpg.InfinityxInfinity.webp&podOriginPx=1936_1854&podOriginOss=https%3A%2F%2Fpod-picture.oss-cn-hangzhou.aliyuncs.com%2Fpod_origin%2F250428%2Fpod-picture_oss-cn-hangzhou_aliyuncs_com_LX_PO-211-12729261699191806-1_jpg.InfinityxInfinity.jpg"
                    ],
                    "customDesign": [
                        {
                            "img": "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/180af06e-7b7-4662-b975-070203989480.jpg",
                            "areaNameEn": "",
                            "printWidth": "50",
                            "typeName": "",
                            "type": "1",
                            "scaleX": "1",
                            "backImgList": [
                                {
                                    "color": "1pcs",
                                    "imgSrc": "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/00e2483-b3b2-4873-80ac-e71f4d760e1f.jpg"
                                },
                                {
                                    "color": "4pcs",
                                    "imgSrc": "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/0c42181-d63f-49f9-b6d5-d55574027fcb.jpg"
                                },
                                {
                                    "color": "10pcs",
                                    "imgSrc": "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/1ae2f95-5484-4d30-a93f-64bc740832d2.jpg"
                                },
                                {
                                    "color": "16pcs",
                                    "imgSrc": "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/53ce421-33db-4249-8862-f36ad20083b5.jpg"
                                },
                                {
                                    "color": "18pcs",
                                    "imgSrc": "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/245e348-a87b-4196-a3a4-056f6b391301.jpg"
                                }
                            ],
                            "printHeight": "50",
                            "scaleY": "1",
                            "podType": "4",
                            "top": "297.99999928474426",
                            "areaName": "DIY",
                            "left": "253.99999994039536",
                            "areaType": "1",
                            "imgicon": "",
                            "angle": "0",
                            "fontSize": 12,
                            "fontSpace": 0,
                            "sku": ""
                        }
                    ]
                }
			}
		]
	},
	"requestId": "3adccdcb-d41b-4808-996b-c7c5c833d77d"
}

返回字段	字段意思	字段类型	长度	备注
orderId	CJ订单ID	string	200
orderNum	店铺订单号	string	200
platformOrderId	店铺订单Id	string	200
fromCountryCode	发货国家编码	string	2
shippingCountryCode	收货人国家编码	string	200
shippingProvince	收货人省份	string	200
shippingCity	收货人城市	string	200
shippingAddress	收货人地址	string	200
shippingCustomerName	收货人名称	string	200
shippingPhone	收货人电话	string	200
remark	订单备注	string	500
logisticName	物流名称	string	200
trackNumber	追踪单号	string	200
trackingProvider	物流服务提供商	string	200
trackingUrl	追踪号轨迹URL	string	200
disputeId	CJ纠纷id	string	50
orderWeight	订单重量	int	200
orderAmount	订单金额	BigDecimal	（18，2）	单位：$（美元）
productAmount	商品金额	BigDecimal	（18，2）	单位：$（美元）
postageAmount	物流金额	BigDecimal	（18，2）	单位：$（美元）
orderStatus	订单状态	string	200	参考订单状态
createDate	创建时间	string	200	UTC时间
paymentDate	支付时间	string	200	UTC时间
outWarehouseTime	出库时间	DateTime	1	UTC时间, 示例: 2025-03-14 13:21:07
storeCreateDate	店铺订单创建时间	DateTime	1	UTC时间, 示例: 2025-03-14 13:21:07
isComplete	订单是否完整1:完整 0:不完整	Number	1
isSandbox	是否沙盒订单	integer	1	0-否，1-是
privateOutboundOrder	是否私有库存出库单	boolean		true=私有库存出库单, false=普通订单。与 webhook 订单消息一致
productList	订单中的商品	list	200
- vid	变体ID	string	200
- quantity	数量	int	200
- sellPrice	售价	BigDecimal	（18，2）	单位：$（美元）
- storeLineItemId	店铺订单的lineItemId	string	125
- lineItemId	CJ订单item的唯一id	string	50
- productionOrderStatus	生产状态	Number	1	1=待排单, 2=待生产, 3=生产中, 4=生产完成, 5=生产异常
- abnormalType	异常原因	int[]		6=图片链接错误, 9=生产图和效果图对不上, 10=缺少挂环, 11=刀线图和印刷图不匹配, 12=边缘不平整, 13=字母未连接, 14=下单图片缺失
- podPropertiesInfo	pod订单信息	Object
-- effectImgList	效果图	string	200
-- customResources	成品信息	string	200
-- productionImgList	生产图	string	200
logisticsTimeliness	物流时效	Object
- logisticsModes	物流公司列表	List
-- logisticsName	物流名称	string		DHL Official
-- arrivalTime	妥投天数	string		3-7 Days

订单状态

订单状态	状态
CREATED	创建订单
IN_CART	加入购物车
UNPAID	未支付
UNSHIPPED	未发货
SHIPPED	发货
DELIVERED	已完成
CANCELLED	取消

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 错误码

错误码	错误信息
1600300	order not found
1600300	orderId must be not empty
1600300	The maximum number of features is 20

# 1.8 订单删除（DEL）

仅订单状态为 CREATED（已创建未加购）和 IN_CART（已加入购物车）时可删除；订单一旦被确认或进入后续状态（如 UNPAID、UNSHIPPED、SHIPPED、DELIVERED、CANCELLED 等），均无法通过本接口删除。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/deleteOrder?orderId=210711100018655344

# CURL

curl --location --request DELETE 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/deleteOrder?orderId=210711100018655344' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	订单 id	string	是	200	查询条件

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": "210711100018655344",
    "requestId": "721341bf-abf8-4d8c-b400-1fbdaef79039"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回(订单号)
requestId	请求Id	string	48	用于日志查询错误

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.9 订单确认（PATCH）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/confirmOrder

# CURL

curl --location --request PATCH 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/confirmOrder' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "orderId": "210711100018655344"
                }'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	订单 id	string	是	200	查询条件

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": "210711100018655344",
    "requestId": "721341bf-abf8-4d8c-b400-1fbdaef79039"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回(订单号)
requestId	请求Id	string	48	用于日志查询错误

error

{
    "code": 1603001,
    "result": false,
    "message": "order confirm fail",
    "data": null,
    "requestId": "7dc61955-c0e8-4731-bb9b-393b4fffeaaf"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.10 更换订单仓库

可通过该接口修改平台物流订单的仓库。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/changeWarehouse

# CURL

curl --location 'http://localhost:8081/api2.0/v1/shopping/order/changeWarehouse' \
--header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
--header 'Content-Type: application/json' \
--data '{
    "orderCode": "123",
    "storageId": "1234"
}'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderCode	订单号	string	是	200	查询条件
storageId	仓库id	string	是	200	查询条件

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Congratulation! Well done!",
    "data": true,
    "requestId": "c627424a858444ef861484ba8d1bee48",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data	接口数据返回	object		接口数据返回
requestId	请求Id	string	48	用于日志查询错误

error

{
    "code": 1603001,
    "result": false,
    "message": "order query fail",
    "data": false,
    "requestId": "7dc61955-c0e8-4731-bb9b-393b4fffeaaf"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data	接口数据返回	object		接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 1.11 沙盒订单模拟支付（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/sandbox/simulatePay

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/sandbox/simulatePay' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "orderId": "210711100018655344"
                }'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	CJ订单号	string	否	200	沙盒订单的CJ订单号，与shipmentOrderId二选一
shipmentOrderId	母订单号	string	否	200	母订单号，按母单批量模拟支付所有沙盒子订单，与orderId二选一

参数说明：orderId和shipmentOrderId必须至少传一个。传orderId按单个子订单模拟支付；传shipmentOrderId按母单下所有沙盒子订单批量模拟支付。

注意：当母单下存在多个子订单时，不能使用orderId按单个子订单模拟支付，请传shipmentOrderId按母单批量模拟支付。

适用范围：仅支持isSandbox=1创建的沙盒订单。该接口只模拟支付成功，不会产生真实扣费、真实物流或履约。

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": true,
    "requestId": "9eddf3f5-bd3d-4fae-a4f2-028cbb90db97"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data	模拟支付结果	boolean		true-成功
requestId	请求Id	string	48	用于日志查询错误

# 1.12 沙盒订单状态更新（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/sandbox/updateStatus

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/sandbox/updateStatus' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "orderId": "210711100018655344",
                    "targetStatus": 400
                }'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	CJ订单号	string	是	200	沙盒订单的CJ订单号
targetStatus	目标状态码	integer	是	20	可选值: 400(未发货)、500(已发货)、600(已完成)、700(已关闭)

适用范围：仅支持isSandbox=1创建的沙盒订单。状态更新只模拟沙盒订单流转，不会触发真实物流或履约。

状态流转规则：只能按顺序流转，300→400→500→600→700，不可跳跃或回退。

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": true,
    "requestId": "9eddf3f5-bd3d-4fae-a4f2-028cbb90db97"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data	状态更新结果	boolean		true-成功
requestId	请求Id	string	48	用于日志查询错误

# 订单状态

订单状态	状态
CREATED	创建订单
IN_CART	已加入购物车
UNPAID	未支付
UNSHIPPED	已支付待发货
SHIPPED	发货
DELIVERED	已送达
CANCELLED	已取消

# 2 支付

# 2.1 余额查询（GET）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/getBalance

# CURL

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

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "amount": 87247.32,
        "noWithdrawalAmount": 0.00,
        "freezeAmount": 0.00
    },
    "requestId": "36fc030a-a110-4318-bc83-f39f9d3e5484"
}

返回字段	字段意思	字段类型	长度	备注
amount	余额	string	200	末尾2位小数点
noWithdrawalAmount	未支付金额	BigDecimal	（18，2）	单位：$（美元）
freezeAmount	冻结金额	BigDecimal	（18，2）	单位：$（美元）

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 2.2 余额支付（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalance

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalance' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "orderId": "210711100018655344"
                }'

返回字段	字段意思	字段类型	长度	备注
orderId	订单	string	200

沙盒说明：如果订单为沙盒订单（isSandbox=1），余额支付将走假支付/模拟支付流程，不会产生真实扣费。

注意：当母单下存在多个子订单时，不能使用本接口按单个orderId支付，请使用「余额支付V2」接口按shipmentOrderId支付。

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": 12,
    "requestId": "7dbe69b9-dd82-4ee3-907c-a6fca833e3ce"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回（订单号）
requestId	请求Id	string	48	用于日志查询错误

error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 2.3 余额支付V2（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalanceV2

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalanceV2' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "shipmentOrderId": "12",
                    "payId": "12"
                }'

返回字段	字段意思	字段类型	长度	备注
shipmentOrderId	母订单id	string	200
payId	payId	string	200	可选，不传系统自动生成

沙盒说明：如果母单下所有子订单均为沙盒订单（isSandbox=1），余额支付V2将自动走沙盒模拟支付流程，不会产生真实扣费。沙盒订单与普通订单不允许生成同一母单。

# 返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": 12,
    "requestId": "7dbe69b9-dd82-4ee3-907c-a6fca833e3ce"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回（订单号）
requestId	请求Id	string	48	用于日志查询错误

Error

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

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 3 订单发货信息

# 3.1 上传发货与面单信息(POST)

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/uploadWaybillInfo

提示：

上传面单文件时，请使用 multipart/form-data 格式提交请求。

需要在CJ订单支付之后才能调用此接口。

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/uploadWaybillInfo' \
                --header 'CJ-Access-Token:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ' \
                --form 'orderId="2511111146000642900"' \
                --form 'waybillFile=@"/C:/Users/Desktop/abcd.pdf"' \
                --form 'cjOrderId="DP2511111145580643400"' \
                --form 'cjShippingCompanyName="USPS"' \
                --form 'trackNumber="123123"'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	店铺订单Id	string	Y	200
cjOrderId	CJ订单Id	string	Y	200
cjShippingCompanyName	CJ物流品牌	string	Y	200	参考:获取仓库信息，获取：logisticsBrandList
trackNumber	追踪号	string	Y	200
waybillFile	面单文件	MultipartFile	Y	200

# Return

success

{
  "success": true,
  "message": "",
  "result": true,
  "data": true,
  "requestId": "52f1888a3b4f451d889a84218f2b50dc"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data	是否成功	Boolean
requestId	请求Id	string	48	用于日志查询错误

error

{
    "code": 806,
    "result": false,
    "message": "Warehouse “null” does not support logistics carrier “USPS”.",
    "data": null,
    "requestId": "309ad9d884ff4994b34f0da17853b970",
    "success": false
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 3.2 更新发货与面单信息(POST)

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/updateWaybillInfo

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/updateWaybillInfo' \
                --header 'CJ-Access-Token:xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx ' \
                --form 'orderId="2511111146000642900"' \
                --form 'waybillFile=@"/C:/Users/Desktop/abcd.pdf"' \
                --form 'cjOrderId="DP2511111145580643400"' \
                --form 'cjShippingCompanyName="USPS"' \
                --form 'trackNumber="123123"'

参数名称	参数意义	参数类型	是否必传	长度	备注
orderId	店铺订单Id	string	Y	200
cjOrderId	CJ订单Id	string	Y	200
cjShippingCompanyName	CJ物流品牌	string	Y	200	参考:获取仓库信息，获取：logisticsBrandList
trackNumber	追踪号	string	Y	200
waybillFile	面单文件	MultipartFile	Y	200

# Return

success

{
  "success": true,
  "message": "",
  "result": true,
  "data": true,
  "requestId": "52f1888a3b4f451d889a84218f2b50dc"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data	是否成功	Boolean
requestId	请求Id	string	48	用于日志查询错误

Error

{
    "code": 804,
    "result": false,
    "message": "This order does not use store platform logistics. Label upload not supported.",
    "data": null,
    "requestId": "715937dad5844ec49d51be43541eeb00",
    "success": false
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 3.3 修改POD图片属性(POST)

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/podProductCustomPicturesEdit

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/podProductCustomPicturesEdit' \
                --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'platformToken: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
                --header 'Content-Type: application/json' \
                --data-raw '{
                    "podPicturesEditParams": [
                        {
                            "orderCode": "123",
                            "lineItemId": "111",
                            "effectImgList": [
                                "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/245e348-a87b-4196-a3a4-056f6b391301.jpg"
                            ],
                            "productionImgList": [
                                "https://oss-cf.cjdropshipping.com/product/2025/04/22/01/245e348-a87b-4196-a3a4-056f6b391301.jpg"
                            ]
                        }
                    ]
                }'

参数名称	参数意义	参数类型	是否必传	长度
podPicturesEditParams		List	Y
-orderCode	CJ订单Id	string	Y	200
-lineItemId	CJ订单item的唯一id	string	Y	200
-effectImgList	实际生产图链接	List	Y	200
-productionImgList	实际效果图链接	List	Y	200

# Return

success

{
    "code": 200,
    "result": true,
    "message": "Congratulation! Well done!",
    "data": {
        "list": [
            {
                "orderCode": "123",
                "lineItemId": "111",
                "result": 2,
                "failedMessage": null
            },
            {
            "orderCode": "456",
            "lineItemId": "666",
            "result": 0,
            "failedMessage": "No matching order number found"
            }
        ]
    },
    "requestId": "fa65ceae2f5740459c3e8dc8cf32124c",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

data information

Field	Definition	Type	Length
list		List	Y
-orderCode	CJ订单Id	string	200
-lineItemId	CJ订单item的唯一id	string	200
-result	修改结果 0：失败，1：处理中 2：成功	int	20
-failedMessage	失败原因	string	200

Error

{
    "code": 804,
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "715937dad5844ec49d51be43541eeb00",
    "success": false
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200
data				接口数据返回
requestId	请求Id	string	48	用于日志查询错误

# 4 COGS

# 4.1 查询COGS基础数据订单信息(POST)

根据所提供订单编号查询基本数据订单信息列表。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/order/queryCogsBasicDataOrderInfoList

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/order/queryCogsBasicDataOrderInfoList' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json' \
     --data '{
         "orderCodesList": ["DP2506140734320969300"]
     }'

参数名	字段意思	字段类型	必填	长度	备注
orderCodesList	CJ订单号列表	`List<String>`	Y	-	cj订单号列表

# 返回

成功

{
    "code": 200,
    "data": [
        {
            "cogsBasicDataOrderInfoJson": {
                "a": "CJ2506144290356158893",
                "c": null,
                "d": 1,
                "f": 0.74,
                "g": 6.58,
                "h": 5.84,
                "ii": "38",
                "j": "2025-06-14T07:44:31"
            },
            "orderCode": "DP2506140734320969300",
            "originalOrderCode": "",
            "paymentDate": "2025-06-14T07:44:31",
            "userId": "e11a3d3e3230401ab3984c59949be6a9"
        }
    ],
    "message": "",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
orderCode	订单号	string	200
originalOrderCode	原订单号	string	200	拆单是拆单原始单号，合单是合单前单号
paymentDate	支付时间	LocalDateTime	-
userId	用户ID	string	200
cogsBasicDataOrderInfoJson	基础数据详情	object	-	见下方CogsBasicDataOrderInfoJson说明

# CogsBasicDataOrderInfoJson

属性	类型	JSON字段	说明
shipmentsOrderId	String	a	母订单ID
merchantNumber	String	s	客户ID
payFlag	Integer	d	支付标记（1：已支付）
postage	BigDecimal	f	总邮费-折扣后
totalAmount	BigDecimal	g	订单总金额
orderProductAmount	BigDecimal	h	订单商品总金额
paymentDate	LocalDateTime	j	付款时间
taxesInfo	Object	k	税费信息
productInfoMap	Map	z	商品数据（productCode → ProductInfo）
disputeInfoMap	Map	x	纠纷数据（disputeId → DisputeInfo）
diffAmountInfoMap	Map	c	补款金额信息
storeOrderInfo	Object	n	店铺订单信息
isOutOfStockSplit	Integer	m	是否采购缺货拆分
isReissue	Integer	qq	是否为补发单（0否，1是）
outStockFee	BigDecimal	rr	出库费用
storeCostFee	BigDecimal	tt	仓储费用
store	String	ii	仓库编号
countryCode	String	pp	收货国code

# ProductInfo

属性	类型	JSON字段	说明
productCode	String	pc	商品编码
sku	String	w	SKU
price	BigDecimal	t	商品实付单价
quantity	Integer	y	商品数量
productType	String	u	商品类型（0:正常,1:服务,3:包装,4:供应商,5:自发货,6:虚拟）
img	String	z	商品图片
isGift	Integer	h	是否赠品（0-否 1-是）
grams	BigDecimal	r	单重量（克）

# DisputeInfo

属性	类型	JSON字段	说明
productPriceFinal	BigDecimal	q	最终商品退款金额
iossTaxesFinal	BigDecimal	e	最终ioss税费
postageFinal	BigDecimal	p	最终退款运费
outboundCostFinal	BigDecimal	s	最终退款出库费
storageCostFinal	BigDecimal	d	最终退款仓储费

错误

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

# 5 合单

# 5.1 自动匹配可合单列表(POST)

获取自动匹配的可合并订单列表。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/autoMatchMergeOrderListV3

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/autoMatchMergeOrderListV3' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json' \
     --data '{
         "filterOrder": true,
         "orderStatus": 100
     }'

参数名	字段意思	字段类型	必填	长度	备注
filterOrder	是否过滤手动移除单	boolean	Y	1
orderStatus	订单状态	int	Y	10	100：完整订单页，101：购物车页

# 返回

成功

{
    "code": 200,
    "data": [
        {
            "haveMoreShopOrder": true,
            "mergeShopOrderVOList": [
                {
                    "city": "Shanghai",
                    "country": "China",
                    "countryCode": "CN",
                    "customerName": "张三",
                    "logisticsInfoList": [
                        {
                            "logisticsName": "顺丰速运",
                            "postage": 18.00,
                            "arrivalTime": "2023-11-20",
                            "isChecked": true
                        }
                    ]
                }
            ]
        }
    ],
    "message": "success",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
haveMoreShopOrder	是否存在多店铺订单	boolean	1	false-否，true-是
mergeShopOrderVOList	店铺订单列表	Array	-
- city	所在城市	string	200
- country	国家	string	200
- countryCode	国家编码	string	20
- customerName	收货人姓名	string	200
- logisticsInfoList	物流选项列表	Array	-
-- logisticsName	物流名称	string	200
-- postage	邮费	decimal	-
-- arrivalTime	预计到达时间	string	200
-- isChecked	当前选中的物流	boolean	1

# 5.2 自动合单进度查询(POST)

查询自动匹配合单列表的异步处理进度。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/autoMergeQueryProgress

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/autoMergeQueryProgress' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json'

# 返回

成功

{
    "code": 200,
    "data": {
        "noTask": false,
        "step": 2,
        "stepCount": [10, 20, 30, 10, 30],
        "stepPercent": 5000
    },
    "message": "success",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
noTask	当前没有提交任务要处理	boolean	1
step	当前步骤	int	10
stepCount	总步骤数	Array	-	数组长度代表步骤数，数组元素代表每一步骤占比
stepPercent	当前步骤进度	int	10	上限10000

# 5.3 自动合单匹配结果查询(POST)

查询自动匹配合单的异步处理结果。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/autoMergeQueryResult

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/autoMergeQueryResult' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json'

# 返回

成功

{
    "code": 200,
    "data": [
        {
            "haveMoreShopOrder": true,
            "mergeShopOrderVOList": [
                {
                    "city": "Shanghai",
                    "customerName": "张三",
                    "logisticsInfoList": [
                        {
                            "logisticsName": "顺丰速运",
                            "postage": 18.00
                        }
                    ],
                    "mergeOrderInfoList": [
                        {
                            "orderCode": "CJ123456789",
                            "orderNumber": "ORD987654",
                            "platform": "shopify",
                            "shopName": "我的店铺"
                        }
                    ]
                }
            ]
        }
    ],
    "message": "success",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
haveMoreShopOrder	是否存在多店铺订单	boolean	1	false-否，true-是
mergeShopOrderVOList	店铺订单列表	Array	-
- mergeOrderInfoList	合单订单信息列表	Array	-
-- orderCode	CJ订单号	string	200
-- orderNumber	客户订单号	string	200
-- platform	平台	string	50
-- shopName	店铺名称	string	200

# 5.4 提交批量自动合单(POST)

提交自动匹配分组的合并订单，将多个符合条件的订单合并为一个订单。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/submitMergeOrderBatchV3

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/submitMergeOrderBatchV3' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json' \
     --data '[
         {
             "logisticName": "顺丰速运",
             "orderCodeList": ["CJ123456789", "CJ987654321"],
             "orderNumber": "ORD123456",
             "orderStatus": 100,
             "packType": 0
         }
     ]'

参数名	字段意思	字段类型	必填	长度	备注
logisticName	物流名称	string	Y	50
orderCodeList	待合并CJ订单号列表	`List<String>`	Y	-
orderNumber	客户商铺订单号	string	Y	50
orderStatus	订单状态	int	Y	10	100：完整订单页，101：购物车页
packType	包装类型	int	Y	1	0：SKU，1：店铺

# 返回

成功

{
    "code": 200,
    "data": {
        "failGroupCount": 0,
        "failOrderCount": 0,
        "mergeFailOrderGroupList": [],
        "newOrderCodeList": ["CJ999888777"],
        "successGroupCount": 1,
        "successOrderCount": 2
    },
    "message": "success",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
failGroupCount	失败组数	int	10
failOrderCount	失败订单数	int	10
mergeFailOrderGroupList	失败订单列表及原因	Array	-
- errorCode	失败code	int	10	200：成功，11001-11007：各类错误，11100：其他
- orderCodes	订单集合	Array	-
newOrderCodeList	合并成功订单号	Array	-
successGroupCount	成功组数	int	10
successOrderCount	成功订单数	int	10

# 5.5 提交合单进度查询(POST)

查询提交合单的异步处理进度。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/submitProgress

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/submitProgress' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json'

# 返回

成功

{
    "code": 200,
    "data": {
        "noTask": false,
        "step": 1,
        "stepCount": [10, 20, 30, 10, 30],
        "stepPercent": 8000
    },
    "message": "success",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
noTask	当前没有任务处理	boolean	1
step	当前步骤	int	10
stepCount	总步骤数	Array	-	数组长度=步骤数
stepPercent	当前步骤进度	int	10	上限10000

# 5.6 提交合单结果查询(POST)

获取提交合单的异步处理结果。

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/submitResult

# CURL

curl --location 'https://developers.cjdropshipping.com/api2.0/v1/shopping/mergeOrder/submitResult' \
     --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
     --header 'Content-Type: application/json'

# 返回

成功

{
    "code": 200,
    "data": {
        "failGroupCount": 0,
        "failOrderCount": 0,
        "mergeFailOrderGroupList": [],
        "newOrderCodeList": ["CJ999888777"],
        "successGroupCount": 1,
        "successOrderCount": 2
    },
    "message": "success",
    "success": true
}

返回字段	字段意思	字段类型	长度	备注
failGroupCount	失败组数	int	10
failOrderCount	失败订单数	int	10
mergeFailOrderGroupList	失败订单列表及原因	Array	-
- errorCode	失败code	int	10	200：成功，11001：勾选订单数量=1，11002：订单异常，11003：订单信息为空，11004：地址不一致，11005：无可用物流，11006：存在供应商自发货订单，11007：订单状态变动，11100：其他错误
- orderCodes	订单集合	Array	-
newOrderCodeList	合并成功订单号	Array	-
successGroupCount	成功组数	int	10
successOrderCount	成功订单数	int	10

# 6 地址管理

地址管理接口用于维护当前账号地址簿，属于账号级地址簿能力，不是某一个具体下单流程的创建要素。服务端会按当前 CJ-Access-Token 自动设置用户信息，请求体不要传 userId 或 token。

# 6.1 地址列表（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/address/list

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/address/list' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{}'

返回 data[].id 是地址簿记录ID；创建私有库存SY单本身不使用该字段。

# 6.2 新增地址（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/address/create

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/address/create' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "firstName": "Gilbert",
        "lastName": "Soria",
        "country": "United States",
        "countryCode": "US",
        "province": "OH",
        "city": "HUBER HEIGHTS",
        "address": "3419 BROADMOOR BLVD1",
        "addressNew": "Apt 123",
        "zip": "222260",
        "phone": "9322331159",
        "mail": "test@example.com",
        "isDefault": "0"
    }'

# 6.3 修改地址（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/address/update

新增地址的全部字段均支持修改，并额外必传 id。如果只需要更新邮编，OpenAPI仍使用本接口：先通过地址列表取得原地址完整字段，再提交 id、完整地址必填字段和新的 zip。

参数名称	参数意义	参数类型	是否必传	长度	备注
id	地址ID	string	修改接口必传	100	从地址列表返回中获取
firstName	姓氏	string	新增/修改必传	100
lastName	名字	string	新增/修改必传	100
country	国家名称	string	新增/修改必传	100
countryCode	国家二字码	string	新增/修改必传	10	参照国家信息标准表
province	省/州	string	新增/修改必传	100
city	城市	string	新增/修改必传	100
address	地址1	string	新增/修改必传	200
addressNew	地址2	string	否	200
zip	邮编	string	否	30	地址资料字段；如需改邮编，通过修改地址接口一并提交
phone	电话	string	否	30
mail	邮箱	string	否	100
isDefault	是否默认地址	string	否	1	0-否，1-是
countyTown	县/区	string	否	100
consigneeId	收货人ID	string	否	100

# 6.4 地址接口返回字段

返回字段	字段意思	字段类型	备注
data	地址接口业务数据	object/list/boolean	地址列表返回数组；新增/修改返回地址操作结果
data[].id	地址ID	string	地址簿记录ID；不作为私有库存创建订单入参
data[].firstName / data[].lastName	姓名	string	地址联系人信息
data[].country / data[].countryCode	国家信息	string	国家名称和二字码
data[].province / data[].city	省州/城市	string	地址区域信息
data[].address / data[].addressNew	地址	string	地址1和地址2
data[].zip	邮编	string	地址邮编
data[].phone / data[].mail	电话/邮箱	string	联系方式
data[].isDefault	是否默认地址	string/integer	0-否，1-是

# 7 私有库存订单

私有库存订单接口用于通过OpenAPI完成备货/预购库存下单流程。推荐使用直接选择商品模式：查询私有库存商品 → 传入多个 variants 获取确认信息 → 获取仓库、物流和费用 → 直接提交多个 productList 创建SY订单。购物车接口仅作为暂存/查看辅助，不是下单前置步骤。

所有接口均使用 CJ-Access-Token 对应账号操作私有库存订单。本文档只描述调用方可见的公开接口、页面动作和字段含义。

# 私有库存下单公开接口时序图

私有库存下单先从商品列表接口获取可售商品和SKU信息。调用方从 /product/listV2 返回数据中选择商品ID、变体ID/SKU和数量，再按普通模式或购物车模式完成确认、选仓、选物流、创建订单和查询订单。

私有库存下单建议拆成两种对接方式：

普通模式：不使用购物车，直接把商品ID、SKU ID和数量整理成 variants，再确认仓库、物流和费用后创建订单。
购物车模式：先把商品加入私有库存购物车，再从购物车读取商品行，把要下单的SKU整理成 variants，后续确认和创建步骤与普通模式一致。

对接步骤	目的	接口对接时怎么做
获取商品信息	查询可售商品，取得商品ID、变体ID/SKU等下单基础信息	调 `/product/listV2`，从返回商品和SKU中选择本次要下单的商品行
选择对接模式	决定是否需要先暂存购物车	普通模式直接整理 `variants`；购物车模式先调 `/shopping/privateInventory/addToCart`，再调 `/shopping/privateInventory/getCart` 读取商品
确认仓库、物流和费用	获取可选仓库、物流方式和最终金额	调 `/shopping/privateInventory/getConfirmationWithCost`，按“只传 `variants` → 加 `storageId` → 加 `logisticName`”三步确认
创建私有库存订单	提交最终商品、仓库、物流和支付方式	调 `/shopping/privateInventory/createOrder` 创建订单；页面支付返回支付页面链接
私有库存余额支付	使用账户余额支付私有库存订单	调 `/shopping/pay/payBalanceV2`，使用创建订单返回的订单号、支付单ID和私有库存订单类型发起余额支付
查询订单	获取创建结果和后续状态	调 `/shopping/privateInventory/order/list` 查询私有库存订单

# 页面查看入口

页面链接需要使用同一个官网账号登录查看；未登录时会先进入登录页，登录后再回到对应页面。

操作结果	官网页面	说明
加入私有库存购物车后	私有库存购物车 (opens new window)	可查看刚加入购物车的私有库存商品；也可通过 `/shopping/privateInventory/getCart` 接口读取同一批数据
创建私有库存订单后	私有库存订单列表 (opens new window)	可查看创建后的私有库存订单；如需定位指定订单，可在页面搜索订单号，或在链接后追加 `&orderNumber=SY1234567890`

订单列表链接里的 orderType=2 是官网页面筛选私有库存订单的参数；余额支付接口仍按上文传 orderType=9。

图中的接口路径可点击跳转到对应接口章节。

# 普通模式：直接选择商品下单

sequenceDiagram
    participant You as 你的系统
    participant Product as 商品列表接口
    participant Cost as 确认/仓库/费用接口
    participant CreateApi as 创建订单接口
    participant BalancePay as 余额支付接口
    participant Orders as 订单列表接口

    Note over You,Orders: 普通模式：不使用购物车，直接用商品ID、SKU ID和数量下单
    You->>Product: GET /product/listV2
    Product-->>You: 返回商品ID、变体ID/SKU和商品信息
    You->>Cost: POST /shopping/privateInventory/getConfirmationWithCost(variants)
    Cost-->>You: 返回确认商品和可选仓库
    You->>Cost: POST /shopping/privateInventory/getConfirmationWithCost(variants, storageId)
    Cost-->>You: 返回该仓库可选物流和费用
    You->>Cost: POST /shopping/privateInventory/getConfirmationWithCost(variants, storageId, logisticName)
    Cost-->>You: 返回最终金额
    You->>CreateApi: POST /shopping/privateInventory/createOrder(productList, storageId, logisticName, payType)
    alt 页面支付
        CreateApi-->>You: 返回订单号、支付单ID和支付页面链接
    else 余额支付
        CreateApi-->>You: 返回订单号和支付单ID
        You->>BalancePay: POST /shopping/pay/payBalanceV2(shipmentOrderId, payId, orderType)
        BalancePay-->>You: 返回余额支付结果
    end
    You->>Orders: POST /shopping/privateInventory/order/list
    Orders-->>You: 返回私有库存订单状态

# 购物车模式：先暂存再下单

sequenceDiagram
    participant You as 你的系统
    participant Product as 商品列表接口
    participant AddCart as 加入购物车接口
    participant Cart as 购物车接口
    participant Cost as 确认/仓库/费用接口
    participant CreateApi as 创建订单接口
    participant BalancePay as 余额支付接口
    participant Orders as 订单列表接口

    Note over You,Orders: 购物车模式：先暂存商品，再把购物车商品转成下单入参
    You->>Product: GET /product/listV2
    Product-->>You: 返回商品ID、变体ID/SKU和商品信息
    You->>AddCart: POST /shopping/privateInventory/addToCart(productId, variants)
    AddCart-->>You: 返回加购结果
    You->>Cart: POST /shopping/privateInventory/getCart
    Cart-->>You: 返回购物车商品、SKU和数量
    Note over You,Cart: 把要下单的购物车SKU整理为 variants
    You->>Cost: POST /shopping/privateInventory/getConfirmationWithCost(variants)
    Cost-->>You: 返回确认商品和可选仓库
    You->>Cost: POST /shopping/privateInventory/getConfirmationWithCost(variants, storageId)
    Cost-->>You: 返回该仓库可选物流和费用
    You->>Cost: POST /shopping/privateInventory/getConfirmationWithCost(variants, storageId, logisticName)
    Cost-->>You: 返回最终金额
    You->>CreateApi: POST /shopping/privateInventory/createOrder(productList, storageId, logisticName, payType)
    alt 页面支付
        CreateApi-->>You: 返回订单号、支付单ID和支付页面链接
    else 余额支付
        CreateApi-->>You: 返回订单号和支付单ID
        You->>BalancePay: POST /shopping/pay/payBalanceV2(shipmentOrderId, payId, orderType)
        BalancePay-->>You: 返回余额支付结果
    end
    You->>Orders: POST /shopping/privateInventory/order/list
    Orders-->>You: 返回私有库存订单状态

# 7.0 创建订单要素来源

创建订单前，请让用户确认商品、数量、仓库、物流和支付方式。商品可以来自商品列表、购物车或确认结果；仓库、物流和费用以接口返回的可选内容为准。

创建字段/辅助项	来源	使用位置	备注
商品ID、变体ID、SKU	商品列表接口 `/product/listV2`、购物车或确认信息返回	`productList[].productId`、`productList[].variantId`、`productList[].sku`	最终创建必传；商品ID表示买哪个商品，变体ID表示买哪个SKU。
数量	用户在商品页或购物车选择的数量	`productList[].quantity`	最终创建必传；表示每个SKU要买几件。
仓库ID	`getConfirmation` / `getConfirmationWithCost` 返回的 `availableStorehouseList[].storageId`	`getCostInfo.storageId`、`createOrder.storageId`	最终创建必传；从私有库存可选仓库列表选择。不要使用固定示例值。
物流名称	`logistics/list` 返回的 `availableLogisticList[].logisticName`；也可直接从 `getCostInfo.freightTrialList` 选中行获取	`createOrder.logisticName`、`getConfirmationWithCost.logisticName`	最终创建必传；必须选择当前仓库和商品可用的物流。
商品单价	当前商品价格	接口计算	创建订单无需提交价格；最终金额以接口返回为准。
费用明细	`getCostInfo` 或 `getConfirmationWithCost` 返回	下单前展示与确认	非创建入参。
支付方式	用户选择	`createOrder.payType`	可选；1=页面支付，返回支付页面链接；2=余额支付，可继续调用余额支付接口完成支付。

# 7.1 加入私有库存购物车（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/addToCart

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/addToCart' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "productId": "422C91F3-B7D0-47F3-BC66-5E1FE3208BBA",
        "variants": [
            {"variantId": "V001-SKU-A", "quantity": 100}
        ]
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
productId	商品ID	string	是	200	可从私有库存商品查询接口获取
variants	SKU列表	list	是		要加入购物车的SKU和数量列表
variants[].variantId	变体ID	string	是	200
variants[].quantity	数量	integer	是	20	1-100000

# 返回字段

返回字段	字段意思	字段类型	备注
data	加购结果	object/boolean	部分环境可能直接返回布尔值
data.success	是否加购成功	boolean	返回时表示本次加购是否成功
data.addedCount	成功加入SKU行数	integer	返回时表示成功加入购物车的SKU行数

加购成功后，可打开私有库存购物车 (opens new window) 查看商品；接口侧也可继续调用 /shopping/privateInventory/getCart 获取购物车数据。

# 7.2 获取私有库存购物车（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getCart

请求体可省略；未传请求体时，服务端按空对象处理并默认查询私有库存购物车全部商品。分页参数仍然支持，pageSize 最大100，超过100时OpenAPI按100条处理。

# CURL（不传请求体，按默认查询）

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getCart' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx'

# CURL（分页查询）

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getCart' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{"pageNum":1,"pageSize":20,"isAll":0}'

参数名称	参数意义	参数类型	是否必传	长度	备注
pageNum	页码	integer	否	20	不传时使用默认页码
pageSize	每页条数	integer	否	20	不传时使用默认条数；最大100，超过100时按100处理
isAll	是否查询全部	integer	否	1	0-不查全部，1-查全部；未传默认1

# 返回字段

返回字段	字段意思	字段类型	备注
data.productList	购物车商品列表	list	按商品聚合的有效购物车商品
data.productList[].productId	商品ID	string	商品ID
data.productList[].productName	商品名称	string	展示字段
data.productList[].productImage	商品图片	string	展示字段
data.productList[].variants	SKU行列表	list	商品下的购物车SKU/变体行
data.productList[].variants[].id	购物车SKU行ID	string	购物车SKU行标识
data.productList[].variants[].variantId	变体ID	string	SKU/规格ID
data.productList[].variants[].sku	SKU编码	string	SKU编码
data.productList[].variants[].quantity/count	数量	integer	SKU数量
data.productList[].variants[].price	最终备货单价	number	美元；仅用于展示/参考，创建订单无需提交价格
data.invalidProductList	无效商品列表	list	有不可购买或失效商品时返回
data.totalAmount	购物车商品金额	number	美元，仅用于展示，创建请求不传订单总价
data.selectVariantCount	SKU数量	integer	统计字段；公开创建流程不依赖购物车选中状态
data.currencyInfo	币种信息	object	通常包含 `currencyCode`、`currencySymbol`

# 7.3 删除私有库存购物车商品（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/removeFromCart

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/removeFromCart' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{"variantIds":["V001-SKU-A"]}'

参数名称	参数意义	参数类型	是否必传	长度	备注
variantIds	变体ID列表	list	是		要删除的SKU变体ID列表

删除标识说明：删除购物车商品时传 variantIds 即可，取值来自 getCart 返回的SKU行 id 或 variantId。

# 返回字段

返回字段	字段意思	字段类型	备注
data	删除结果	boolean/object	通常返回布尔值；如返回对象则表示删除明细

# 7.4 获取私有库存订单确认信息（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getConfirmation

# 直接选择商品确认模式 CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getConfirmation' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "variants": [
            {"variantId": "V001-SKU-A", "productId": "422C91F3-B7D0-47F3-BC66-5E1FE3208BBA", "quantity": 100}
        ]
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
variants	变体列表	list	否		直接选择商品确认时传；推荐显式传入，支持多个商品行
variants[].variantId	变体ID	string	直接选择模式必传	200
variants[].productId	商品ID	string	直接选择模式必传	200
variants[].quantity	数量	integer	直接选择模式必传	20	本次要确认的SKU购买数量

# 返回字段

返回字段	字段意思	字段类型	备注
data.orders	确认页订单分组	list	按商品、仓库等维度聚合的确认信息
data.availableStorehouseList	私有库存可选仓库列表	list	可用于选择仓库ID
data.availableStorehouseList[].storageId	仓库ID	string	传给 `logistics/list.storageId`、`getCostInfo.storageId`、`createOrder.storageId`
data.availableStorehouseList[].displayName	仓库名称	string	仓库名称
data.availableStorehouseList[].countryCode / areaId	仓库国家/区域	string/integer	用于展示或区域判断
data.availableStorehouseList[].addresses / address / zipCode	仓库地址/邮编	string	有值时用于展示仓库位置
data.availableStorehouseList[].selected	是否选中	boolean	是否为本次请求 `storageId` 命中的仓库
data.selectedStorageId	已选仓库ID	string	本次请求命中的仓库ID；未传或不可用时为空
data.selectedStorehouse	已选仓库对象	object	字段同 `availableStorehouseList[]`；未传或不可用时为空
data.orders[].logisticList	确认页物流候选	list	仅为确认页返回；最终可创建物流优先从 `logistics/list.availableLogisticList` 选择
data.orders[].products	确认商品行	list	可整理为最终创建接口 `productList`
data.orders[].products[].id / variantId	变体ID	string	创建时传 `productList[].variantId`
data.orders[].products[].productId	商品ID	string	创建时传 `productList[].productId`
data.orders[].products[].sku	SKU编码	string	创建时传 `productList[].sku`
data.orders[].products[].quantity / count / itemCount	数量	integer	创建时传 `productList[].quantity`
data.orders[].products[].price / nowPrice	最终备货单价	number	美元；仅用于展示/参考，创建订单无需提交价格，最终以服务端实时计算为准
data.totalProductPrice	商品金额汇总	number	美元，仅用于展示，创建请求不传订单总价
data.currencyInfo	币种信息	object	通常包含 `currencyCode`、`currencySymbol`

# 7.5 获取私有库存可用物流（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/logistics/list

该接口用于获取已选仓库下可用的物流方式。请在用户选好商品、数量和仓库后调用，并从返回列表中选择创建订单使用的物流名称。

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/logistics/list' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "storageId": "WAREHOUSE-HZ-001",
        "variantInfoList": [
            {"id": "V001-SKU-A", "quantity": 100}
        ]
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
storageId	仓库ID	string	是	200	从 `getConfirmation` 或 `getConfirmationWithCost` 返回的 `availableStorehouseList[].storageId` 中选择
variantInfoList	变体信息	list	是		费用接口商品明细
variantInfoList[].id	变体ID	string	是	200
variantInfoList[].quantity	数量	integer	是	20

# 返回数据结构

字段	类型	说明
storageId	string	本次用于查询物流的仓库ID
availableLogisticList	list	可选物流精简扁平列表，来自费用接口 `freightTrialList[]`
availableLogisticList[].logisticName	string	创建订单和费用匹配使用的物流名称
availableLogisticList[].displayName	string	物流展示名称
availableLogisticList[].logisticCode	string	物流编码；有值时返回
availableLogisticList[].shippingCost	number	物流费用；来自 `freightTrialList[].shippingCost` 等费用字段，按美元保留2位小数
availableLogisticList[].estimateDays	string	预计时效；有值时返回
availableLogisticList[].freightIndex	integer	物流来源的费用行序号，从0开始
availableLogisticList[].selected	boolean	默认选中状态；创建订单仍以调用方最终选择的 `logisticName` 为准
selectedLogisticName	string	默认选中的物流名称；无选中物流时为空
logisticInfoMessage	string	未传仓库或未返回可用物流时的提示；正常有物流时通常为空

# 7.6 获取私有库存费用明细（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getCostInfo

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getCostInfo' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "storageId": "WAREHOUSE-HZ-001",
        "variantInfoList": [
            {"id": "V001-SKU-A", "quantity": 100}
        ]
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
storageId	入库仓库ID	string	是	200	从确认信息返回的 `availableStorehouseList[].storageId` 中选择
variantInfoList	变体信息	list	是		费用接口商品明细
variantInfoList[].id	变体ID	string	是	200
variantInfoList[].quantity	数量	integer	是	20
logisticName	已选物流名称	string	否	200	可选；用于费用接口/整合金额匹配选中物流。仅获取物流候选时可不传

# 返回字段

返回字段	字段意思	字段类型	备注
data.freightAmount / data.logisticsCost / data.shippingCost	物流费用	number	不同场景可能返回不同字段名，以实际响应字段为准
data.warehouseFee / data.storehouseCost	仓库/出库费用	number	不同场景可能返回不同字段名，以实际响应字段为准
data.serviceFee	服务费	number	美元
data.freightTrialList	可用物流费用行	list	`logistics/list.availableLogisticList` 来源
data.freightTrialList[].logisticName / enName	物流名称	string	可作为 `createOrder.logisticName` 候选值
data.freightTrialList[].shippingCost	物流费用	number	美元
data.freightTrialList[].selected	是否选中	boolean	客户显式传 `logisticName` 未命中时不回退该默认值
data.costDetails	费用明细	list	返回时表示费用明细列表
data.errorEnList / data.errorSuggestionList	错误和建议	list	费用异常时可能返回

# 7.7 获取确认与费用整合信息（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getConfirmationWithCost

此接口用于同时获取确认信息、可选仓库和费用信息。首次可不传 storageId 获取仓库列表；用户选定仓库后传入 storageId 获取费用；用户选定物流后再传入 logisticName 获取最终金额。

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/getConfirmationWithCost' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "storageId": "WAREHOUSE-HZ-001",
        "logisticName": "CJ Packet Ordinary",
        "variants": [
            {"variantId": "V001-SKU-A", "productId": "422C91F3-B7D0-47F3-BC66-5E1FE3208BBA", "quantity": 100}
        ]
    }'

首次请求可不传 storageId；选择仓库后传入 storageId；选择物流后传入 logisticName 获取最终金额。

# 可选仓取值说明

availableStorehouseList 是仓库选择列表，字段如下：

字段	类型	说明
availableStorehouseList[].storageId	string	下次请求 `storageId` 或创建订单 `storageId` 可直接使用的仓库ID
availableStorehouseList[].displayName	string	仓库名称
availableStorehouseList[].countryCode	string	仓库国家/地区编码
availableStorehouseList[].areaId	integer	仓库区域ID
availableStorehouseList[].addresses	string	仓库地址信息
availableStorehouseList[].address	string	仓库地址信息别名，便于调用方直接取值
availableStorehouseList[].zipCode	string	仓库邮编；有值时返回
availableStorehouseList[].selected	boolean	是否为本次请求传入并用于费用试算的仓；未传或未命中 `storageId` 时为 `false`

# 返回数据结构

字段	类型	说明
confirmation	object	确认信息
availableStorehouseList	list	可选仓库列表，包含仓库ID、仓库名称、国家/地区、地址和选中状态
selectedStorageId	string	本次请求传入且命中候选仓的仓库ID；未传或不可用时为空
selectedStorehouse	object	本次请求命中的仓库对象，字段同 `availableStorehouseList[]`，并带 `selected=true`；未传或不可用时为空
costInfo	object	已选仓对应费用明细，结构同 `getCostInfo` 的 `data`；只有请求传入有效 `storageId` 时才调用费用接口
amountDetail	object	金额明细汇总，金额均为美元并保留2位小数；包含商品行金额、服务费、已选或默认选中的物流费；仓库和物流已选且金额项完整时返回 `totalAmount`
amountDetail.productAmountList	list	商品行金额明细，包含 `variantId`、`productId`、`sku`、`quantity`、最终备货单价 `unitPrice` 和商品行小计 `productAmount`；不返回批发价等其他价格口径
amountDetail.productAmountList[].unitPrice	number	最终备货单价，美元，保留2位小数
amountDetail.productAmountList[].productAmount	number	商品行小计，美元，保留2位小数
amountDetail.productAmount	number	商品总金额，美元，保留2位小数；如果商品行金额缺失则为空
amountDetail.serviceFee	number	服务费，美元，保留2位小数，来自 `costInfo.serviceFee`
amountDetail.requestedLogisticName	string	本次请求传入、用于匹配费用行的物流名称；未传时为空
amountDetail.selectedFreight	object	用于汇总的物流费用行；未传 `logisticName` 时才可取默认选中的费用行，已传 `logisticName` 但未命中时不回退默认选中行，也不默认取第一条
amountDetail.shippingCost	number	已选物流费用，美元，保留2位小数，来自 `amountDetail.selectedFreight.shippingCost`
amountDetail.totalAmount	number	商品总金额 + 服务费 + 物流费，美元，保留2位小数；仅在仓库已选、物流已选且关键金额项都存在时返回
amountDetail.totalAmountCalculated	boolean	是否已成功计算总金额；为 `false` 时查看 `missingAmountItems`。物流未选、仓库不可用、费用接口因服务费配置等原因报错时不会强行给总金额
amountDetail.missingAmountItems	list	缺失金额项；物流未选时通常包含 `selectedFreight`，存在缺失时不强行返回总金额
costInfoMessage	string	未传仓库、仓库不可用、无可用仓或无商品信息导致无法计算费用时返回说明；正常有费用时通常为空

# 7.8 创建私有库存订单（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/createOrder

创建私有库存订单前，请确认商品、仓库、物流和支付方式都已经选好。页面支付会返回支付页面链接；余额支付可使用创建结果继续调用私有库存余额支付接口。

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/createOrder' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "productList": [
            {"variantId": "V001-SKU-A", "productId": "422C91F3-B7D0-47F3-BC66-5E1FE3208BBA", "sku": "CJJJJTJT00873-Black", "quantity": 100},
            {"variantId": "V002-SKU-B", "productId": "D9B2A2E0-88A1-44A6-9F7D-PRIVATE-B", "sku": "CJJJJTJT00873-White", "quantity": 50}
        ],
        "logisticName": "CJ Packet Ordinary",
        "storageId": "WAREHOUSE-HZ-001",
        "payType": 1
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
productList	最终提交商品列表	list	是		不能为空，支持多个商品行
productList[].variantId	变体ID	string	是	200	SKU/规格ID
productList[].productId	商品ID	string	是	200
productList[].sku	SKU	string	是	200
productList[].quantity	数量	integer	是	20	该SKU最终下单数量
productList[].price	最终备货单价	BigDecimal	否	(18,2)	可选且非必填；不作为创建订单计费依据，最终价格以接口返回为准
logisticName	物流名称	string	是	200	从 `logistics/list` 返回的 `availableLogisticList[].logisticName` 中选择
storageId	仓库ID	string	是	200	从 `getConfirmation` 或 `getConfirmationWithCost` 返回的 `availableStorehouseList[].storageId` 中选择
payType	支付方式	integer	否	10	1=页面支付，创建成功后返回支付页面链接；2=余额支付

页面支付时，创建成功会返回支付页面链接；余额支付时，可使用创建结果中的订单号和支付单ID调用私有库存余额支付接口。

# 返回字段

返回字段	字段意思	字段类型	备注
data.orderId / data.orderCode	SY订单号	string	创建成功后的私有库存订单号，字段名以实际响应为准
data.payId	支付单ID	string	返回时表示关联的支付单ID
data.cjPayUrl	支付页面链接	string	页面支付时返回
data.price	创建结果金额	number	美元，以实际响应为准
data.riskInterceptOrderList	风控拦截订单列表	list	风控拦截时可能返回
data.checkPlaceOrderInfo	不可下单校验详情	object	服务端最终校验失败时返回
data.checkPlaceOrderInfo.confirmStatus	是否可下单	boolean	`false` 表示商品、仓库、物流、库存、价格或重量等发生变化
data.checkPlaceOrderInfo.productInfoVOList	不可下单商品列表	list	包含变体ID、SKU和不可下单原因
data.availableLogisticList	当前可选物流	list	当 `logisticName` 不可用时返回，字段同 `logistics/list.availableLogisticList`
data.requestedLogisticName	请求物流名称	string	创建请求中传入但未命中的物流名称

创建成功后，可打开私有库存订单列表 (opens new window) 查看订单；如需直接定位订单，可在页面搜索订单号，或在链接后追加 &orderNumber=订单号。

# 7.9 余额支付 V2（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalanceV2

该接口支持多种订单类型的余额支付，通过 orderType 区分：

私有库存订单（orderType=9）：创建订单后用余额支付。shipmentOrderId 使用创建订单返回的 data.orderId 或 data.orderCode；payId 来自创建订单返回的 data.payId（可选）。
补款单（orderType=24）：对 makeup/createPayOrder 生成的补款支付单用余额扣款。shipmentOrderId 使用 createPayOrder 返回的 data.payOrderCode；payId 与 amount 均必传（来自 createPayOrder 返回的 data.payId 与 data.amount）。
默认（不传 orderType）：普通代发单余额支付。

# CURL - 私有库存订单示例

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalanceV2' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "shipmentOrderId": "SY1234567890",
        "orderType": 9,
        "payId": "PAY1234567890"
    }'

# CURL - 补款单示例

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/pay/payBalanceV2' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "shipmentOrderId": "2605260000000001",
        "orderType": 24,
        "payId": "PAY260526000001"
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
shipmentOrderId	订单号	string	是	100	私有库存传 `createOrder` 返回的 `orderId`；补款单传 `createPayOrder` 返回的 `payOrderCode`
orderType	订单类型	integer	否	20	`9`=私有库存；`24`=补款单(母单-补款订单MD_BK)；不传默认普通代发单
payId	支付单ID	string	否/必传	100	私有库存可选（未传时自动生成）；补款单必传，使用 `createPayOrder` 返回的 `data.payId`

# 返回字段

返回字段	字段意思	字段类型	备注
code	错误码	int	见返回错误码标准表
result	是否正常返回	boolean	`true` 表示接口处理成功
message	返回信息	string	处理结果说明
data	支付结果标识	string	通常返回本次支付对应的订单号，字段值以实际响应为准
requestId	请求ID	string	用于问题排查

# 7.10 查询私有库存订单列表（POST）

# URL

https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/order/list

# CURL

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/order/list' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "pageNum": 1,
        "pageSize": 10,
        "orderContent": "SY1234567890",
        "createOrderDateStart": 1717200000000,
        "createOrderDateEnd": 1719791999000
    }'

参数名称	参数意义	参数类型	是否必传	长度	备注
pageNum	页码	integer	否	20	默认1，最小1；用于指定返回第几页数据
pageSize	每页条数	integer	否	20	默认10，最大200；超过最大值会返回参数错误
orderContent	搜索关键字	string	否	100	一次传一个关键字；支持私有库存订单号（SY开头）、支付单号、SKU、商品名称等订单列表可搜索内容
orderStatus	订单状态	string	否	50	常用值：3=Awaiting Payment，11=Payment Incoming，10=Pending，6=Awaiting Dispatch，12=Dispatched，7=Completed，13=Closed，8=Canceled；不传则查询可展示状态的订单
payStatus	待支付细分状态	integer	否	1	仅在 `orderStatus=3` 时生效；不传=待支付和支付中，0=Awaiting Payment，1=Payment Incoming
createOrderDateStart	创建时间开始	long	否	20	毫秒时间戳；查询创建时间晚于该值的订单
createOrderDateEnd	创建时间结束	long	否	20	毫秒时间戳；查询创建时间早于该值的订单
isAmountDifference	是否差异订单	integer	否	1	不传=不过滤，1=仅查询存在金额差异的订单，0=仅查询无金额差异的订单

# 返回字段

返回字段	字段意思	字段类型	备注
data.pageSize	每页数量	number	本次响应的每页条数
data.pageNumber	当前页码	number	本次响应的页码
data.totalRecords	总记录数	number	符合筛选条件的订单总数
data.totalPages	总页数	number	按 `pageSize` 计算得到的总页数
data.content	订单列表	list	当前页的私有库存订单明细

data.content[] 订单字段：

返回字段	字段意思	字段类型	备注
orderCode	SY订单号	string	私有库存订单唯一编号
status	订单状态编码	string	如3、11、10、6、12、7、13、8等
statusDesc	订单状态文案	string	订单状态展示名称，如Awaiting Payment、Pending、Dispatched等
disputeStatus	纠纷相关订单状态	string	有纠纷记录时返回
storageId	仓库ID	string	订单使用的私有库存仓库ID
storageNo2Name	仓库名称	string	仓库英文名或展示名
stockout	是否缺货	boolean	`true`表示订单存在缺货信息
logisticName	物流名称	string	下单时选择的物流线路名称
logisticsMode	物流方式	string	物流方式或线路类型
postage	物流费用	number	USD金额
showPostage	展示物流费用	number	按账号展示币种换算后的金额
trackingNumber	运单号	string	承运商运单号，有运单后返回
cjTrackingNumber	CJ运单号	string	CJ侧运单号，有运单后返回
paymentExpirationTime	支付超时时间	number	毫秒时间戳；待支付订单可参考该值
inventoryReserved	库存是否仍锁定	boolean	待支付且未超时时通常为 `true`
createDate	创建时间	string	格式示例：2021-10-12 01:33
createDateTime	创建时间戳	number	毫秒时间戳
paymentDate	支付时间	string	支付后返回，格式同 `createDate`
paymentDateTime	支付时间戳	number	毫秒时间戳，支付后返回
orderAmount	商品总价	number	USD商品金额
showOrderAmount	展示商品总价	number	按账号展示币种换算后的商品金额
amount	订单总金额	number	USD订单总额，通常包含商品、物流、服务费、税费等
showAmount	展示订单总金额	number	按账号展示币种换算后的订单总额
payableAmount	应付划线金额	number	优惠前或应付展示金额，存在时返回
showPayableAmount	展示应付划线金额	number	按账号展示币种换算后的金额
discountMoney	平台总优惠金额	number	USD优惠金额
productDiscountMoney	商品优惠金额	number	USD商品优惠金额
postageDiscountMoney	运费优惠金额	number	USD运费优惠金额
serviceFee	服务费	number	USD服务费
showServiceFee	展示服务费	number	按账号展示币种换算后的服务费
iossNumber	IOSS号	string	使用IOSS申报时返回
iossType	IOSS申报类型	integer	1=不使用IOSS，2=使用我的IOSS，3=使用CJ IOSS
iossTaxes	IOSS税费	number	USD税费金额
taxesFlag	是否税费代缴	integer	0=不代缴，1=代缴
taxesType	税费类型	integer	0=无，1=欧盟IOSS，2=巴西Duty税费
orderQuantity	商品总数量	integer	订单内所有商品数量合计
stockoutRefundStatus	缺货退款状态	string	0=待退款，1=已退款，2=已拒绝
impStorageFlag	入库订单标识	string	私有库存订单相关标识
isContainPack	是否包含包装商品	integer	0=否，1=是
orderSourceType	订单来源类型	string	如Excel上传、店铺同步等
paymentSign	支付中提示标识	string	0=不提示，1=提示银行卡付款中
handlerResult	缺货处理结果	string	如分开发货、缺货商品替换、缺货退款等
refundAmount	退款金额	number	有退款时返回
refundStatus	退款状态	integer	1=待退款，2=已退款
refundTime	退款时间	string	有退款时返回
orderType	订单类型	integer	私有库存订单通常为2
orderCategory	订单类别	string	私有库存通常为SY
paymentType	支付方式	string	如Stripe、PayPal、Checkout等，支付后可能返回
variantTypeSum	变体种类数量	integer	订单内SKU/变体种类数
diffType	差异来源类型	integer	1=手动创建，2=订单审核，3=物流费补收
diffAmount	差异金额	number	USD差异金额
showDiffAmount	展示差异金额	number	按账号展示币种换算后的差异金额
openDispute	是否可开纠纷	boolean	`true`表示当前状态允许开纠纷
abnormalPerformanceType	履约异常类型	integer	0=无，1=异常，2=完成
paymentOrderCodeList	支付单号列表	list	订单关联的支付单号
isRepeatPayment	是否重复支付	integer	0=否，1=是
isShowInventoryRecord	是否显示库存记录	integer	0=不显示，1=显示
canPayPostage	是否可支付物流费	integer	有物流费补缴情形时返回
postagePayStatus	物流费支付状态	integer	1=待补充物流信息，2=待支付，3=支付中，4=已支付
postagePayStatusDesc	物流费支付状态文案	string	物流费支付状态展示名称
postagePayStatusRemark	物流费支付说明	string	物流费支付状态补充说明
selfPickAddressInfo	自提地址信息	object	自提订单返回
selfPickCode	自提取件码	string	自提订单返回
currencyInfo	货币信息	object	展示币种、汇率等信息
isReceipt	是否签收	integer	0=否，1=是
canViewWarehouseVideo	是否可查看仓库作业视频	boolean	`true`表示可查看
noViewWarehouseVideoReason	不可查看视频原因	integer	不可查看时返回原因编码

data.content[].supplierList[] 与商品字段：

返回字段	字段意思	字段类型	备注
supplierId	供应商ID	string	商品所属供应商ID
supplierName	供应商名称	string	商品所属供应商名称
productList	商品SPU列表	list	按供应商分组后的商品列表
productList[].productId	商品ID	string	CJ商品SPU ID
productList[].productVariantListList	商品变体列表	list	当前商品下的SKU/变体列表
productVariantListList[].productCode	订单商品ID	string	订单商品行编号
productVariantListList[].orderCode	所属订单号	string	对应 `orderCode`
productVariantListList[].stanProductId	变体ID	string	CJ商品变体ID
productVariantListList[].sku	SKU	string	商品SKU
productVariantListList[].cjProductId	商品ID	string	CJ商品SPU ID
productVariantListList[].cjProductName	商品名称	string	CJ商品英文名称
productVariantListList[].cjImage	商品图片	string	商品图片URL
productVariantListList[].property	属性	string	商品属性
productVariantListList[].variantKey	规格	string	变体规格值
productVariantListList[].quantity	数量	integer	购买数量
productVariantListList[].allocateNum	入库数量	integer	已入库或库存分配数量
productVariantListList[].originalPrice	商品原价	number	USD原价
productVariantListList[].showOriginalPrice	展示商品原价	number	按账号展示币种换算后的原价
productVariantListList[].price	商品单价	number	USD单价
productVariantListList[].showPrice	展示商品单价	number	按账号展示币种换算后的单价
productVariantListList[].discount	商品折扣率	number	存在折扣时返回
productVariantListList[].weight	重量	number	商品重量，通常为克
productVariantListList[].refundStatus	商品退款状态	integer	1=待退款，2=已退款
productVariantListList[].productType	商品类型	string	商品类型标识
productVariantListList[].stockout	是否缺货	boolean	`true`表示该商品缺货
productVariantListList[].handlerResult	商品处理结果	string	缺货或异常处理结果
productVariantListList[].originalSku	原SKU	string	SKU变更时返回原SKU
productVariantListList[].groupProduct	是否组合商品	boolean	`true`表示组合商品
productVariantListList[].isPod	是否POD商品	integer	POD商品标识
productVariantListList[].unCertified	商品信息是否缺失	integer	1=商品信息缺失，其他值表示完整
productVariantListList[].productGroupChildList	组合子商品列表	list	组合商品时返回
productGroupChildList[].id	子商品变体ID	string	子商品变体ID
productGroupChildList[].sku	子商品SKU	string	子商品SKU
productGroupChildList[].nameEn	子商品名称	string	子商品英文名称
productGroupChildList[].image	子商品图片	string	子商品图片URL
productGroupChildList[].itemCount	子商品数量	integer	子商品数量
productGroupChildList[].allocateNum	子商品入库数量	integer	子商品已入库或库存分配数量
productGroupChildList[].variantKey	子商品规格	string	子商品规格值
productGroupChildList[].packWeight	子商品包装重量	number	单件包装重量
productGroupChildList[].totalPackWeight	子商品总包装重量	number	数量乘以包装重量
productGroupChildList[].price	子商品价格	number	USD价格

响应可能包含更多订单展示字段；请以上表主要字段为准，未列出的扩展字段按实际返回值使用。

# 通用返回

success

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {},
    "requestId": "2b97f15603384fe4832e85617cf07d9c"
}

error

{
    "code": 1600100,
    "result": false,
    "message": "Param error",
    "data": null,
    "requestId": "2b97f15603384fe4832e85617cf07d9c"
}

返回字段	字段意思	字段类型	长度	备注
code	错误码	int	20	返回错误码标准表
result	是否正常返回	boolean	1
message	返回信息	string	200	查询失败时返回参数或业务错误信息
data	接口数据	object		成功时为订单列表分页数据，失败时可能为null
requestId	请求Id	string	48	用于日志查询错误

# 8 私有库存出库单

私有库存出库单接口用于通过 OpenAPI 完成 OMS 私有库存出库单创建、库存锁定进度轮询、提交出库单以及支付/母单状态查询。所有接口均使用 CJ-Access-Token 对应账号操作，服务端会自动解析 userId、userNum 和用户 token，调用方不要传客户编号、userId、merchantId、permissionCode、systemInvoke、createUserId、createUserName、thirdStorage、deliveryType 等 OMS 后台或内部字段。

出库使用的私有库存来源，可登录 MyCJ 在「仓储 → 私有库存」模块查看对应的私有订单信息与库存信息。

# 8.1 接口清单

接口	方法	说明
`/api2.0/v1/shopping/privateInventory/outbound/address/list`	POST	查询当前 token 用户地址列表
`/api2.0/v1/shopping/privateInventory/outbound/product/query`	POST	按发货仓、SKU/SPU 或 `privateOrderId` 查询可出库商品
`/api2.0/v1/shopping/privateInventory/outbound/product/batch-refresh`	POST	创建前批量刷新已选商品可用库存
`/api2.0/v1/shopping/privateInventory/outbound/create`	POST	创建或更新私有库存出库单，可传 `submit=true` 创建后自动提交
`/api2.0/v1/shopping/privateInventory/outbound/progress`	POST	查询创建进度、锁定失败商品、提交/支付状态
`/api2.0/v1/shopping/privateInventory/outbound/submit`	POST	提交私有库存出库单
`/api2.0/v1/shopping/privateInventory/outbound/detail`	POST	查询出库单详情
`/api2.0/v1/shopping/privateInventory/outbound/cancel`	POST	取消未完成出库单

推荐调用顺序：address/list → product/query → product/batch-refresh → create → 循环调用 progress，进度完成后调用 submit 或在创建时传 submit=true，再继续轮询 progress 查看支付/母单状态。若提交阶段返回库存不足/锁定失败，不要重复提交原请求；请查详情、减少数量或删除失败商品行、带原 orderId 重新调用 create 更新后再次提交。

# 8.1.1 调用时序图与对接说明

图中带 outbound/... 的接口文本会在页面渲染后自动转换为可点击跳转，点击蓝色下划线接口名可进入对应接口说明。

sequenceDiagram
    autonumber
    participant Client as OpenAPI 调用方
    participant API as CJ OpenAPI

    Client->>API: outbound/address/list 查询地址候选
    API-->>Client: address 字段候选
    Client->>API: outbound/product/query(storageId, skuOrSpu/privateOrderId)
    API-->>Client: 商品候选
    Client->>API: outbound/product/batch-refresh(products)
    API-->>Client: 最新可出库数量
    Client->>API: outbound/create(form, address, productList, submit)
    API-->>Client: orderId + nextAction=POLL_CREATE_PROGRESS
    loop 创建进度轮询
        Client->>API: outbound/progress(orderId)
        API-->>Client: createProgress/createStatus/lockFails/nextAction
    end
    alt lockFails 不为空或 nextAction=ADJUST_LOCK_FAIL_PRODUCTS
        Client->>API: outbound/detail(orderId)
        API-->>Client: 出库单和商品行回显
        Client->>API: outbound/create(orderId + 调整后的商品行)
        API-->>Client: orderId + nextAction
    else lockFails 为空且 nextAction=SUBMIT_ORDER
        Client->>API: outbound/submit(orderId)
        API-->>Client: submitAccepted + nextAction
    end
    Client->>API: outbound/progress(orderId)
    API-->>Client: submitStatus/paymentStatus/shipmentOrderId/paymentOrderId
    opt 查看详情或取消未完成出库单
        Client->>API: outbound/detail(orderId)
        API-->>Client: 出库单详情
        Client->>API: outbound/cancel(orderId, reason)
        API-->>Client: 取消结果
    end

对接说明：客户侧 OpenAPI 不依赖 OMS 页面登录态，也不要传 userId、userNum、customerNo 等内部身份字段；客户身份必须由 CJ-Access-Token 解析并由服务端注入。调用方应以 /progress 和 /submit 的返回为准处理下一步动作。

# 8.1.2 地址模块与出库地址复用时序说明

地址模块维护的是当前账号地址簿，可先通过 地址列表、新增地址、修改地址 准备地址资料，再通过私有库存出库单的 address/list 获取当前 token 下可用于出库的地址候选，最终将地址字段回填到 create 的 address 对象。当前公开地址模块只暴露列表、新增、修改能力，未发现删除地址公开接口，因此时序图不体现删除流程。

图中的 地址模块 address/... 与 outbound/... 接口文本会在页面渲染后自动变为可点击跳转。

sequenceDiagram
    autonumber
    participant Client as OpenAPI 调用方
    participant API as CJ OpenAPI

    Client->>API: 地址模块 address/list 查询地址簿
    API-->>Client: 地址簿列表
    opt 需要新增地址
        Client->>API: 地址模块 address/create 提交完整地址字段
        API-->>Client: 返回操作结果
    end
    opt 需要修改地址
        Client->>API: 地址模块 address/update(id + 完整地址字段)
        API-->>Client: 返回操作结果
    end
    Client->>API: outbound/address/list 获取出库地址候选
    API-->>Client: 回填 create.address 所需字段
    Client->>API: outbound/create(address + productList)
    API-->>Client: 返回 orderId 和下一步动作

# 8.2 地址列表（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/address/list

请求体可为空。返回字段用于回填创建接口 address。

请求示例：

{}

响应示例：

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": [
        {
            "id": "ADDR001",
            "name": "Gilbert Soria",
            "countryCode": "US",
            "province": "OH",
            "city": "HUBER HEIGHTS",
            "address": "3419 BROADMOOR BLVD1",
            "addressNew": "Apt 123",
            "zip": "222260",
            "phone": "9322331159",
            "mail": "test@example.com"
        }
    ]
}

返回字段	类型	说明
data[].id	string	地址记录 ID，仅用于地址簿展示。
data[].name	string	收货人完整姓名，可回填 `address.customerName`。
data[].firstName / data[].lastName	string	收货人名/姓。
data[].country / data[].countryCode	string	国家名称/国家二字码。
data[].province / data[].city / data[].countyTown	string	省州、城市、县镇；`countyTown` 可回填 `address.town`。
data[].address / data[].addressNew	string	地址 1 / 地址 2。
data[].zip / data[].phone / data[].mail	string	邮编、电话、邮箱。
data[].consigneeId	string	收件人 ID，可回填 `address.consigneeId`。

# 8.3 查询可出库商品（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/product/query

参数名称	参数意义	参数类型	是否必传	备注
storageId	发货仓 ID	string	是	当前出库仓库。
skuOrSpu	SKU/SPU 搜索词	string	否	与 `privateOrderId` 至少传一个。
privateOrderId	私有库存订单号	string	否	下游映射为 `privateOrderCode`。
orderId	出库单号	string	否	更新出库单时传入；下游映射为 `orderCode`。

返回字段	类型	说明
data[].id	string	商品行 ID；更新已有出库单商品行时使用。
data[].uid	string	行唯一值，一般由 `privateOrderId + stanProductId` 组成。
data[].productId / data[].spu / data[].sku	string	商品 ID、SPU、SKU。
data[].stanProductId	string	标准商品变体 ID，创建接口必传。
data[].productName / data[].productImg	string	商品名称、商品图片。
data[].value1 / data[].value2 / data[].value3	string	SKU 规格值。
data[].price	number	商品中心返回的当前展示单价；创建时 OMS 会再次获取商品中心最新价格。
data[].privateOrderId	string	私有库存订单号。
data[].availableQuantity	integer	当前可出库数量。
data[].lockQuantity	integer	当前出库单已锁定数量，更新订单时用于回显。

# 8.4 批量刷新已选商品库存（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/product/batch-refresh

参数名称	参数意义	参数类型	是否必传	备注
storageId	发货仓 ID	string	是	当前出库仓库。
orderId	出库单号	string	否	更新出库单时用于排除当前单已锁定数量。
products	已选商品	list	是	不能为空。
products[].privateOrderId	私有库存订单号	string	是	下游映射为 `privateOrderCode`。
products[].stanProductId	标准商品变体 ID	string	是	需要刷新库存的变体。
products[].price	展示价格	number	否	刷新库存不依赖该字段。

响应示例：

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": [
        {
            "privateOrderId": "PO26050001",
            "stanProductId": "CJVAR001",
            "uid": "PO26050001-CJVAR001",
            "availableQuantity": 118
        }
    ]
}

返回字段	类型	说明
data[].privateOrderId	string	私有库存订单号。
data[].stanProductId	string	标准商品变体 ID。
data[].uid	string	行唯一值。
data[].availableQuantity	integer	当前可出库数量。

现有响应主要返回 privateOrderId、stanProductId、uid、availableQuantity；完整商品展示信息请以 /product/query 或 /detail 为准。

# 8.5 创建私有库存出库单（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/create

curl --location --request POST 'https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/create' \
    --header 'CJ-Access-Token: xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx' \
    --header 'Content-Type: application/json' \
    --data-raw '{
        "orderNumber": "OUTBOUND-API-001",
        "storageId": "08898c4735bf43068d5d677c1d217ab0",
        "platform": "API",
        "storeName": "API Store",
        "postagePayNode": 4,
        "address": {
            "customerName": "Gilbert Soria",
            "shippingAddress": "3419 BROADMOOR BLVD1",
            "shippingAddress2": "Apt 123",
            "city": "HUBER HEIGHTS",
            "country": "United States",
            "countryCode": "US",
            "province": "OH",
            "zipCode": "222260",
            "phone": "9322331159",
            "email": "test@example.com"
        },
        "productList": [
            {
                "sku": "CJJJJTJT00873-Black",
                "stanProductId": "CJVAR001",
                "privateOrderId": "PO26050001",
                "quantity": 2
            }
        ],
        "submit": false
    }'

参数名称	参数意义	参数类型	是否必传	备注
orderId	出库单号	string	更新时必传	创建时不传；下游映射为 `orderCode`。
orderNumber	自定义单号	string	是	页面“自定义单号”。
storageId	发货仓 ID	string	是	页面“发货仓”。
platform	店铺类型	string	否	不传时后端按默认策略处理。
storeName	店铺名称	string	否	调用方自定义展示字段。
postagePayNode	物流费支付节点	integer	是	`4`=出库前付，`5`=出库后付，`6`=无需支付。
reason	申请原因	string	`postagePayNode=6` 时必传	申请原因。
reasonEn	英文申请原因	string	否	英文申请原因。
address.customerName	收货人	string	是	可从地址列表 `name` 回填。
address.shippingAddress / address.shippingAddress2	地址 1 / 地址 2	string	地址1必传	收货地址。
address.city / address.province / address.town	城市/省州/县镇	string	城市必传	`town` 可由地址列表 `countyTown` 回填。
address.countryCode / address.country	国家二字码/国家名称	string	`countryCode` 必传	国家二字码用于 OMS 校验。
address.zipCode / address.phone / address.email	邮编/电话/邮箱	string	否	收货联系信息。
address.taxId / address.consigneeId	税号/收件人 ID	string	否	可选。
productList	商品行	list	是	不能为空。
productList[].id	已有商品行 ID	string	更新商品行时必传	新建出库单可不传。
productList[].uid	行唯一值	string	否	建议回传用于排查，当前创建逻辑不依赖。
productList[].sku	SKU	string	是	商品 SKU。
productList[].stanProductId	标准商品变体 ID	string	是	来自 `/product/query`。
productList[].price	展示价格	number	否	非可信入参；OMS 创建时按商品中心最新价格写入订单。
productList[].privateOrderId	私有库存订单号	string	是	下游映射为 `privateOrderCode`。
productList[].quantity	出库数量	integer	是	必须大于 0 且不超过可用库存。
submit	是否自动提交	boolean	否	默认 `false`。

成功时返回：

返回字段	类型	说明
data.orderId	string	出库单号；下游字段为 `orderCode`。
data.createTaskStarted	boolean	是否已创建异步任务。
data.submitRequested	boolean	是否请求创建完成后自动提交。
data.nextAction	string	下一步动作，通常为 `POLL_CREATE_PROGRESS`。

# 8.6 查询进度（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/progress

请求体：

{
    "orderId": "SD260526000001"
}

响应示例：

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "orderId": "SD260526000001",
        "createProgress": 60,
        "createStatus": "CREATE_SUB_ORDER_SUCCESS",
        "nextAction": "WAIT_LOCK_ARRIVE",
        "lockFails": []
    }
}

返回字段	类型	说明
data.orderId	string	出库单号。
data.progress / data.createProgress	number	创建进度，当前主要为 `0/60/100`。
data.createStatus	string	`PROCESSING`、`CREATE_SUB_ORDER_SUCCESS`、`TASK_COMPLETE`、`LOCK_FAIL`。
data.lockFails	list	锁定失败商品；有值时需调整商品数量。
data.lockFails[].sku / data.lockFails[].privateOrderId	string	锁定失败 SKU / 私有库存订单号。
data.lockFails[].quantity / data.lockFails[].lockQuantity	integer	申请出库数量 / 实际锁定数量。
data.nextAction	string	`WAIT_CREATE`、`WAIT_LOCK_ARRIVE`、`ADJUST_LOCK_FAIL_PRODUCTS`、`SUBMIT_ORDER` 等。
data.submitStatus / data.paymentStatus	string	当前第一版未聚合到提交/支付状态时为 `UNKNOWN`。

锁定失败处理：当 createStatus=LOCK_FAIL、nextAction=ADJUST_LOCK_FAIL_PRODUCTS 或 lockFails 不为空时，不要直接调用 /submit，也不要继续依赖 create.submit=true 自动提交。请先调用 /detail 获取当前出库单和商品行回显，再按 lockFails[].lockQuantity / availableQuantity 删除失败商品或降低 productList[].quantity，然后带 orderId 再次调用 /create 更新出库单，继续轮询 /progress，直到 createProgress=100、createStatus=TASK_COMPLETE、lockFails 为空且 nextAction=SUBMIT_ORDER 后再提交。部分商品已锁定不代表整单可以提交；只有更新后的商品行全部可锁定时才允许提交。

# 8.7 提交出库单（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/submit

参数名称	参数意义	参数类型	是否必传	备注
orderId	出库单号	string	是	创建接口返回的 `data.orderId`。

响应字段：

返回字段	类型	说明
data.orderId	string	出库单号。
data.submitAccepted	boolean	OMS 已接受提交请求。
data.nextAction	string	下一步动作，通常为 `POLL_SUBMIT_PROGRESS`、`WAIT_APPROVAL`、`PAY` 或 `FINISHED`；库存不足/锁定失败时为 `ADJUST_LOCK_FAIL_PRODUCTS`。

库存不足/锁定失败返回示例：

{
    "code": 1603001,
    "result": false,
    "message": "Private inventory is insufficient. Please call /shopping/privateInventory/outbound/detail, reduce productList.quantity or remove failed product lines, call /shopping/privateInventory/outbound/create again with the same orderId, then submit again.",
    "data": {
        "orderId": "SD260526000001",
        "createStatus": "LOCK_FAIL",
        "submitAccepted": false,
        "nextAction": "ADJUST_LOCK_FAIL_PRODUCTS",
        "actionRequired": "ADJUST_QUANTITY_AND_RESUBMIT",
        "lockFails": [
            {
                "sku": "CJNSXZXX001-Black-S",
                "privateOrderId": "SY260526000001",
                "quantity": 10,
                "lockQuantity": 6
            }
        ],
        "suggestedSteps": [
            "Call /shopping/privateInventory/outbound/detail with orderId to review product lines.",
            "Reduce productList.quantity or remove failed product lines according to lockFails/availableQuantity.",
            "Call /shopping/privateInventory/outbound/create again with the same orderId to update the outbound order.",
            "Poll /shopping/privateInventory/outbound/progress until lockFails is empty and nextAction is SUBMIT_ORDER, then submit again."
        ]
    }
}

提交前请先确认 /progress 返回可提交状态：lockFails 必须为空，且 nextAction 不能是 ADJUST_LOCK_FAIL_PRODUCTS。如果 /submit 返回上面的库存不足/锁定失败业务错误，说明这不是系统服务异常，调用方应按 data.lockFails / availableQuantity 调整商品数量或删除失败商品行，带原 orderId 再次调用 /create 更新出库单，继续轮询 /progress，直到可提交后再调用 /submit。

出库单提交成功后，客户可登录 MyCJ 在 https://www.cjdropshipping.com/mine/dropshipping/orderList?orderType=7 (opens new window) 页面查看该私有库存出库单。

# 8.8 查询出库单详情（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/detail

参数名称	参数意义	参数类型	是否必传	备注
orderId	出库单号	string	是	用于编辑回显、锁定失败后重试或查看详情。

主要返回字段：

返回字段	类型	说明
data.orderId / data.orderNumber	string	出库单号 / 自定义单号。
data.storageId / data.platform / data.storeName	string	发货仓、店铺类型、店铺名称。
data.postagePayNode	integer	物流费支付节点。
data.address	object	收货信息，字段同创建接口 `address`。
data.productList	list	商品行，字段同创建接口并带 `availableQuantity`、`lockQuantity`、`price` 等回显字段。
data.orderStatus / data.submitStatus	string	OMS 订单状态 / API 聚合提交状态。

# 8.9 取消出库单（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/privateInventory/outbound/cancel

参数名称	参数意义	参数类型	是否必传	备注
orderId	出库单号	string	是	待取消的出库单。
reason	取消原因	string	否	调用方备注。

响应字段：

返回字段	类型	说明
data.orderId	string	已取消的出库单号；部分 OMS 版本可能直接返回布尔值或原始下游对象。
data.cancelled	boolean	是否取消成功。

提交、详情、取消接口都会校验当前 CJ-Access-Token 客户是否拥有该出库单；状态不允许操作时，以 OMS 返回错误为准。

# 9 补款单（Makeup）

补款单（Makeup）接口路径前缀 /api2.0/v1/shopping/makeup/*，用于获取未支付补款单、创建补款支付单（返回 payId、cjPayUrl），以及通过 payId 完成余额支付。type 区分 0=Make-up Orders（订单补款）/ 1=Other Make-up；diffUseType 细分 Other Make-up 的用途。

# 9.1 调用时序图

sequenceDiagram
    autonumber
    participant Client as OpenAPI 调用方
    participant API as CJ OpenAPI
    participant Browser as 浏览器/支付页

    Client->>API: POST /shopping/makeup/list(pageNum, pageSize, type, diffUseType)
    API-->>Client: 返回补款分页、未支付数量、未支付总金额
    Client->>API: POST /shopping/makeup/createPayOrder(orderCodes, type, diffUseType)
    API-->>Client: 返回 payOrderCode、payId、amount、cjPayUrl、paymentPagePath
    alt 跳转支付页支付
        Client->>Browser: 跳转 cjPayUrl https://www.cjdropshipping.com/mine/payment?pid={payId}
        Browser-->>Client: 用户在支付页完成支付
    else 直接调用余额支付
        Client->>API: POST /shopping/pay/payBalanceV2(shipmentOrderId=payOrderCode, payId, orderType=24)
        API-->>Client: 返回余额支付结果
    end
    Note over Client,API: 创建 payId 后由调用方选择跳转支付页，或调 POST /shopping/pay/payBalanceV2(orderType=24) 直接余额支付
    Client->>API: POST /shopping/makeup/list(pageNum, pageSize, type)
    API-->>Client: 重新获取补款状态

# 9.2 获取补款列表（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/makeup/list

请求示例：

{
    "pageNum": 1,
    "pageSize": 20,
    "type": 0
}

参数名称	参数意义	参数类型	是否必传	备注
pageNum	页码	integer	否	默认 `1`。
pageSize	每页数量	integer	否	默认 `10`，最大 `200`。
type	补款类型	integer	否	`0`=Make-up Orders（订单补款），`1`=Other Make-up（其他补款）；不传时返回第一个有未支付数据的类型。
diffUseType	补款用途	integer	否	`type=1` 时可用于筛选：`1`=Balance Top-up，`2`=Repayment，`3`=Transfer Shipping Fee；`type=0` 可不传或传 `0`。

响应示例：

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "type": 0,
        "totalAmount": 12.35,
        "unPaymentCountList": [
            { "type": 0, "count": 2 },
            { "type": 1, "count": 0 }
        ],
        "pageData": {
            "pageSize": 20,
            "pageNumber": 1,
            "totalRecords": 2,
            "totalPages": 1,
            "content": [
                {
                    "orderCode": "BK260526000001",
                    "cjOrderCode": "ZF260526000001",
                    "status": 0,
                    "amount": 12.35,
                    "reason": "Postage difference",
                    "orderType": 1,
                    "diffUseType": 0,
                    "createAt": 1779763200000
                }
            ]
        }
    },
    "requestId": "2b97f15603384fe4832e85617cf07d9c"
}

返回字段	类型	说明
data.type	integer	当前返回的补款类型。
data.totalAmount	number	当前筛选条件下未支付补款总金额，单位 USD。
data.unPaymentCountList[].type / count	integer	各补款类型的未支付数量。
data.pageData.content[].orderCode	string	补款单号；余额支付时放入 `orderCodes`。
data.pageData.content[].cjOrderCode	string	关联 CJ 订单号。
data.pageData.content[].status	integer	补款单状态：`0`=待提交，`1`=处理中，`2`=失败，`3`=取消，`4`=完成，`5`=支付中。
data.pageData.content[].amount	number	补款金额，单位 USD。
data.pageData.content[].reason	string	英文补款原因。
data.pageData.content[].orderType	integer	关联订单类型，用于页面分类展示。
data.pageData.content[].diffUseType	integer	补款用途：`0`=订单补款，`1`=Balance Top-up，`2`=Repayment，`3`=Transfer Shipping Fee。
data.pageData.content[].createAt	long	创建时间，Unix 毫秒时间戳。

# 9.3 创建补款支付单（POST）

URL: https://developers.cjdropshipping.com/api2.0/v1/shopping/makeup/createPayOrder

该接口对齐 MyCJ 页面“勾选补款单 → Pay”的真实流程：从补款列表取 orderCode，调用后生成补款支付单和 payId。页面拿到 payId 后会跳转 https://www.cjdropshipping.com/mine/payment?pid={payId}；OpenAPI 返回同格式的 cjPayUrl 以及相对路径 paymentPagePath 供调用方选择使用。该接口只创建支付单，不执行余额扣款。

请求示例：

{
    "orderCodes": ["BK260526000001"],
    "type": 0
}

参数名称	参数意义	参数类型	是否必传	备注
orderCodes	补款单号列表	array<string>	是	来自补款列表 `orderCode`，至少传 1 个。
type	补款类型	integer	否	默认 `0`；`0`=Make-up Orders（订单补款），`1`=Other Make-up（其他补款）。
diffUseType	补款用途	integer	`type=1` 时必传	`type=0` 可不传或传 `0`；`type=1` 时传 `1`=Balance Top-up、`2`=Repayment、`3`=Transfer Shipping Fee。

响应示例：

{
    "code": 200,
    "result": true,
    "message": "Success",
    "data": {
        "payOrderCode": "2605260000000001",
        "payId": "PAY260526000001",
        "amount": 12.35,
        "cjPayUrl": "https://www.cjdropshipping.com/mine/payment?pid=PAY260526000001",
        "paymentPagePath": "/mine/payment?pid=PAY260526000001"
    },
    "requestId": "2b97f15603384fe4832e85617cf07d9c"
}

返回字段	类型	说明
data.payOrderCode	string	本次补款支付单号。
data.payId	string	支付中心支付 ID；MyCJ 页面使用它跳转支付页。
data.amount	number	本次待支付金额，单位 USD。
data.cjPayUrl	string	CJ 支付页完整地址，格式为 `https://www.cjdropshipping.com/mine/payment?pid={payId}`。
data.paymentPagePath	string	MyCJ 页面支付路径，格式为 `/mine/payment?pid={payId}`。

补款支付：拿到 createPayOrder 返回的 payId 后，调用方可直接跳转 cjPayUrl 支付页完成支付，或按支付类型 orderType 调用 /shopping/pay/payBalanceV2 用当前账号余额支付。

← 4 仓储 6 物流 →