Instalabel - 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 using our Instalabel feature.

Note

Instalabel 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 account 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:

Copy
Copied
{
    "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:

cURLRubyPythonPHPNodeJavaC#
Copy
Copied
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@shippo.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@shippo.com"
            },
            "parcels": [{
                "length": "5",
                "width": "5",
                "height": "5",
                "distance_unit": "in",
                "weight": "2",
                "mass_unit": "lb"
            }]
        },
        "carrier_account": "b741b99f95e841639b54272834bc478c",
        "servicelevel_token": "usps_priority"
        }'
Copy
Copied
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@shippo.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@shippo.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"
)
Copy
Copied
import shippo
from shippo.models import components

shippo_sdk = shippo.Shippo(api_key_header="<API_Token>")

address_from = components.AddressCreateRequest(
    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@shippo.com"
)

address_to = components.AddressCreateRequest(
    name="Mr Hippo",
    company="",
    street1="Broadway 1",
    street2="",
    city="New York",
    state="NY",
    zip="10007",
    country="US",
    phone="+1 555 341 9393",
    email="mrhippo@shippo.com",
    metadata="Hippos dont lie"
)

parcel = components.ParcelCreateRequest(
    length="5",
    width="5",
    height="5",
    distance_unit=components.DistanceUnitEnum.IN,
    weight="2",
    mass_unit=components.WeightUnitEnum.LB
)

shipment = components.ShipmentCreateRequest(
    address_from=address_from,
    address_to=address_to,
    parcels=[parcel]
)

transaction = shippo_sdk.transactions.create(
    components.InstantTransactionCreateRequest(
        shipment=shipment,
        carrier_account="b741b99f95e841639b54272834bc478c",
        servicelevel_token="usps_priority"
    )
)
Copy
Copied
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@shippo.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@shippo.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',
)
);
Copy
Copied
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@shippo.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@shippo.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
});
Copy
Copied
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()));
}
Copy
Copied
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.

Copy
Copied
{
    "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@shippo.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": []
}