API document
I.Basic Information
1.HTTP method:
HTTP POST
2.Data format
Data from Json Response
3.Query Parameters
Head Content Type: application/x-www.form-urlencoded
Key (Mandatory parameter)
Query key (32 randomly generated alpha-numeric character); It is considered a security number provided by the company given to the partnership, used to identify the source of query parameter and avoid unauthorized illegal access.
Other parameters
Depends on your specific circumstances, see API information below
4.Response data
Code
Status Code
200 – Succeeded (OK)
600 – Server Exception
603 – The parameter is incorrect
Message
Describe return an error message
II.API Information
1.Obtain balance
https:///Api/UserInfo.ashx
Query Parameters:
Post Parameter |
Mandatory field |
Information |
Key |
Yes |
Retrieve a key from your registered carriers |
Response
Attributes |
Information |
Code |
Status Code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error message |
Data |
User Information |
Example
Postman example:
Query Parameter:
Key = 88888888888888888888888888888888
Return Value:
{
"Code": "200",
"Message": null,
"Data": {
"Balance": 888.88
}
}
2.Received packages and packages delivery services
https:///Api/Express/GetCarrierList.ashx
Query Parameter:
Post Parameter |
Mandatory Field |
Information |
Key |
Yes |
Retrieve a key from your registered carriers |
Language |
No |
english=english;chinese=chinese.The default is chinese |
Response
Attributes |
Information |
Code |
Status code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error Message |
Data |
Carrier list |
Example
Postman Example:
Query Parameter:
Key = 88888888888888888888888888888888
Return Value:
{
"Code": "200",
"Message": null,
"Data": [{
"ServiceList": ["FedEx SmartPost", "FedEx Home Delivery", "FedEx Ground"],
"Name": "FedEx Test",
"IsInsure": true,
"IsMultParcel": true,
}, {
"ServiceList": ["usps_first_class_mail", "usps_media_mail", "usps_parcel_select", "usps_priority_mail", "usps_priority_mail_express", "usps_first_class_mail_international", "usps_priority_mail_international", "usps_priority_mail_express_international"],
"Name": "USPS"
"IsInsure": false,
"IsMultParcel": true,
}]
}
3.Shipping Rates Inquiry
https:///Api/Express/Rates.ashx
Query Parameter:
Post Parameter |
Mandatory field |
Information |
Key |
Yes |
Retrieve a key of your registered carriers |
Language |
No |
english=english;chinese=chinese.The default is chinese |
Data |
Yes |
|
Shipment
Parameter |
Mandatory |
Types |
|
Carrier |
Yes |
String |
Obtained from the API of “2. Received packages and packages delivery services”
|
ShipFrom |
Yes |
ShipAddr |
Sender information |
ShipTo |
Yes |
ShipAddr |
Recipient information |
Parcels |
Yes |
List<Parcels> |
Parcels list |
ItemList |
Yes |
List <Item> |
Item information list (new) |
FreightClass |
No |
String |
UPS GFP FREIGHT_CLASS (Mandatory field). Other class does not require this parameter |
Signature |
No |
Bool |
Required signature or not; signature not required by default. |
WeightUnitType |
No |
Int |
Unit type; 0 = lb./in; 1 – kg/cm; 2 = oz/in; default to 0. |
ShipAddr
Parameter |
Mandatory |
Type |
Description |
Postal Code |
Yes |
String |
Postal Code |
Name |
Yes |
String |
Name |
Company |
No |
String |
Company |
Address1 |
Yes |
String |
Address1 |
Address2 |
Yes |
String |
Address2 |
State |
Yes |
String |
State |
City |
Yes |
String |
City |
Country |
Yes |
String |
Support US area only |
Phone Number |
No |
String |
Phone Number |
AddrType |
No |
Int |
0= Self-determination(default);1 = Business; 2 = residential
|
Parcel
Parameter |
Mandatory field |
Type |
Description |
Weight |
Yes |
Round to 2 decimal places |
Package Weight |
Length |
Yes |
Round to 2 decimal places |
Length |
Width |
Yes |
Round to 2 decimal places |
Width |
Height |
Yes |
Round to 2 decimal places |
Height |
Insure |
No |
Round to 2 decimal places |
Insurance Coverage Limit; only available when carrier provide insurance service
|
Item (new)
Parameter |
Mandatory fields |
Type |
Description |
SKU |
Yes |
String |
SKU |
Quantity |
Yes |
Int |
Quantity |
Response
Attributes |
Information |
Code |
Status code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error Message |
Rate |
Rate Json – Rate information |
Example
Query Parameter:
Data = {
"Carrier": "ups2",
"ShipFrom": {
"PostalCode": "47906",
"Name": "xiaoyang hu",
"Address1": "1138 anthrop dr",
"Address2": null,
"State": "IN",
"City": "West Lafayette",
"Country": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
},
"ShipTo": {
"PostalCode": "60609",
"Name": "Jing zhang",
"Address1": "2023 w 35th st",
"Address2": null,
"State": "IL",
"City": "Chicago",
"Country": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
},
"Parcels": [{
"Weight": 3,
"Length": 22,
"Width": 22,
"Height": 22
}],
"ItemList": [{
"Sku": "TEST123456789",
"Quantity": 3
}]
}&Key = 88888888888888888888888888888888
Return Value:
{
"Code": "200",
"Message": "",
"Data": [{
"RateId": "rate_fa3adcab1d084bd290fd92149a8aeb0c",
"Carrier": "self_ups",
"CarrierServiceLevel": "Ground",
"CarrierServiceName": "Ground",
"ChargeWeight": 3,
"TotalCharge": 29.42,
"PackageType": null
}, {
"RateId": "rate_fa9cdf649a33426b9cdfd3883f5ec8af",
"Carrier": "self_ups",
"CarrierServiceLevel": "3DaySelect",
"CarrierServiceName": "3DaySelect",
"ChargeWeight": 3,
"TotalCharge": 77.59,
"PackageType": null
}, {
"RateId": "rate_8a5d4079079348668e071a1ffdfed6dd",
"Carrier": "self_ups",
"CarrierServiceLevel": "NextDayAir",
"CarrierServiceName": "NextDayAir",
"ChargeWeight": 3,
"TotalCharge": 182.84,
"PackageType": null
}]
}
4.Create Shipping Label
API: https:///Api/Express/CreateLabel.ashx
Query Parameter:
Post Parameter |
Mandatory field |
Description |
Key |
Yes |
Retrieve a key of your registered carriers |
Language |
No |
english=english;chinese=chinese.The default is chinese |
Data |
Yes |
Shipment Json; String Serializable |
Shipment
Parameter |
Mandatory fields |
Type |
Description |
Order Num |
No |
String |
Minimum 8 digits. Access request required; automatic generated if leave this field empty. Nothing needs to be filled if unable to access. |
Carrier |
Yes |
String |
Obtained from the API of “Received packages and packages delivery services” |
CarrierServiceLevel |
Yes |
String |
Obtained from the API of “Received packages and packages delivery services” |
ShipFrom |
Yes |
ShipAddr |
Sender information |
ShipTo |
Yes |
ShipAddr |
Recipient information |
Parcels |
Yes |
List<Parcels> |
Parcels List |
ItemList |
Yes |
List<Item> |
Item List (new) |
FreightClass |
No |
String |
UPS GFP FRIGHT_CLASS is mandatory. Other class does not required. |
Signature |
No |
Bool |
Default to signature not required |
LabelSize |
No |
Int |
Label size: 0 = 4 x 6; 1 = A4; defaults to 4x6 |
Remark 1 |
No |
String |
Remark 1 |
Remark 2 |
No |
String |
Remark 2 |
WeightUnitType |
No |
Int |
Unit Type: 0 = lb/in; 1= kg/cm; 2 = oz/in; default to 0 |
EcOrder |
No |
String |
Ecommerce order |
AutoChangeService |
No |
Bool |
Most FedEx account numbers are available (Specific details please contact IT department for more information). Auto change to FedEx Ground/FedEx Home Delivery depends on the address type |
ShipAddr
Parameter |
Mandatory field |
Type |
Description |
Postal Code |
Yes |
String |
Postal Code |
Name |
Yes |
String |
Name |
Company |
No |
String |
Company |
Address 1 |
Yes |
String |
Address 1 |
Address 2 |
Yes |
String |
Address 2 |
State |
Yes |
String |
State |
City |
Yes |
String |
City |
Country |
Yes |
String |
Support US area only |
Phone Number |
No |
String |
Phone number |
AddrType |
No |
Int |
0= Self-determination(default); 1= Business; 2 = Residential |
Parcel
Parameter |
Mandatory Field |
Type |
Description |
Weight |
Yes |
Round to 2 decimal places |
Package weight |
Length |
Yes |
Round to 2 decimal places |
Length |
Width |
Yes |
Round to 2 decimal places |
Width |
Height |
Yes |
Round to 2 decimal places |
Height |
Insure |
No |
Round to 2 decimal places |
Insurance coverage limit; only available if carrier provide insurance |
Picking |
No |
String |
Picking information; only available if carrier supported |
Item (new)
Parameter |
Mandatory field |
Type |
Description |
Sku |
Yes |
String |
Sku |
Quantity |
Yes |
Int |
Quantity |
Response
Attributes |
Description |
Code |
Status code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error message |
Shipment |
Shipment Json – Order information |
Example
Query Parameter:
Data = {
"Carrier": "ups2",
"CarrierServiceLevel": "Ground",
"ShipFrom": {
"PostalCode": "47906",
"Name": "xiaoyang hu",
"Address1": "1138 anthrop dr",
"Address2": null,
"State": "IN",
"City": "West Lafayette",
"Country": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
},
"ShipTo": {
"PostalCode": "60609",
"Name": "Jing zhang",
"Address1": "2023 w 35th st",
"Address2": null,
"State": "IL",
"City": "Chicago",
"Country": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
},
"OrderNum": null,
"Parcels": [{
"Weight": 3,
"Length": 22,
"Width": 22,
"Height": 22
}],
"ItemList": [{
"Sku": "TEST123456789",
"Quantity": 3
}]
}&Key = 88888888888888888888888888888888
Return Value:
{
"Code": "200",
"Message": null,
"Data": {
"LabelReady": true, //Is the label ready, such as false 、//ShipmentId,LabelUrl,TranckingNumbers No data,need to wait//10-100second Request for API label information to obtain these data
"ShipmentId": "shp_f771f2934f7f48459a6c7998b40cfb0e",
"LabelUrl": "http://localhost:55862/UploadFiles/Self/1Z13R10R0398374459.pdf",
"ShippingWeight": 2,
"FactWeight": 2,
"ShippingPrice": 29.42,
"TrackingNumbers": ["1Z13R10R0398374459"],
"Carrier": "ups2",
"CarrierServiceLevel": "Ground",
"ShipFrom": {
"PostalCode": "47906",
"Name": "xiaoyang hu",
"Address1": "1138 anthrop dr",
"Address2": null,
"State": "IN",
"City": "West Lafayette",
"Country": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
},
"ShipTo": {
"PostalCode": "60609",
"Name": "Jing zhang",
"Address1": "2023 w 35th st",
"Address2": null,
"State": "IL",
"City": "Chicago",
"Country": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
},
"OrderNum": "KV10644787171",
"Parcels": [{
"TrackingNumber": null,
"Weight": 3,
"Length": 22,
"Width": 22,
"Height": 22
}]
}
}
5.Obtain label information
https:///Api/Express/LabelsInfo.ashx
Query Parameter:
Post parameter |
Mandatory field |
Description |
Key |
Yes |
Retrieve a key from registered carriers |
Language |
No |
english=english;chinese=chinese.The default is chinese |
Data |
Yes |
Json String |
Response
Attributes |
Information |
Code |
Status code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error message |
LabelInfo |
Json string – label information |
Example
Query Parameter:
Data = [
"KV10645108889",
"KV10645090385",
"KV10645084825",
"KV10645076260"
]&Key = 88888888888888888888888888888888
Return Value :
{
"Code": "200",
"Message": null,
"Data": [{
"ShipmentId": "",
"LabelReady": false,
"LabelUrl": null,
"TrackingNumbers": [],
"OrderNum": "KV10645108889"
}, {
"ShipmentId": "9622001900008000264000794631631221",
"LabelReady": true,
"LabelUrl": "http://localhost/UploadFiles/EE/794631631221.pdf",
"TrackingNumbers": ["794631631221"],
"OrderNum": "KV10645090385"
}, {
"ShipmentId": "9622001900008000264000794631631221",
"LabelReady": true,
"LabelUrl": "http://localhost/UploadFiles/EE/794631631221.pdf",
"TrackingNumbers": ["794631631221"],
"OrderNum": "KV10645084825"
}, {
"ShipmentId": "9622001900008000264000794631631221",
"LabelReady": true,
"LabelUrl": "http://localhost/UploadFiles/EE/794631631221.pdf",
"TrackingNumbers": ["794631631221"],
"OrderNum": "KV10645076260"
}]
}
6.Refund shipping label
https:///Api/Express/LabelsCancel.ashx
Query Parameter:
Post Parameter |
Mandatory field |
Description |
Key |
Yes |
Retrieve a key from your registered carriers |
Language |
No |
english=english;chinese=chinese.The default is chinese |
Order Number |
Yes |
Order Number |
Response
Attributes |
Description |
Code |
Status Code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error response |
Example
Query Parameter:
OrderNum=KV10645076260&Key = 88888888888888888888888888888888
Return Value:
{
"Code": "200",
"Message": null
}
7.Address Type Determination
/Api/Express/AddressCheck.ashx
Noted: Different carriers’ address type determination may vary; therefore, the return address type could have error; but 98% of them are accurate. If the address type is not the accurate one, you could fix it by entering the address manually.
Query Parameter:
Post Parameter |
Mandatory field |
Description |
Key |
Yes |
Retrieve a key from your registered carriers |
Language |
No |
english=english;chinese=chinese.The default is chinese |
Data |
Yes |
ShipAddr Json – Address information |
ShipAddr
Parameter |
Mandatory field |
Type |
Description |
Postal Code |
Yes |
String |
Postal Code |
Name |
Yes |
String |
Name |
Address 1 |
Yes |
String |
Address 1 |
Address 2 |
Yes |
String |
Address 2 |
State |
Yes |
String |
State |
City |
Yes |
String |
City |
Country |
No |
String |
Support US area only |
Phone Number |
No |
String |
Phone number |
AddrType |
No |
Int |
1= Business; 2 = Residential AddrType does not require for this API. The response will automatically enter this field for the accurate address |
Response
Attributes |
Information |
Code |
Status code 200 – Succeeded (OK) 600 – Server Exception 603 – The parameter is incorrect |
Message |
Describe return an error message |
Data |
ShipAddr Json – Address information |
Example
Query Parameter:
Data = {
"PostalCode": "91710",
"Name": "Kevin Chen",
"Address1": "14592111 Central Av",
"Address2": null,
"State": "CA",
"City": "Chino",
"Country": null,
"CountryCode": null,
"PhoneNumber": "1234567890",
"AddrType":0
} &Key = 88888888888888888888888888888888
Correct return value:
{
"Code": "200",
"Message": null,
"Data": {
"PostalCode": "91710",
"Name": "Kevin Chen",
"Address1": "14592 Central Av",
"Address2": null,
"State": "CA",
"City": "Chino",
"Country": "US",
"CountryCode": "US",
"PhoneNumber": "1234567890",
"AddrType": 1
}
}
Inaccurate Response value :
{
"Code": "603",
"Message": "[address]Address not found",
"Data": {
"PostalCode": "91710",
"Name": "Kevin Chen",
"Address1": "14592111 Central Av",
"Address2": null,
"State": "CA",
"City": "Chino",
"Country": "US",
"CountryCode": "US",
"PhoneNumber": "1234567890",
"AddrType": 0
}
}