Shipments

The heart of the Shippo API, a shipment is made up of “to” and “from” addresses and the parcel to be shipped. Once created, a shipment object can be used to retrieve shipping rates and purchase a shipping label.

The Shipments Object

Attribute	Data Type	Description
status	"WAITING", "QUEUED", "SUCCESS", "ERROR"	"Waiting" shipments have been successfully submitted but not yet been processed. "Queued" shipments are currently being processed. "Success" shipments have been processed successfully, meaning that rate generation has concluded. "Error" does not occur currently and is reserved for future use.
object_created	datetime	Date and time of Shipment creation.
object_updated	datetime	Date and time of last Shipment update.
object_id	string	Unique identifier of the given Shipment object.
object owner	string	Username of the user who created the Shipment object.
address_from	string	ID of the Address object that should be used as sender Address.
address_to	string	ID of the Address object that should be used as recipient Address.
parcels	array	Array of IDs of the Parcel objects to be shipped.
shipment_date	datetime (ISO 8601 date)	Date the shipment will be tendered to the carrier. Must be in the format "2014-01-18T00:35:03.463Z". Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
address_return	string	ID of the Address object where the shipment will be sent back to if it is not delivered (Only available for UPS, USPS, and Fedex shipments). If this field is not set, your shipments will be returned to the address_form.
customs_declaration	string	ID of the Customs Declarations object for an international shipment.
carrier_accounts	array	An array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. If no carrier account object_ids are set in this field, Shippo will attempt to generate rates using all the carrier accounts that have the 'active' field set.
metadata	string	A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra	object	An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Shipment Extra table below for all available services.
rates	array	An array with all available rates. If async has been set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.
messages	array	An array containing elements of the following schema: "code" (string): an identifier for the corresponding message (not always available") "message" (string): a publishable message containing further information.
test	bool	Indicates whether the object has been created in test mode

Shipment Extras

The following values are support for the extra field of the shipment object.

Attribute	Data Type	Description
status	"WAITING", "QUEUED", "SUCCESS", "ERROR"	"Waiting" shipments have been successfully submitted but not yet been processed. "Queued" shipments are currently being processed. "Success" shipments have been processed successfully, meaning that rate generation has concluded. "Error" does not occur currently and is reserved for future use.
object_created	datetime	Date and time of Shipment creation.
object_updated	datetime	Date and time of last Shipment update.
object_id	string	Username of the user who created the Shipment object.
address_from	string	ID of the Address object that should be used as recipient Address.
parcels	array	Array of IDs of the Parcel objects to be shipped.
shipment_date	datetime (ISO 8601 date)	Date the shipment will be tendered to the carrier. Must be in the format "2014-01-18T00:35:03.463Z". Defaults to current date and time if no value is provided. Please note that some carriers require this value to be in the future, on a working day, or similar.
address_return	string	ID of the Address object where the shipment will be sent back to if it is not delivered (Only available for UPS, USPS, and Fedex shipments). If this field is not set, your shipments will be returned to the address_form.
customs_declaration	string	ID of the Customs Declarations object for an international shipment.
metadata	string	A string of up to 100 characters that can be filled with any additional information you want to attach to the object.
extra	object	An object holding optional extra services to be requested. See the Shipment Extra table below for all available services.
rates	array	An array with all available rates. If async has been set to false in the request, this will be populated with all available rates in the response. Otherwise rates will be created asynchronously and this array will initially be empty.
metadata	string	A string of up to 100 characters that can be filled with any additional information you want to attach to the object.

POST Create a New Shipment

A POST to the /shipment resource to allow your application to create a new parcel object.

/shipments/

BODY PARAMETERS

Attributes	Required/Optional	Data Type
address_from	required	string or object
address_to	required	string or object
parcels	required	string, object, or array
shipment_date	optional	datetime
address_return	optional	string or object
customs_declaration	optional	string or object
extra	optional	object
metadata	optional	string, up to 50 characters
async	optional	boolean

EXAMPLE REQUEST (Create a Shipment):

curl https://api.goshippo.com/shipments/ \
  -H "Authorization: ShippoToken <API_TOKEN>" \
  -H "Content-Type: application/json" \
  -d $'{
      "address_to": {
          "name": "Mr Hippo",
          "street1": "965 Mission St #572",
          "city": "San Francisco",
          "state": "CA",
          "zip": "94103",
          "country": "US",
          "phone": "4151234567",
          "email": "mrhippo@goshippo.com"
      },
      "address_from": {
          "name": "Mrs Hippo",
          "street1": "1092 Indian Summer Ct",
          "city": "San Jose",
          "state": "CA",
          "zip": "95122",
          "country": "US",
          "phone": "4159876543",
          "email": "mrshippo@goshippo.com"
      },
      "parcels": [{
          "length": "10",
          "width": "15",
          "height": "10",
          "distance_unit": "in",
          "weight": "1",
          "mass_unit": "lb"
      }],
      "async": false
  }'

EXAMPLE RESPONSE (from Create a Shipment):

{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:04:06.163Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"shippotle@goshippo.com",
   "status":"SUCCESS",
   "address_from":{
      "object_id": "fdabf0abb93c4460b60aa596116872a7",
      "validation_results": {},
      "is_complete": true,
      "name": "Mrs Hippo",
      "street1": "1092 Indian Summer Ct",
      "city": "San Jose",
      "state": "CA",
      "zip": "95122",
      "country": "US",
      "phone": "4159876543",
      "email": "mrshippo@goshippo.com"
   },
   "address_to":{
      "object_id": "0476d70c612a423f9509ba5f807569db",
      "is_complete": true,
      "validation_results": {},
      "name": "Mr Hippo",
      "street1": "965 Mission St #572",
      "city": "San Francisco",
      "state": "CA",
      "zip": "94103",
      "country": "US",
      "phone": "4151234567",
      "email": "mrhippo@goshippo.com"
   },
  "address_return":{
      "object_id": "fdabf0abb93c4460b60aa596116872a7",
      "is_complete": true,
      "validation_results": {},
      "name": "Mrs Hippo",
      "street1": "1092 Indian Summer Ct",
      "city": "San Jose",
      "state": "CA",
      "zip": "95122",
      "country": "US",
      "phone": "4159876543",
      "email": "mrshippo@goshippo.com"
   },
  "parcels":[{
      "object_id": "7df2ecf8b4224763ab7c71fae7ec8274",
      "length": "10",
      "width": "15",
      "height": "10",
      "distance_unit": "in",
      "weight": "1",
      "mass_unit": "lb"
   }],
   "shipment_date":"2013-12-03T12:00:00Z",
   "extra":{
      "insurance": {
        "amount": "",
        "currency": ""
      },
      "reference_1":"",
      "reference_2":""
   },
   "customs_declaration":null,
   "rates": [
        {
            "object_created": "2014-07-17T00:04:06.263Z",
            "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
            "object_owner": "shippotle@goshippo.com",
            "shipment": "89436997a794439ab47999701e60392e",
            "attributes": [],
            "amount": "5.50",
            "currency": "USD",
            "amount_local": "5.50",
            "currency_local": "USD",
            "provider": "USPS",
            "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
            "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
            "servicelevel": {
              "name": "Priority Mail",
              "token":"usps_priority",
              "terms": "",
            },
            "estimated_days": 2,
            "arrives_by": null,
            "duration_terms": "Delivery in 1 to 3 business days.",
            "messages": [],
            "carrier_account": "078870331023437cb917f5187429b093",
            "test": true
        },
        ...
    ],
   "carrier_accounts": [],
   "messages":[],
   "metadata":"Customer ID 123456",
   "test": true
}

GET Retrieve a Shipment

A GET to the /shipment resource to allow your application to retrieve an existing shipment by object ID.

/shipments/{shipment object id}

PATH PARAMETERS

Parameter	Required/Optional	Data Type	Description
Shipment Object ID	required	string	shipment object id

EXAMPLE REQUEST (Retrieve a Shipment)

curl https://api.goshippo.com/shipments/7c47d12aa95a4cbb9d90c167cca7bea7 \
   -H "Authorization: ShippoToken <API_TOKEN>"

EXAMPLE RESPONSE (from Retrieve a Shipment):

{
   "object_state":"VALID",
   "object_created": "2013-12-11T19:38:09.729Z",
   "object_updated": "2013-12-11T19:38:09.729Z",
   "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
   "object_owner": "shippotle@goshippo.com",
   "template": null,
   "length": "20",
   "width": "15",
   "height": "12",
   "distance_unit": "in",
   "weight": "5",
   "mass_unit": "lb",
   "metadata": "Customer ID 123456",
   "extra": {},
   "test": true
}

GET List All Shipments

A GET to the /shipment resource to allow your application to list all shipment objects.

/shipments/

EXAMPLE REQUEST (List All Shipments)

curl https://api.goshippo.com/shipments/ \
   -H "Authorization: ShippoToken <API_TOKEN>"

QUERY PARAMETERS

In order to filter results, you can use the below query parameters. A maximum date range of 90 days is permitted. Provided dates should be ISO 8601 UTC dates.

Parameter	Data Type	Description
object_created_gt	object	object(s) created greater than a provided date time
object_created_gte	object	object(s) created greater than or equal to a provided date time
object_created_lt	object	object(s) created greater less than a provided date time
object_created_lte	object	object(s) created less than or equal to a provided date time

Date Format Examples:

"2017-01-01"

"2017-01-01T03:30:30" or "2017-01-01T03:30:30.5"

"2017-01-01T03:30:30Z"

Example URL with the Query Parameters:

https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30

EXAMPLE RESPONSE (from List All Shipments)

{
   "next":"https://api.goshippo.com/shipments/?page=2",
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:04:06.163Z",
         "object_updated":"2014-07-17T00:06:05.416Z",
         "object_id":"89436997a794439ab47999701e60392e",
         "object_owner":"shippotle@goshippo.com",
         "status":"SUCCESS",
         "address_from":{
            "object_id": "fdabf0abb93c4460b60aa596116872a7",
            "is_complete": true,
            "validation_results": {},
            "name": "Mrs Hippo",
            "street1": "1092 Indian Summer Ct",
            "city": "San Jose",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "4159876543",
            "email": "mrshippo@goshippo.com"
         },
         "address_to":{
            "object_id": "0476d70c612a423f9509ba5f807569db",
            "is_complete": true,
            "validation_results": {},
            "name": "Mr Hippo",
            "street1": "965 Mission St #572",
            "city": "San Francisco",
            "state": "CA",
            "zip": "94103",
            "country": "US",
            "phone": "4151234567",
            "email": "mrhippo@goshippo.com"
         },
         "parcels":[{
            "object_id": "7df2ecf8b4224763ab7c71fae7ec8274",

            "length": "10",
            "width": "15",
            "height": "10",
            "distance_unit": "in",
            "weight": "1",
            "mass_unit": "lb"
         }],
         "shipment_date":"2013-12-03T12:00:00Z",
         "address_return":{
            "object_id": "fdabf0abb93c4460b60aa596116872a7",
            "is_complete": true,
            "validation_results": {},
            "name": "Mrs Hippo",
            "street1": "1092 Indian Summer Ct",
            "city": "San Jose",
            "state": "CA",
            "zip": "95122",
            "country": "US",
            "phone": "4159876543",
            "email": "mrshippo@goshippo.com"
         },
        "extra":{
            "insurance": {
              "amount": "",
              "currency": ""
            },
            "reference_1":"",
            "reference_2":""
         },
         "customs_declaration":null,
         "rates": [
           {
               "object_created": "2014-07-17T00:04:06.263Z",
               "object_id": "545ab0a1a6ea4c9f9adb2512a57d6d8b",
               "object_owner": "shippotle@goshippo.com",
               "shipment": "89436997a794439ab47999701e60392e",
               "attributes": [],
               "amount": "5.50",
               "currency": "USD",
               "amount_local": "5.50",
               "currency_local": "USD",
               "provider": "USPS",
               "provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
               "provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
               "servicelevel": {
                 "name": "Priority Mail",
                 "token":"usps_priority",
                 "terms": "",
               },
               "estimated_days": 2,
               "arrives_by": null,
               "duration_terms": "Delivery in 1 to 3 business days.",
               "messages": [],
               "carrier_account": "078870331023437cb917f5187429b093",
               "test": true
           },
           ...
         ],
         "carrier_accounts": [],
         "messages":[
            {
               "source":"UPS",
               "code":"",
               "text":"RatedShipmentWarning: Ship To Address Classification is changed from Commercial to Residential"
            }
         ],
         "metadata":"Customer ID 123456",
         "test": true
      },
      {...},
      {...}
   ]
}