Create Your First Shipment

Create your shipment, get shipping rates, and generate your first shipping label.

The Setup

Before you begin, you’ll need to:

  1. Grab your Test or Live Token from the API page of your Shippo dashboard. Learn more about Authentication.
  2. Download and install one of our client libraries, available in most major programming languages. If you prefer, you can also use cURL to interact directly with our REST API.
  3. You won't need to sign up for a carrier account to get started, simply put in a U.S. outbound shipment to start working.
    By default, you have access to Shippo's discounted accounts for any U.S. outbound shipments with carriers such as USPS and DHL Express. After this tutorial, you can visit the visit the carrier account tutorial if you'd like to add other carriers that allow other outbound destinations.

High-Level Structure

To create a shipping label, you'll need to follow two simple steps:

  1. Create the Shipment Object, consisting of a sender address, a recipient address, and a parcel (blue objects below). The Shipment response will contain the list of available Rates.
  2. Create Transaction Object, i.e. the actual label, for any of the Rates from the Shipment response (green object below).

1. Create the Shipment Object

The purpose of the Shipment object is to retrieve rates. It represents a request to ship a given package between the sender and recipient addresses. You could create the Address and Parcel objects in separate API calls but we suggest creating the Address and Parcel objects inline as it will save you time and extra network calls.

For both Address objects make sure to send the following values: name, street1, city, state (only for US & CA), zip, country and email. All US and Australian addresses are automatically validated. For more information see our Address Validation Tutorial.

The Shipment object has many extra properties (such as signature confirmation, 3rd party billing, COD, etc.) that you can find in our API reference.

curl https://api.goshippo.com/shipments/  \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -d '{
       "object_purpose":"PURCHASE",
       "address_from":{
          "object_purpose":"PURCHASE",
          "name":"Mr. Hippo",
          "street1":"215 Clayton St.",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94117",
          "country":"US",
          "phone":"+1 555 341 9393",
          "email":"support@goshippo.com"
       },
       "address_to":{
          "object_purpose":"PURCHASE",
          "name":"Mrs. Hippo",
          "street1":"965 Mission St.",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94105",
          "country":"US",
          "phone":"+1 555 341 9393",
          "email":"support@goshippo.com"
       },
       "parcel":{
          "length":"5",
          "width":"5",
          "height":"5",
          "distance_unit":"in",
          "weight":"2",
          "mass_unit":"lb"
       },
       "async": false
    }'
require 'shippo'

Shippo::api_token = '<API_TOKEN>'

address_from = {
    :object_purpose => 'PURCHASE',
    :name => 'Shawn Ippotle',
    :street1 => '215 Clayton St.',
    :city => 'San Francisco',
    :state => 'CA',
    :zip => '94117',
    :country => 'US',
    :phone => '+1 555 341 9393',
    :email => 'shippotle@goshippo.com' 
}

address_to = {
    :object_purpose => 'PURCHASE',
    :name => 'Mr Hippo',
    :street1 => 'Broadway 1',
    :city => 'New York',
    :state => 'NY',
    :zip => '10007',
    :country => 'US',
    :phone => '+1 555 341 9393',
    :email => 'mrhippo@goshippo.com'
}

parcel = {
    :length => 5,
    :width => 1,
    :height => 5.555,
    :distance_unit => :in,
    :weight => 2,
    :mass_unit => :lb
}

shipment = Shippo::Shipment.create(
    :object_purpose => 'PURCHASE',
    :address_from => address_from,
    :address_to => address_to,
    :parcel => parcel,
    :async => false
)
import shippo

shippo.api_key = "<API_TOKEN>"

address_from = {
    "object_purpose": "PURCHASE",
    "name": "Shawn Ippotle",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@goshippo.com"
}

address_to = {
    "object_purpose": "PURCHASE",
    "name": "Mr Hippo",
    "street1": "Broadway 1",
    "city": "New York",
    "state": "NY",
    "zip": "10007",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "mrhippo@goshippo.com"
}

parcel = {
    "length": "5",
    "width": "5",
    "height": "5",
    "distance_unit": "in",
    "weight": "2",
    "mass_unit": "lb"
}

shipment = shippo.Shipment.create(
    object_purpose = 'PURCHASE',
    address_from = address_from,
    address_to = address_to,
    parcel = parcel,
    async = False
)
require_once('lib/Shippo.php');
Shippo::setApiKey("<API_TOKEN>");

$fromAddress = array(
    'object_purpose' => 'PURCHASE',
    'name' => 'Shawn Ippotle',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'shippotle@goshippo.com'
);

