Shipping Labels

The Shippo API allows you to programmatically create shipping labels from any carrier. Depending on your use case, there are two different ways to create labels:

Rating and label purchase: if you don’t know which carrier and service to use, or if you want to rate shop, you can first retrieve a list of available services including shipping rates and transit times. You can then select one of the available rates to buy the label.
Label with one API call: if you already know which carrier and service you want to use, you can create a label with a single API call directly.

Rating and Label Purchase

To retrieve all available rates and create a shipping label based on one of the rates, you need to follow two simple steps:

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.
Create the 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 from the sender to the recipient address. For both addresses make sure to send the name, street1, city, state (only for US & CA), zip and country values. All US and Australian addresses are automatically validated. For more information see our Address Validation Tutorial.

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

cURL

Ruby

Python

PHP

Node

Java

                curl https://api.goshippo.com/shipments/  \
    -H "Authorization: ShippoToken <API_TOKEN>" \
    -H "Content-Type: application/json"  \
    -d '{
       "address_from":{
          "name":"Mr. Hippo",
          "street1":"215 Clayton St.",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94117",
          "country":"US"
       },
       "address_to":{
          "name":"Mrs. Hippo",
          "street1":"965 Mission St.",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94105",
          "country":"US"
       },
       "parcels":[{
          "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 = {
    :name => 'Shawn Ippotle',
    :street1 => '965 Mission St.',
    :city => 'San Francisco',
    :state => 'CA',
    :zip => '94117',
    :country => 'US'
}

address_to = {
    :name => 'Mr Hippo',
    :street1 => 'Broadway 1',
    :city => 'New York',
    :state => 'NY',
    :zip => '10007',
    :country => 'US'
}

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

shipment = Shippo::Shipment.create(
    :address_from => address_from,
    :address_to => address_to,
    :parcels => parcel,
    :async => false
)
              

                import shippo

shippo.api_key = "<API_TOKEN>"

address_from = {
    "name": "Shawn Ippotle",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US"
}

address_to = {
    "name": "Mr Hippo",
    "street1": "Broadway 1",
    "city": "New York",
    "state": "NY",
    "zip": "10007",
    "country": "US"
}

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

shipment = shippo.Shipment.create(
    address_from = address_from,
    address_to = address_to,
    parcels = [parcel],
    async = False
)
              

                require_once('lib/Shippo.php');
Shippo::setApiKey("<API_TOKEN>");

$fromAddress = array(
    'name' => 'Shawn Ippotle',
    'street1' => '215 Clayton St.',
    'city' => 'San Francisco',
    'state' => 'CA',
    'zip' => '94117',
    'country' => 'US'
);

$toAddress = array(
    'name' => 'Mr Hippo"',
    'street1' => 'Broadway 1',
    'city' => 'New York',
    'state' => 'NY',
    'zip' => '10007',
    'country' => 'US',
    'phone' => '+1 555 341 9393'
);

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

$shipment = Shippo_Shipment::create( array(
    'address_from'=> $fromAddress,
    'address_to'=> $toAddress,
    'parcels'=> array($parcel),
    'async'=> false
    )
);
              

                var shippo = require('shippo')('<API_TOKEN>');

var addressFrom  = {
    "name": "Shawn Ippotle",
    "street1": "215 Clayton St.",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US"
};

var addressTo = {
    "name": "Mr Hippo",
    "street1": "Broadway 1",
    "city": "New York",
    "state": "NY",
    "zip": "10007",
    "country": "US"
};

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

shippo.shipment.create({
    "address_from": addressFrom,
    "address_to": addressTo,
    "parcels": [parcel],
    "async": false
}, function(err, shipment){
    // asynchronously called
});
              

                Shippo.setApiKey('<API_TOKEN>');

// To Address
HashMap<String, Object> addressToMap = new HashMap<String, Object>();
addressToMap.put("name", "Mr Hippo");
addressToMap.put("company", "Shippo");
addressToMap.put("street1", "215 Clayton St.");
addressToMap.put("city", "San Francisco");
addressToMap.put("state", "CA");
addressToMap.put("zip", "94117");
addressToMap.put("country", "US");

// From Address
HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
addressFromMap.put("name", "Ms Hippo");
addressFromMap.put("company", "San Diego Zoo");
addressFromMap.put("street1", "2920 Zoo Drive");
addressFromMap.put("city", "San Diego");
addressFromMap.put("state", "CA");
addressFromMap.put("zip", "92101");
addressFromMap.put("country", "US");

// Parcel
HashMap<String, Object> parcelMap = new HashMap<String, Object>();
parcelMap.put("length", "5");
parcelMap.put("width", "5");
parcelMap.put("height", "5");
parcelMap.put("distance_unit", "in");
parcelMap.put("weight", "2");
parcelMap.put("mass_unit", "lb");

// Shipment
HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
shipmentMap.put("address_to", addressToMap);
shipmentMap.put("address_from", addressFromMap);
shipmentMap.put("parcels", parcelMap);
shipmentMap.put("async", false);

Shipment shipment = Shipment.create(shipmentMap);
              

                APIResource resource = new APIResource ('<API_TOKEN>');

// to address
Hashtable toAddressTable = new Hashtable();
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");

// from address
Hashtable fromAddressTable = new Hashtable();
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");

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},
	{ "parcels", parcelTable},
	{ "async", false}});
              

The API will respond with the JSON serialized Shipment object:

{
    "status": "SUCCESS",
    "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": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "",
        "email": "",
        "is_residential": null
    },
    "address_to": {
        "object_id": "4c7185d353764d0985a6a7825aed8ffb",
        "validation_results": {},
        "is_complete": true,
        "name":"Mrs. Hippo",
        "street1":"965 Mission St.",
        "city":"San Francisco",
        "state":"CA",
        "zip":"94105",
        "country":"US",
        "phone":"",
        "email":"",
        "is_residential": false
    },
    "address_return": {
        "object_id": "0943ae4e373e4120a99c337e496dcce8",
        "validation_results": {},
        "is_complete": true,
        "company": "",
        "street_no": "",
        "name": "Mr. Hippo",
        "street1": "215 Clayton St.",
        "street2": "",
        "city": "San Francisco",
        "state": "CA",
        "zip": "94117",
        "country": "US",
        "phone": "",
        "email": "",
        "is_residential": null
    },
    "parcels": [{
        "object_id": "ec952343dd4843c39b42aca620471fd5",
        "object_created": "2013-12-01T06:24:21.121Z",
        "object_updated": "2013-12-01T06:24:21.121Z",
        "object_owner": "shippotle@goshippo.com",
        "template": null,
        "length":"5",
        "width":"5",
        "height":"5",
        "distance_unit":"in",
        "weight":"2",
        "mass_unit":"lb",
        "value_amount": null,
        "value_currency": null,
        "metadata": "",
        "line_items": [],
        "test": true
    }],
    "shipment_date": "2013-12-03T12:00:00.000Z",
    "extra": {
        "insurance": {
            "currency": "",
            "amount": ""
        }
    },
    "customs_declaration": "",
    "rates": [
        {
            "object_created": "2013-12-01T06:24:21.121Z",
            "object_id": "cf6fea899f1848b494d9568e8266e076",
            "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",
                "token":"usps_priority",
                "terms": "",
            },
            "days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": false,
            "zone": 1
        },
        ...
    ],
    "carrier_accounts": [],
    "metadata": "Customer ID 123456",
    "messages": []
}

The response contains a list of rates for the Shipment. If you haven’t added your own carrier accounts, you should only see USPS and DHL Express rates (for international shipments) at the moment.

Note that “SUCCESS” status and all available rates are returned because this is a synchronous API call. For asynchronous API calls please wait for “SUCCESS” statusto get all available rates for your shipment.
For more information please refer to https://goshippo.com/docs/async/

If you want to retrieve rates from specific carriers only, you can specify a list of carrier accounts in the carrier_account field of your Shipment request. When this field is set, Shippo will only retrieve rates from the corresponding carriers.

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

Ruby

Python

PHP

Node

