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(
    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.