API objects

What is a Shippo API Object?

Read this guide to understand how the Shippo API uses objects and object IDs.

In the Shippo API, objects use used to stored information. Objects are stored in the Shippo database. Examples of objects include addresses, carrier accounts, transactions, and labels.

Each object has an associated object ID. Each object ID is unique and you can use the object ID to reference and use the data in the object.

Use POST requests to create objects, GET requests to retrieve objects, and PUT requests to update objects.

Most objects in the Shippo API are immutable. This means that once you have created an object, you cannot change it. Instead, you must create a new one with the updated values. Carrier Accounts, Service Groups, and User Parcel Templates are the only objects that you can update.

How to use a Shippo API object

Follow this example to help understand how to use Shippo API objects.

Before starting this example, make sure you have generated your test token. In each example, replace <API_TOKEN> with the test token you have generated.

Create an address object

cURLRubyPythonPHPtypescript
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
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",
});

The expected response is a view of the address object that includes the address you created along with its metadata. It includes the object ID, "object_id" that you can use to reference the object.

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"
}

Use this object ID to retrieve the address details

cURLRubyPythonPHPtypescript
Copy
Copied
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/ \
    -H "Authorization: ShippoToken <API_TOKEN>"
Copy
Copied
# Retrieve an existing address by object_id
Shippo::Address.get('d799c2679e644279b59fe661ac8fa488')
Copy
Copied
# Retrieve an existing address by object_id
shippo_sdk.addresses.get("d799c2679e644279b59fe661ac8fa488")
Copy
Copied
// Retrieve an existing address by object_id
Shippo_Address::retrieve('d799c2679e644279b59fe661ac8fa488');
Copy
Copied
// Retrieve an existing address by object_id
shippo.addresses.get('d799c2679e644279b59fe661ac8fa488');

In this example, d799c2679e644279b59fe661ac8fa488 is the object ID of the address you have created.

The expected response is a view of the address object that includes the address you created along with its metadata. The same response you received when you created the address object.

Copy
Copied
{
   "is_complete": true,
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-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",
   "test": true
}

Shippo API object list

The following is a list of objects created in the Shippo API.

Object Object Name
Address Object AddressId
Parcel Object ParcelId
User Parcel Object UserParcelTemplateObjectId
Shipment Object ShipmentId
Rate Object RateId
Transaction Object TransactionId
Batch Object BatchId
Customs Item Object CustomsItemId
Customs Declaration Object CustomsDeclarationId
Carrier Account Object CarrierAccountId
Manifest Object ManifestId
Pickup Object PickupId
Order Object OrderId
Refund Object RefundId
Invoice Object InvoiceObjectId
Service Group Object ServiceGroupId
Shippo Account Object ShippoAccountId