Java

                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.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["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[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.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"][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["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[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 own business logic
Rate rate = shipment.ratesList[0];

HashMap<String, Object> transactionMap = new HashMap<String, Object>();
transactionMap.put("rate", rate.objectId);
transactionMap.put("async", false);

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

if (transaction.getStatus().equals("SUCCESS")) {
	System.out.println(String.format("Label url : %s",
	 transaction.getLabelUrl()));
	System.out.println(String.format("Tracking number : %s",
	 transaction.getTrackingNumber()));
} else {
	System.out.println(String.format("An Error has occured while generating your label. Messages : %s",
	 transaction.getMessages()));
}
              

                // Get the first rate in the rates results.
// Customize this based on your business logic.
Rate rate = shipment.RatesList[0];

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

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

if (((String) transaction.Status).Equals("SUCCESS", StringComparison.OrdinalIgnoreCase){
    Console.WriteLine("Label url: " + transaction.LabelURL);
    Console.WriteLine("Tracking number: " +
		 transaction.TrackingNumber);
} else{
    Console.WriteLine("Error generating label. Messages: " +
		transaction.Messages);
}
              

The API will respond with the JSON serialized Transaction object:

{
    "object_state":"VALID",
    "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":"UNKNOWN",
    "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC","eta":"2013-12-30T12:00:00.000Z",
    "label_url":"https://shippo-delivery-east.s3.amazonaws.com/773e695165f74f90b28f07450a7b4161.pdf?Signature=c%2B0eKYDgTOn6chbwpP8Ns9T0DTs%3D&Expires=1536113105&AWSAccessKeyId=AKIAJTHP3LLFMYAWILIA",
    "commercial_invoice_url":"",
    "metadata":"",
    "parcel":"603dbc611dc04170b47c376fae7b68f7"
}

Congrats! You’ve created your first shipment. You can find the shipping label in the label_url field of the Transaction object, and the tracking number in the tracking_number field, amongst other response attributes.

Label Purchase with one API Call

If you already know what service level you’ll be shipping with, you can create a shipping label in one API call through Shippo.

Single call label creation is currently only available for a select set of carriers through Shippo. To see if your carrier is supported, see our carrier capabilities page.

Creating a label with one API call is a POST request to the Transaction endpoint with the nested shipment information, the carrier account and the service token. A sample request looks like this:

{
    "shipment": {
        "address_from": { 
            // sender address fields
        },
        "address_to": { 
            // recipient address fields
        },
        "parcels": [
            {
                // parcel fields
            }
        ],
        ... // other relevant shipment fields
    },
    "carrier_account": "<carrier-account-object-id>",
    "servicelevel_token": "<servicelevel-token>"
}

Here’s a sample call that instantly creates and returns a shipping label:

cURL

Ruby

Python

PHP

Node

Java

                curl https://api.goshippo.com/transactions/  \
    -H "Authorization: ShippoToken <API_Token>" \
    -H "Content-Type: application/json"  \
    -d '{
        "shipment": {
            "address_from": {
                "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": {
                "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"
            },
            "parcels": [{
                "length": "5",
                "width": "5",
                "height": "5",
                "distance_unit": "in",
                "weight": "2",
                "mass_unit": "lb"
            }]
        },
        "carrier_account": "b741b99f95e841639b54272834bc478c",
        "servicelevel_token": "usps_priority"
        }'
              

                require 'shippo'

Shippo::API.token = '<API_Token>'

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

address_to = {
    :name => 'Mr Hippo"',
    :company => '',
    :street1 => 'Broadway 1',
    :street2 => '',
    :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 => :cm,
    :weight => 2,
    :mass_unit => :lb
}

shipment = {
    :address_from => address_from,
    :address_to => address_to,
    :parcels => parcel
)

transaction = Shippo::Transaction.create(
    :shipment => shipment,
    :carrier_account => "b741b99f95e841639b54272834bc478c",
    :servicelevel_token => "usps_priority"
)
              

                import shippo

shippo.api_key = "<API_Token>"

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

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

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

shipment = {
    "address_from": address_from,
    "address_to": address_to,
    "parcels": [parcel]
}

transaction = shippo.Transaction.create(
    shipment = shipment,
    carrier_account = "b741b99f95e841639b54272834bc478c",
    servicelevel_token = "usps_priority"
)
              

                require_once('lib/Shippo.php');
Shippo::setApiKey("<API_Token>");

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

$toAddress = array(
    'name' => 'Mr Hippo"',
    'company' => '',
    'street1' => 'Broadway 1',
    'street2' => '',
    '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 = array(
    'address_from'=> $fromAddress,
    'address_to'=> $toAddress,
    'parcels'=> array($parcel),
);

$transaction = Shippo_Transaction::create( array(
    'shipment' => $shipment,
    'carrier_account' => 'b741b99f95e841639b54272834bc478c',
    'servicelevel_token' => 'usps_priority',
)
);
              

                var shippo = require('shippo')('<API_Token>');

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

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

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

var shipment = {
    "address_from": addressFrom,
    "address_to": addressTo,
    "parcels": [parcel],
};

shippo.transaction.create({
    "shipment": shipment,
    "carrier_account": "078870331023437cb917f5187429b093",
    "servicelevel_token": "usps_priority"
}, function(err, transaction) {
    // asynchronously called
});
              

                Shippo.setApiKey('<API_Token>');

// To Address
HashMap<String, Object> addressToMap = new HashMap<String, Object>();
addressToMap.put("name", "Mr Hippo");
addressToMap.put("company", "Shippo");
addressToMap.put("street1", "215 Clayton St.");
addressToMap.put("city", "San Francisco");
addressToMap.put("state", "CA");
addressToMap.put("zip", "94117");
addressToMap.put("country", "US");
addressToMap.put("phone", "+1 555 341 9393");
addressToMap.put("email", "mrhippo@goshipppo.com");

// From Address
HashMap<String, Object> addressFromMap = new HashMap<String, Object>();
addressFromMap.put("name", "Ms Hippo");
addressFromMap.put("company", "San Diego Zoo");
addressFromMap.put("street1", "2920 Zoo Drive");
addressFromMap.put("city", "San Diego");
addressFromMap.put("state", "CA");
addressFromMap.put("zip", "92101");
addressFromMap.put("country", "US");
addressFromMap.put("email", "mshippo@goshipppo.com");
addressFromMap.put("phone", "+1 619 231 1515");
addressFromMap.put("metadata", "Customer ID 123456");

// Parcel
HashMap<String, Object> parcelMap = new HashMap<String, Object>();
parcelMap.put("length", "5");
parcelMap.put("width", "5");
parcelMap.put("height", "5");
parcelMap.put("distance_unit", "in");
parcelMap.put("weight", "2");
parcelMap.put("mass_unit", "lb");

// Shipment
HashMap<String, Object> shipmentMap = new HashMap<String, Object>();
shipmentMap.put("address_to", addressToMap);
shipmentMap.put("address_from", addressFromMap);
shipmentMap.put("parcels", parcelMap);
shipmentMap.put("async", false);

// Transaction
HashMap<String, Object> transactionMap = new HashMap<String, Object>();
transactionMap.put("shipment", shipmentMap);
transactionMap.put("servicelevel_token", "usps_priority");
transactionMap.put("carrier_account", "b741b99f95e841639b54272834bc478c");

Transaction transaction = Transaction.create(transactionMap);

if (transaction.getStatus().equals("SUCCESS")) {
	System.out.println(String.format("Label url : %s",
	 transaction.getLabelUrl()));
	System.out.println(String.format("Tracking number : %s",
	 transaction.getTrackingNumber()));
} else {
	System.out.println(String.format("An Error has occured while generating your label. Messages : %s",
	 transaction.getMessages()));
}
              

                APIResource resource = new APIResource ("<API_Token>");

// to address
Hashtable toAddressTable = new Hashtable ();
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", "support@goshipppo.com");

// from address
Hashtable fromAddressTable = new Hashtable ();
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", "hippo@goshipppo.com");
fromAddressTable.Add ("phone", "+1 619 231 1515");
fromAddressTable.Add ("metadata", "Customer ID 123456");

// parcel
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");

// shipment
Hashtable shipmentTable = new Hashtable ();
shipmentTable.Add ("address_to", toAddressTable);
shipmentTable.Add ("address_from", fromAddressTable);
shipmentTable.Add ("parcels", parcelTable);

Console.WriteLine ("Getting shipping label..");
Hashtable transactionParameters = new Hashtable ();
transactionParameters.Add ("shipment", shipmentTable);
transactionParameters.Add ("servicelevel_token", "usps_priority");
transactionParameters.Add ("carrier_account", "b741b99f95e841639b54272834bc478c");
Transaction transaction = resource.CreateTransaction (transactionParameters);

if (((String) transaction.Status).Equals ("SUCCESS", StringComparison.OrdinalIgnoreCase)) {
    Console.WriteLine ("Label url : " + transaction.LabelURL);
    Console.WriteLine ("Tracking number : " + transaction.TrackingNumber);
} else {
    Console.WriteLine ("An Error has occured while generating your label. Messages : " + transaction.Messages);
}
              

The API will respond with the JSON serialized Shipment object. Shippo automatically creates the corresponding rate object, which you can use to retrieve the amount of the label.

{
    "object_state": "VALID",
    "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": {
        "object_id": "cf6fea899f1848b494d9568e8266e076",
        "amount": "5.50",
        "currency": "USD",
        "amount_local": "5.50",
        "currency_local": "USD",
        "provider": "USPS",
        "servicelevel_name": "Priority Mail",
        "servicelevel_token": "usps_priority",
        "carrier_account": "078870331023437cb917f5187429b093",
    },
    "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_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "eta": "2013-12-30T12:00:00.000Z",
    "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 a label with a single API call. You can find the shipping label in the label_url field of the Transaction object, and the tracking number in the tracking_number field, amongst other response attributes.

Next Steps

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

We recommend checking out the following common API endpoints and shipping features:

Add carrier accounts – to use carriers other than our default ones, you will need to add your own account credential and connect your own carrier account.
International shipping label purchases: send packages cross-border and create customs declarations, commercial invoices and submit your documentation electronically to the customs office.
Refunds: everyone makes mistakes and sometimes your customers might have made an error when purchasing a label. Allow them to void unused labels and get their money back.
Address validation: prevent failed deliveries and shipping errors by automatically validating any address worldwide with Shippo’s Address Validation service.
Tracking: keep your customers, and their buyers, informed about the status of their shipments. Engage buyers by proactively sending shipment and delivery notification, and stay on top of shipment delays or exceptions.

We also recommend that you make use of webhooks to update your customers about tracking updates in realtime and reduce your development time.

Shipping Labels

Rating and Label Purchase

1. Create the Shipment Object

2. Create the Transaction Object

Label Purchase with one API Call

Next Steps

Get Started Today for Free