Getting Rates
This guide walks you through getting retreiving rates from JUSDA API.
Authentication
JUSDA uses API keys for authentication. At this time API keys are assigned by JUSDA's Technology Team. To obtain a key, contact your JUSDA Sales representative.
Once you have an API key, to authenticate, it will be necessary to pass the key in the HTTP header of each call you make. For the header key pass x-api-key. Pass your key as the value. For example:
x-api-key=34A81032-979E-4EFC-9A6F-87E2973F3E20
If there is any problem authenticating your key, the API will respond with an HTTP 401 code.
Testing
JUSDA may provide you an API key that is set to our test environment. Rates retrieved by the test key may not be rates you'll get in production. If instead you have a production API key, it's possible to use the test environment on any API call by including an environment attribute in the endpoint's query string. For example:
https://services.jusdausa.com/api/v1/Rates?environment=Test
API Endpoint
The URL for JUSDA Rate APIs is:
https://services.jusdausa.com/api/v1/Rates
Use an HTTP POST with the approprate payload as described below.
Get Rates Request Payload
Craft a JSON payload as shown below. Key properties of the payload:
- rateRequestIdentifier: (optional) Your internal reference number. Will be stored in JUSDA's system and returned in the response payload
- mode: (optional) Parcel or LTL. If not provided both Parcel and LTL rates will be returned.
- shipperCity: (required)
- shipperStateProvince: (required)
- shipperPostalCode: (required) ZIP code or postal code
- shipperCountry: (required) 2 digit ISO country code like US or CN
- shipToCity: (required)
- shipToStateProvince: (required)
- shipToPostalCode: (required) ZIP code or postal code
- shipToCountry: (required) 2 digit ISO country code like US or CN
- residential: (optional) Specifies if Ship To location is a residence. Use true or false
- carrierName: (optional) Specifies the carrier name, such as UPS, FEDEX, or DHL. If not provided, rates for all carriers and all service levels will be returned. Specify the carrier could reduce the response time.
- serviceLevel: (optional) Specifies the service level. If not provided, rates for all service levels will be returned. Specify the service level could reduce the response time.
- declaredValue: (optional) Declared value of the items being shipped
- declaredValueCurrencyCode: (optional) 3 digit currency code like USD, EUR, or JPY
- items: (required) An array containing one item for each package being shipped
- weight: (required) Gross weight of package
- weightUnit: (required) LB or KG
- length: (required) Length of package
- width: (required) Width of package
- height: (required) Height of package
- dimUnit: (required) IN or CM
- freightClass: (optional) US LTL Freight Class. For LTL either provide freight class or dimensions. Does not apply to parcel
- hazardous: (optional) Use true or false to specify if package contains hazardous materials
Sample Request
{
"rateRequestIdentifier": "MyReference",
"mode" : "Parcel",
"shipperCity" : "Diamond Bar",
"shipperStateProvince" : "CA",
"shipperPostalCode" : "91765",
"shipperCountry" : "US",
"shipToCity" : "Elk Grove Village",
"shipToStateProvince" : "IL",
"shipToPostalCode" : "60007",
"shipToCountry" : "US",
"residential" : false,
"carrierName": "UPS",
"items": [
{
"weight" : 5,
"weightUnit" : "LB",
"length" : 5,
"width" : 5,
"height" : 5,
"dimUnit" : "IN",
"hazardous": false
}
]
}
Get Rates Response Payload
The response payload will contain an array of any matching carriers and service levels. Key properties of the payload:
- rateResponseId: JUSDA assigned identifier for this Rate Response. Can be used as a support reference
- rateRequestId: JUSDA assigned identifier for the Rate Request. Can be used as a support reference
- rateRequestIdentifier: Your reference which was provided in the request payload
- responseDate: Date and time rate response was processed in Coordinated Universal Time (UTC)
- quoteNo: Provided by some LTL carriers
- carrierName: Carrier rate applies to
- carrierLogoUrl: Carrier's logo URL to support displaying logo in API consumer's results
- service: Carrier's service level for this rate
- totalCharge: Total charges including freight and accessorials. Taxes and duties not included.
- transitDays: Carrier's estimated transit time in days
- estimatedDeliveryDate: ETD based on provided shipDate or date of rate request if not provided
- currencyCode: Currency Code of totalCharge
- messages: An array of any warning messages provided by the carrier for this rate request
Sample Response
[
{
"rateResponseId": "4559af98-aa65-4fa8-e256-08d8b4311f0a",
"rateRequestId": "48885b43-f12f-402b-5e9a-08d8b4311a71",
"rateRequestIdentifier": "MyReference",
"responseDate": "2021-01-08T23:57:13.8922329Z",
"quoteNo": null,
"mode": "Parcel",
"carrierName": "UPS",
"carrierLogoUrl": "https://jusdamedia.blob.core.windows.net/webassets/ups.svg",
"service": "UPS Next Day Air Saver",
"totalCharge": 15.25,
"transitDays": 1,
"estDeliveryDate": "2021-01-11T17:57:06.2572877Z",
"currencyCode": "USD",
"messages": [
{
"code": "820",
"description": "The destination state/province code has been changed. ",
"severity": "NOTE"
}
]
},
{
"rateResponseId": "0e8ae7cf-38eb-44d2-e257-08d8b4311f0a",
"rateRequestId": "48885b43-f12f-402b-5e9a-08d8b4311a71",
"rateRequestIdentifier": null,
"responseDate": "2021-01-08T23:57:13.9763896Z",
"quoteNo": null,
"mode": "Parcel",
"carrierName": "UPS",
"carrierLogoUrl": "https://jusdamedia.blob.core.windows.net/webassets/ups.svg",
"service": "UPS Next Day Air",
"totalCharge": 17.45,
"transitDays": 1,
"estDeliveryDate": "2021-01-11T17:57:06.2572877Z",
"currencyCode": "USD",
"messages": null
}
]
API Documentation
For more details about the Rates API endpoint, see JUSDA's API Documentation.