Calculate Shipping Costs
ShipEngine is a REST API that allows you to manage almost every facet possible for shipping. This tutorial will show you how to create a rate.
Before you begin:
- Sign up for a ShipEngine account, if you haven't already.
- You'll need an API key (a sandbox API key will work for this tutorial).
- You'll need a tool to make an API call, like curl or Postman.
This article helps you to make a POST call to get shipping rates for your multiple carrier and service options.
Display these at checkout to let your customers choose the fastest, cheapest, or most-trusted route when you ship your products.
Similar to the Quickstart: Create a Label guide, we need to know some basic information to get a rate.
Below are four examples of different ways to POST calls in JSON. Each example includes the response you should see returned, and how to understand and use their results. These examples include:
Examples
POST /v1/rates/
Given some shipment details and rate options, this endpoint returns a list of rate quotes. You can then Use a Rate to Print a Label.
Choose to validate the address as part of the rate request to help ensure that you get back the most-accurate rates possible. There are three address validation options:
Validation Option | Description |
---|---|
no_validation | This default option in ShipEngine does not validate addresses nor does it confirm the accuracy of an address. |
validate_only | Validates address accuracy but returns an error if the validation fails. |
validate_and_clean | Validates address accuracy and updates the address with recommended adjustments. |
Example Requests
This JSON example passes shipment
details and no_validation
for the validate_address
property in the POST call.
If you've already created a shipment, then you can pass the shipment_id
instead of the full shipment details.
This examples passes the shipment_id
of a previously created shipment.
Example Response
The response can be quite daunting depending on how many carriers you requested rates from. We excluded all but one in our response below. As you can see, there's a lot of data that comes back in a response.
Each rate includes the itemized prices for:
Property | Description |
---|---|
shipment_amount | Cost of shipment only. |
insurance_amount | Cost to insure shipment. |
confirmation_amount | Cost to confirm shipment delivery. |
other_amount | Fees and surcharges from the carrier. |
The total rate is the sum of all these amounts.
You may want some additional detail about the rates coming back. When it's avaialable, we provide this additional information in the rate_details
object. This is structured:
Property | Description |
---|---|
rate_detail_type | Normalized type for the additional rate information. These types are enumerated as: uncategorized , shipping , insurance , confirm , discount , fuel_charge , additional_fees , tariff , tax , delivery , handling , special_goods , pickup , location_fee , oversize , returns , notifications , tip |
carrier_description | Plain text description of the rate detail as provided by the carrier. |
carrier_billing_code | Code for the billing type provided by the carrier. |
carrier_memo | Additional text regarding this charge. Usually null. |
amount | The currency and amount of the detailed charge |
The Rate Details object should match the total of the shipment_amount
, insurance_amount
, confirmation_amount
and other_amount
when it is provided.
Example: Find Rates with Package Types
This example shows how to get rates that are filtered by a specific set of package types. If no package type is specified the the default package type for that carrier is used, not all package types.
Example (Find Rates with service codes)
This example shows how to get rates that are filtered by a specific set of service codes. If no service code is specified then all service codes are returned.
Example (Find Rates with service codes and package types)
This example shows how to get rates that are filtered by a combination of service codes and package types.