Getting Started
This guide will walk you through shipping your first package with EasyPost. In this example, we'll be shipping an EasyPost T-Shirt from EasyPost HQ to a customer.
Before You Start
- Sign up for an EasyPost account or log in to an existing account.
Manage API Keys - Enter your carrier specific credentials on the Carrier Account Dashboard.
Note: Unless you've entered your carrier information for other carriers, you'll just receive USPS rates.
Note: Negotiated rates are only available in Production mode.
- Grab one of our official client libraries. If you prefer, you can always interact directly with the REST API with cURL.
- Read the EasyPost Objects section of the docs. You'll need to know these few details to understand some of the code samples, and how to optimize your application.
To start, create the To and From Addresses for the package you'll be shipping. An Address object contains information you'd expect like name, street, city, state, country, etc. You need to create an Address object for both the To and the From Addresses.
Once you create an Address, EasyPost returns a unique ID for the Address. You can reuse this ID in the future for other packages you ship. This is helpful for when you are sending a lot of packages from a single location. For every type of object you create on EasyPost, we will pass you back a unique ID that you can use to reference in the future.
1curl -X POST https://api.easypost.com/v2/addresses \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "address": {
6 "street1": "417 MONTGOMERY ST",
7 "street2": "FLOOR 5",
8 "city": "SAN FRANCISCO",
9 "state": "CA",
10 "zip": "94104",
11 "country": "US",
12 "company": "EasyPost",
13 "phone": "415-123-4567"
14 }
15 }'Next, you'll need to tell us about the package you're shipping. You do this by creating a Parcel object. A Parcel contains information about the weight and dimensions (length, width, and height) of a package. Weights are in ounces and dimensions are in inches. In this example, because it's a t-shirt, it's a pretty small and light package. When you create a Parcel, EasyPost will give you a unique ID that you can use to reference it after the fact.
1curl -X POST https://api.easypost.com/v2/parcels \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "parcel": {
6 "length": "20.2",
7 "width": "10.9",
8 "height": "5",
9 "weight": "65.9"
10 }
11 }'We also have common carrier-specific packaging as predefined constants you can use. If you're using this for your packaging, you don't need to pass the dimensions, just the weight. You do this by passing the constant in the "predefined_package" parameter and we take care of the rest.
Now that you have created To and From Addresses and a Parcel, you can combine them all by creating a Shipment. When you create a Shipment, the API responds with shipping rates for the all carriers you've enabled. These are the rates for shipping the Parcel between the To and From Addresses you've specified.
To create a Shipment, pass us the IDs of the To and From Addresses and Parcel that you created in the previous steps. If creation is successful, we'll return a set of rates back to you. An individual rate contains information about the carrier, the service level (eg 1 day, 2 day, Ground, etc), cost, and the estimated number of days to delivery (when available). In our example, we'll keep it simple and just use USPS as the carrier.
Note: Unless you've entered your carrier information for other carriers, you'll just receive USPS rates.
1curl -X POST https://api.easypost.com/v2/shipments \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "shipment": {
6 "to_address": {
7 "name": "Dr. Steve Brule",
8 "street1": "179 N Harbor Dr",
9 "city": "Redondo Beach",
10 "state": "CA",
11 "zip": "90277",
12 "country": "US",
13 "phone": "8573875756",
14 "email": "dr_steve_brule@gmail.com"
15 },
16 "from_address": {
17 "name": "EasyPost",
18 "street1": "417 Montgomery Street",
19 "street2": "5th Floor",
20 "city": "San Francisco",
21 "state": "CA",
22 "zip": "94104",
23 "country": "US",
24 "phone": "4153334445",
25 "email": "support@easypost.com"
26 },
27 "parcel": {
28 "length": "20.2",
29 "width": "10.9",
30 "height": "5",
31 "weight": "65.9"
32 },
33 "customs_info": {
34 "id": "cstinfo_..."
35 }
36 }
37 }'You're almost done. Now you're ready to buy the label so you can print it out and put it on your package. To do this, you need to tell us which rate you want to use. If you are using a client library, just call the buy method on the shipment and pass the ID of the rate you want to use. If using the REST API, then POST the rate ID to the shipment resource. We have examples of both below. We also have convenience functions built into the client libraries so you buy the lowest rate every time if that's easier for you.
Once you buy the label, we'll respond with a URL to the image of your label that you can download and print. The URL can be found on a Shipment's postage_label.label_url property (this property's name may be different if you requeset a specific label type).
By default, labels are returned in .PNG format but you can also request labels in other formats.
In the response, you'll also notice that we pass back the tracking ID for your package. You can use this to store on your side or pass to your customers. EasyPost supports sending automatic tracking updates to your app with webhooks. We'll teach you a bit more about tracking in the next tutorial.
1curl -X POST https://api.easypost.com/v2/shipments/shp_.../buy \
2 -u "EASYPOST_API_KEY": \
3 -H 'Content-Type: application/json' \
4 -d '{
5 "rate": {
6 "id": "rate_..."
7 },
8 "insurance": "249.99"
9 }'Congratulations! You've just shipped your first package with EasyPost! Check out our Full Reference API Documentation.