API quickstart

Follow this guide to make your first Shippo API call. In this guide, you will learn how to create an address, set up your token, and test a request using the Shippo API.

Building shipping for multiple merchants?A single API account works great for one business. If you’re building a platform where other businesses will ship through your integration, there’s a different setup that handles per-merchant billing, carrier accounts, and reporting cleanly.See which integration path is right for you →

Generate your API Token

Follow the Authentication guide to generate your API Token.

NoteWhen learning about and testing the Shippo API, we recommend using the test token. Using your test token means all the calls you make to the Shippo API are free.

Install the client library for your language

# No library needed for cURL

pip install shippo

// Follow the steps in 
// https://github.com/goshippo/shippo-php-client

npm install shippo

// Java
npm install shippo

dotnet add package Shippo

// For a full list of supported libraries, review our client libraries page
// https://docs.goshippo.com/guides/client-libraries

See our client libraries page for more details.

Make your first API call

To make sure everything is working, make a simple call to create a new address in your Shippo account. You must replace <API_TOKEN> with the token you copied from Step 1.

curl https://api.goshippo.com/addresses/ \
   -H "Authorization: ShippoToken <API_TOKEN>" \
   -d name="Shawn Ippotle" \
   -d company="Shippo" \
   -d street1="215 Clayton St." \
   -d street2="" \
   -d city="San Francisco" \
   -d state="CA" \
   -d zip=94117 \
   -d country="US" \
   -d phone="+1 555 341 9393" \
   -d email="shippotle@shippo.com"\
   -d is_residential=True\
   -d metadata="Customer ID 123456"

import shippo
from shippo.models import components

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

shippo_sdk.addresses.create(
    components.AddressCreateRequest(
        name="Shawn Ippotle",
        company="Shippo",
        street1="215 Clayton St.",
        city="San Francisco",
        state="CA",
        zip="94117",
        country="US", # iso2 country code
        phone="+1 555 341 9393",
        email="shippotle@shippo.com"
    )
)

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

// Create address object
$fromAddress = Shippo_Address::create( 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" 
));

// Create address object
const shippo = new Shippo({apiKeyHeader: '<API_TOKEN>'});
const addressFrom = await shippo.addresses.create({
    name: "Shawn Ippotle",
    company: "Shippo",
    street1: "215 Clayton St.",
    city: "San Francisco",
    state: "CA",
    zip: "94117",
    country: "US", // iso2 country code
    phone: "+1 555 341 9393",
    email: "shippotle@shippo.com",
});

Shippo.setApiKey('<API_TOKEN>');

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

Address createAddress = Address.create(addressMap);

using Shippo;
using Shippo.Models.Components;
ShippoSDK sdk = new ShippoSDK(apiKeyHeader: "<API_TOKEN>");
Address address = await sdk.Addresses.CreateAsync(
    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",
    }
);

// For a full list of supported libraries, review our client libraries page
// https://docs.goshippo.com/guides/client-libraries

If your request to create a new address was a success, the response should look like the following. If you don’t get a response like this, check your code and make sure your API token is correct.

{
   "is_complete": true,
   "object_created":"2022-07-09T02:19:13.174Z",
   "object_updated":"2022-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"shippotle@shippo.com",
   "validation_results": {},
   "name":"Shawn Ippotle",
   "company":"Shippo",
   "street_no": "",
   "street1":"215 Clayton St.",
   "street2":"",
   "street3":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "longitude": null,
   "latitude": null,
   "phone":"15553419393",
   "email":"shippotle@shippo.com",
   "is_residential":true,
   "metadata":"Customer ID 123456"
}

Next steps

Choose your API workflow: Now that you’ve made your first call, find the workflow that matches how you ship, such as rate shopping, batch labels, international, returns, or checkout rates.
Generate your first shipping label: Once you know your workflow, you’re ready to start shipping!

You can also start exploring our API reference to learn about all the Shippo API features.

Overview

Get started

AI & agents

Guides

Concepts

Generate your API Token

Install the client library for your language

Make your first API call

Next steps

​Generate your API Token

​Install the client library for your language

​Make your first API call

​Next steps

Generate your API Token

Install the client library for your language

Make your first API call

Next steps