Single Call Label Creation

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.

If this is your first time using Shippo, we recommend going through the First Shipment tutorial to get yourself acquainted with the basic concepts.

Setup and Configuration

  1. If you are using your own carrier accounts, make sure to go through the Carrier Account tutorial to add your carrier credentials and connect them with Shippo first.
  2. Retrieve the unique carrier object_id for the carrier that you’d like to use for the single-call request.
  3. Take a look at our list of available service level tokens to select the one that you’d like to use for the request.

Creating labels with one API call

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
C# 
                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": []
}

Get Started Today for Free!

Kick the tires on the best-in-class shipping platform with a free Shippo account.

Create a Free Account