API quickstart guide

Follow this guide to make your first Shippo API call. In this guide, you will learn how to create an address using the Shippo API.

Generate your API Token

Follow the Authentication guide to generate your API Token.

Note

When 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

cURLRubyPythonPHPNodeJavaC#Other
Copy
Copied
    # cURL
    # No library needed for cURL
Copy
Copied
    #Ruby
    gem install shippo
Copy
Copied
    #Python
    pip install shippo
Copy
Copied
    //PHP
    //Follow the steps in 
    // https://github.com/goshippo/shippo-php-client
Copy
Copied
    // Node.JS
    npm install shippo
Copy
Copied
    // Java
    npm install shippo
Copy
Copied
    // C#
    //The C# client library source code and all installation methods are available on 
    // https://github.com/goshippo/shippo-csharp-client
Copy
Copied
  //Other libraries
  //For a full list of supported libraries, review our client libraries page
  // https://docs.goshippo.com/docs/guides_general/clientlibraries/

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.

cURLRubyPythonPHPNodeJavaC#Other
Copy
Copied
 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"
Copy
Copied
require 'shippo'
Shippo::API.token = '<API_TOKEN>'

# Create address object
address_from = Shippo::Address.create(
    :name => "Shawn Ippotle",
    :company => "Shippo",
    :street1 => "Clayton St.",
    :street_no => "215",
    :street2 => "",
    :city => "San Francisco",
    :state => "CA",
    :zip => "94117",
    :country => "US",
    :phone => "+1 555 341 9393",
    :email => "shippotle@shippo.com"
)
Copy
Copied
import shippo
from shippo.models import components

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

shippo_sdk.addresses.create(
    address_create_request=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"
    )
)
Copy
Copied
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" 
));
Copy
Copied
  // Create address object
var shippo = require('shippo')('<API_TOKEN>');
var addressFrom  = shippo.address.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",
})
Copy
Copied
    // Java
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);
Copy
Copied
    // C#
    APIResource resource = new APIResource ('<API_TOKEN>');
   resource.CreateAddress(new Hashtable(){
    {"name", "Mr. Hippo"},
    {"company", "Shippo"},
    {"street1", "215 Clayton St."},
    {"city", "San Francisco"},
    {"state", "CA"},
    {"zip", "94117"},
    {"country", "US"},
    {"phone", "+1 555 341 9393"},
    {"email", "support@goshipppo.com"}});
Copy
Copied
  //Other libraries
  //For a full list of supported libraries, review our client libraries page
  // https://docs.goshippo.com/docs/guides_general/clientlibraries/

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.

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

You now know how to make API calls using the Shippo API. Your next step is to create your first shipping label.

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