$toAddress = array(
    'object_purpose' => 'PURCHASE',
    'name' => 'Mr Hippo"',
    'street1' => 'Broadway 1',
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10007',
    'country' => 'US',
    'phone' => '+1 555 341 9393',
    'email' => 'mrhippo@goshippo.com'
);

$parcel = array(
    'length'=> '5',
    'width'=> '5',
    'height'=> '5',
    'distance_unit'=> 'in',
    'weight'=> '2',
    'mass_unit'=> 'lb',
);

$shipment = Shippo_Shipment::create( array(
    'object_purpose'=> 'PURCHASE',
    'address_from'=> $fromAddress,
    'address_to'=> $toAddress,
    'parcel'=> $parcel,
    'async'=> false
    )
);
var shippo = require('shippo')('<API_TOKEN>');

var addressFrom  = {
    "object_purpose": "PURCHASE",
    "name": "Shawn Ippotle",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "shippotle@goshippo.com"
};

var addressTo = {
    "object_purpose": "PURCHASE",
    "name": "Mr Hippo",
    "street1": "Broadway 1",
    "city": "New York",
    "state": "NY",
    "zip": "10007",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "mrhippo@goshippo.com"
};

var parcel = {
    "length": "5",
    "width": "5",
    "height": "5",
    "distance_unit": "in",
    "weight": "2",
    "mass_unit": "lb"
};

shippo.shipment.create({
    "object_purpose": "PURCHASE",
    "address_from": addressFrom,
    "address_to": addressTo,
    "parcel": parcel,
    "async": false
}, function(err, shipment){
    // asynchronously called
});
APIResource resource = new APIResource ('<API_TOKEN>');

// to address
Hashtable toAddressTable = new Hashtable();
toAddressTable.Add("object_purpose", "PURCHASE");
toAddressTable.Add("name", "Mr Hippo");
toAddressTable.Add("company", "Shippo");
toAddressTable.Add("street1", "215 Clayton St.");
toAddressTable.Add("city", "San Francisco");
toAddressTable.Add("state", "CA");
toAddressTable.Add("zip", "94117");
toAddressTable.Add("country", "US");
toAddressTable.Add("phone", "+1 555 341 9393");
toAddressTable.Add("email", "mrhippo@goshipppo.com");

// from address
Hashtable fromAddressTable = new Hashtable();
fromAddressTable.Add("object_purpose", "PURCHASE");
fromAddressTable.Add("name", "Ms Hippo");
fromAddressTable.Add("company", "San Diego Zoo");
fromAddressTable.Add("street1", "2920 Zoo Drive");
fromAddressTable.Add("city", "San Diego");
fromAddressTable.Add("state", "CA");
fromAddressTable.Add("zip", "92101");
fromAddressTable.Add("country", "US");
fromAddressTable.Add("email", "mshippo@goshipppo.com");
fromAddressTable.Add("phone", "+1 619 231 1515");
fromAddressTable.Add("metadata", "Customer ID 123456");

Hashtable parcelTable = new Hashtable ();
parcelTable.Add ("length", "5");
parcelTable.Add ("width", "5");
parcelTable.Add ("height", "5");
parcelTable.Add ("distance_unit", "in");
parcelTable.Add ("weight", "2");
parcelTable.Add ("mass_unit", "lb");

resource.CreateShipment(new Hashtable(){
	{ "address_to", toAddressTable},
	{ "address_from", fromAddressTable},
	{ "parcel", parcelTable},
	{ "object_purpose", "PURCHASE"},
	{ "async", false}});

The API will respond with the JSON serialized Shipment object:

{
    "object_state": "VALID",
    "object_status": "SUCCESS",
    "object_purpose": "PURCHASE",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "5e40ead7cffe4cc1ad45108696162e42",
    "object_owner": "shippotle@goshippo.com",
    "address_from": "4f406a13253945a8bc8deb0f8266b245",
    "address_to": "4c7185d353764d0985a6a7825aed8ffb",
    "address_return": "4f406a13253945a8bc8deb0f8266b245",
    "parcel": "ec952343dd4843c39b42aca620471fd5",
    "submission_date": "2013-12-03T12:00:00.000Z",
    "insurance_amount": "",
    "insurance_currency": "",
    "extra": {},
    "customs_declaration": "",
    "reference_1": "",
    "reference_2": "",
    "rates_url": "https://api.goshippo.com/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/",
    "rates_list": [
        {
            "object_state": "VALID",
            "object_purpose": "PURCHASE",
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_updated": "2013-12-01T06:24:21.121Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "5e40ead7cffe4cc1ad45108696162e42",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel_name": "Priority Mail",
            "servicelevel_token":"usps_priority",
            "servicelevel_terms": "",
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "trackable": true,
            "insurance": false,
            "insurance_amount_local": "0.00",
            "insurance_currency_local": null,
            "insurance_amount": "0.00",
            "insurance_currency": null,
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": []
}

In the response, that you'll see a list of rates for the Shipment. If you haven't added any of your own carrier accounts yet, you should only see USPS and DHL Express rates (for international shipments) at the moment.

2. Create the Transaction Object

The creation of a shipping label is handled by the Transaction endpoint. The Transaction object represents a shipping label purchase and is based on the shipping rate you want to purchase from step 1.

You can send an optional label_file_type in the transaction call. If you don't specify this value, the API will use to the default file format, which you can set on the settings page.

curl https://api.goshippo.com/transactions \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -d rate="cf6fea899f1848b494d9568e8266e076"
    -d label_file_type="PDF"
    -d async=false
# Get the first rate in the rates results.
# Customize this based on your business logic.
rate = shipment.rates_list.first

# Purchase the desired rate.
transaction = Shippo::Transaction.create( 
  :rate => rate["object_id"], 
  :label_file_type => "PDF", 
  :async => false )

# label_url and tracking_number
if transaction["object_status"] == "SUCCESS"
  puts "Label sucessfully generated:"
  puts "label_url: #{transaction.label_url}" 
  puts "tracking_number: #{transaction.tracking_number}" 
else
  puts "Error generating label:"
  puts transaction.messages
end
# Get the first rate in the rates results.
# Customize this based on your business logic.
rate = shipment.rates_list[0]

# Purchase the desired rate. 
transaction = shippo.Transaction.create( 
    rate=rate.object_id, 
    label_file_type="PDF", 
    async=False )

# Retrieve label url and tracking number or error message
if transaction.object_status == "SUCCESS":
    print transaction.label_url
    print transaction.tracking_number
else:
    print transaction.messages
// Get the first rate in the rates results.
// Customize this based on your business logic.
$rate = $shipment["rates_list"][0];

// Purchase the desired rate.
$transaction = Shippo_Transaction::create( array( 
    'rate' => $rate["object_id"], 
    'label_file_type' => "PDF", 
    'async' => false ) );

// Retrieve label url and tracking number or error message
if ($transaction["object_status"] == "SUCCESS"){
    echo( $transaction["label_url"] );
    echo("\n");
    echo( $transaction["tracking_number"] );
}else {
    echo( $transaction["messages"] );
}
// Get the first rate in the rates results.
// Customize this based on your business logic.
var rate = shipment.rates_list[0];

// Purchase the desired rate.
shippo.transaction.create({
    "rate": rate.object_id,
    "label_file_type": "PDF",
    "async": false
}, function(err, transaction) {
   // asynchronous callback
});
// Get the first rate in the rates results.
// Customize this based on your business logic.
Rate rate = shipment.RatesList[0];

HashMap transactionParameters = new HashMap();
transactionParameters.Add("rate", rate.ObjectId);
transactionParameters.Add("async", false);

// Purchase the desired rate.
Transaction transaction = resource.CreateTransaction(transactionParameters);

if (transaction.getObjectStatus().equals("SUCCESS")){
    Console.WriteLine("Label url: " + transaction.getLabelUrl());
    Console.WriteLine("Tracking number: " + transaction.getTrackingNumber());
} else{
    Console.WriteLine("Error generating label. Messages: " + transaction.getMessages());
}

The API will respond with the JSON serialized Transaction object:

{
    "object_state": "VALID",
    "object_status": "SUCCESS",
    "object_created": "2013-12-27T19:14:48.273Z",
    "object_updated": "2013-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "shippotle@goshippo.com",
    "was_test": false,
    "rate": "cf6fea899f1848b494d9568e8266e076",
    "tracking_number": "ZW70QJC",
    "tracking_status": {
        "object_created": "2013-12-27T23:17:41.411Z",
        "object_id": "a21b3d6831c14ceaba6730179ce6e784",
        "status": "UNKNOWN",
        "status_details": "",
        "status_date": "2013-12-28T12:04:04.214Z"
    },
    "tracking_history": [],
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "commercial_invoice_url": "",
    "metadata": "",
    "messages": []
}

Congrats! You've created your first shipment. You can find the shipping label URL under label_url, and shipment tracking information amongst other response attributes.

Recommended Configurations

For detailed tutorials on different shipping configurations and advanced functionalities, see our navigation sidebar. Or you can surf through our API references to explore all our supported services.

We recommend reviewing the following information: