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

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.
Retrieve the unique carrier account object_id for the carrier that you’d like to use for the single-call request.
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:

cURLPythonPHPtypescriptJavaC#

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

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

const shippo = new Shippo({apiKeyHeader: '<API_Token>'});

const addressFrom: 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",
};

const addressTo: 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"
};

const parcel: ParcelCreateRequest = {
    length: "5",
    width: "5",
    height: "5",
    distanceUnit: DistanceUnitEnum.In,
    weight: "2",
    massUnit: WeightUnitEnum.Lb
};

const shipment: ShipmentCreateRequest = {
    addressFrom: addressFrom,
    addressTo: addressTo,
    parcels: [parcel],
};

const transaction = await shippo.transactions.create({
    shipment: shipment,
    carrierAccount: "078870331023437cb917f5187429b093",
    servicelevelToken: ServiceLevelUSPSEnum.UspsPriority.valueOf()
});

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

using Shippo;
using Shippo.Models.Components;
ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_Token>");
AddressFrom addressFrom = AddressFrom.CreateAddressCreateRequest(
    new 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",
    }
);
AddressTo addressTo = AddressTo.CreateAddressCreateRequest(
    new 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",
    }
);
Shippo.Models.Components.Parcels parcel = Shippo.Models.Components.Parcels.CreateParcelCreateRequest(
    new ParcelCreateRequest()
    {
        Length = "5",
        Width = "5",
        Height = "5",
        DistanceUnit = DistanceUnitEnum.In,
        Weight = "2",
        MassUnit = WeightUnitEnum.Lb,
    }
);
ShipmentCreateRequest shipmentCreateRequest = new ShipmentCreateRequest()
{
    AddressFrom = addressFrom,
    AddressTo = addressTo,
    Parcels = new List<Shippo.Models.Components.Parcels>() { parcel },
};
Transaction transaction = await sdk.Transactions.CreateAsync(
    CreateTransactionRequestBody.CreateInstantTransactionCreateRequest(
        new InstantTransactionCreateRequest()
        {
            Shipment = shipmentCreateRequest,
            CarrierAccount = "b741b99f95e841639b54272834bc478c",
            ServicelevelToken = ServiceLevelUSPSEnum.UspsPriority.Value(),
        }
    )
);

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