API Resources

All API URLs listed in this documentation are relative to https://api.goshippo.com/v1/. For example, the /addresses/ resource is reachable at https://api.goshippo.com/v1/addresses/.

Authentication

The API requires Basic HTTP Authentication with your Shippo username and password. Don't have them? Sign up here.

The API is available via Secure Socket Layer (SSL) only. Insecure attempts to access the API will return HTTP status 403/Forbidden.

Request & Response Data

Request data is passed to the API by POSTing JSON arrays with the appropriate key/value-pairs to the respective resource. The documentation for each API resource contains more details on the values accepted by a given resource. The returned data is also formatted as JSON array. You can specify how many results per page are to be returned. For instance, /v1/rates/?results=25 will return up to 25 results.

Disposable Objects

The Shippo API is built with simplicity in mind. While you can GET and POST Addresses, Parcels, Shipments and Transactions, you can only GET all other resources. This means that once you created an object, you cannot change it. Instead, create a new one with the desired values.

Address objects are used for creating Shipments, obtaining Rates and printing Labels, and thus are one of the fundamental building blocks of the Shippo API.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "object_purpose": "QUOTE",
    "name": "Laura Behrens Wu",
    "company": "Shippo",
    "street1": "Clayton St.",
    "street_no": "215",
    "street2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "laura@goshippo.com",
    "metadata": "Customer ID 123456"
}

						
					

						
							
{
    "object_state": "VALID",
    "object_purpose": "QUOTE",
    "object_source": "FULLY_ENTERED",
    "object_created": "2013-12-11T19:38:09.729Z",
    "object_updated": "2013-12-11T19:38:09.729Z",
    "object_id": "fcd9c72b564d4bfa8c03299ed6545132",
    "object_owner": "tech@goshippo.com",
    "name": "Laura Behrens Wu",
    "company": "Shippo",
    "street1": "Clayton St.",
    "street_no": "215",
    "street2": "",
    "city": "San Francisco",
    "state": "CA",
    "zip": "94117",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "laura@goshippo.com",
    "ip": "",
    "metadata": "Customer ID 123456",
    "messages": []
}

						
					

Creates a new address object.

Attributes

						
							
curl https://api.goshippo.com/v1/addresses/ \
    -u <USERNAME>:<PASSWORD> \
    -d name="Laura Behrens Wu" \
    -d object_purpose="PURCHASE" \
    -d company="Shippo" \
    -d street1="Clayton St." \
    -d street_no="215" \
    -d street2="" \
    -d city="San Francisco" \
    -d state="CA" \
    -d zip=94117 \
    -d country=US \
    -d phone="+1 555 341 9393" \
    -d email=laura@goshippo.com\
    -d metadata="Customer ID 123456"

						
					

						
							
{
   "object_state":"VALID",
   "object_purpose":"PURCHASE",
   "object_source":"FULLY_ENTERED",
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"unittest",
   "name":"Laura Behrens Wu",
   "company":"Shippo",
   "street_no":"215",
   "street1":"Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"laura@goshippo.com",
   "ip":null,
   "messages":[

   ],
   "metadata":"Customer ID 123456"
}

						
					

Retrieve an existing address by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/addresses/d799c2679e644279b59fe661ac8fa488 \
	-u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "object_state":"VALID",
   "object_purpose":"PURCHASE",
   "object_source":"FULLY_ENTERED",
   "object_created":"2014-07-09T02:19:13.174Z",
   "object_updated":"2014-07-09T02:19:13.174Z",
   "object_id":"d799c2679e644279b59fe661ac8fa488",
   "object_owner":"unittest",
   "name":"Laura Behrens Wu",
   "company":"Shippo",
   "street_no":"215",
   "street1":"Clayton St.",
   "street2":"",
   "city":"San Francisco",
   "state":"CA",
   "zip":"94117",
   "country":"US",
   "phone":"15553419393",
   "email":"laura@goshippo.com",
   "ip":null,
   "messages":[

   ],
   "metadata":"Customer ID 123456"
}

						
					

By checking if an Address exists in the USPS database, this method provides a mean to verify that an Address is valid. If the Address provided contains some fields that are inaccurate, the api will attempt to correct these fields. Otherwise, if the address is too ambiguous and cannot be corrected, the object_state in the response will be set to INVALID.
Address validation is currently only possible for US addresses.

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
curl https://api.goshippo.com/v1/addresses/d799c2679e644279b59fe661ac8fa488/validate/ \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
    "object_state": "VALID",
    "object_purpose": "QUOTE",
    "object_source": "VALIDATOR",
    "object_created": "2013-12-11T19:38:09.729Z",
    "object_updated": "2013-12-11T19:38:09.729Z",
    "object_id": "550f0375bea44ab0bb1911377ede5084",
    "object_owner": "tech@goshippo.com",
    "name": "Laura Behrens Wu",
    "company": "Shippo",
    "street1": "215 CLAYTON ST",
    "street_no": "",
    "street2": "",
    "city": "SAN FRANCISCO",
    "state": "CA",
    "zip": "94117-4324",
    "country": "US",
    "phone": "+1 555 341 9393",
    "email": "laura@goshippo.com",
    "ip": "",
    "metadata": "Customer ID 123456",
    "messages": []
}

						
					

List all addresses.

Attributes

						
							
curl https://api.goshippo.com/v1/addresses/ \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "count":3,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_source":"FULLY_ENTERED",
         "object_created":"2014-07-16T23:20:31.089Z",
         "object_updated":"2014-07-16T23:20:31.089Z",
         "object_id":"747207de2ba64443b645d08388d0309c",
         "object_owner":"unittest",
         "name":"Laura Behrens Wu",
         "company":"Shippo",
         "street_no":"215",
         "street1":"Clayton St.",
         "street2":"",
         "city":"San Francisco",
         "state":"CA",
         "zip":"94117",
         "country":"US",
         "phone":"15553419393",
         "email":"laura@goshippo.com",
         "ip":null,
         "messages":[

         ],
         "metadata":"Customer ID 123456"
      },
      {...},
      {...}
   ]
}

						
					

Parcel objects are used for creating Shipments, obtaining Rates and printing Labels, and thus are one of the fundamental building blocks of the Shippo API. Parcels are created with their basic dimensions and their weight.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "length": "5",
    "width": "5",
    "height": "5",
    "distance_unit": "cm",
    "weight": "2",
    "mass_unit": "lb",
    "template": "",
    "metadata": "Customer ID 123456"
}

						
					

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

						
					

Creates a new parcel object.

Attributes

						
							
curl https://api.goshippo.com/v1/parcels/ \
    -u <USERNAME>:<PASSWORD> \
    -d length="5" \
    -d width="5" \
    -d height="5" \
    -d distance_unit="cm" \
    -d weight="2" \
    -d mass_unit="lb" \
    -d template="" \
    -d metadata="Customer ID 123456"

						
					

						
							
{
   "object_state":"VALID",
   "object_created":"2014-07-08T23:19:19.565Z",
   "object_updated":"2014-07-08T23:19:19.565Z",
   "object_id":"7df2ecf8b4224763ab7c71fae7ec8274",
   "object_owner":"unittest",
   "template":null,
   "length":"5",
   "width":"5",
   "height":"5",
   "distance_unit":"cm",
   "weight":"2",
   "mass_unit":"lb",
   "metadata":"Customer ID 123456"
}

						
					

Retrieve an existing parcel by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/parcels/7df2ecf8b4224763ab7c71fae7ec8274 \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{  
   "object_state":"VALID",
   "object_created":"2014-07-08T23:19:19.565Z",
   "object_updated":"2014-07-08T23:19:19.565Z",
   "object_id":"7df2ecf8b4224763ab7c71fae7ec8274",
   "object_owner":"unittest",
   "template":null,
   "length":"5.0000",
   "width":"5.0000",
   "height":"5.0000",
   "distance_unit":"cm",
   "weight":"2.0000",
   "mass_unit":"lb",
   "value_amount":null,
   "value_currency":null,
   "metadata":"Customer ID 123456"
}

						
					

List all parcel objects.

Attributes

						
							
curl https://api.goshippo.com/v1/parcels/ \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{
   "count":3,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_created":"2014-07-08T23:19:19.565Z",
         "object_updated":"2014-07-08T23:19:19.565Z",
         "object_id":"7df2ecf8b4224763ab7c71fae7ec8274",
         "object_owner":"unittest",
         "template":null,
         "length":"5.0000",
         "width":"5.0000",
         "height":"5.0000",
         "distance_unit":"cm",
         "weight":"2.0000",
         "mass_unit":"lb",
         "value_amount":null,
         "value_currency":null,
         "metadata":"Customer ID 123456"
      }
      {...},
      {...}
   ]
}

						
					

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.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "object_purpose": "QUOTE",
    "address_from": "4f406a13253945a8bc8deb0f8266b245",
    "address_to": "4c7185d353764d0985a6a7825aed8ffb",
    "parcel": "ec952343dd4843c39b42aca620471fd5",
    "submission_type": "PICKUP",
    "submission_date": "2013-12-03T12:00:00.000Z",
    "insurance_amount": "200",
    "insurance_currency": "USD",
    "extra": {
        "signature_confirmation": "standard"
    },
    "customs_declaration": "b741b99f95e841639b54272834bc478c",
    "reference_1": "",
    "reference_2": "",
    "metadata": "Customer ID 123456"
}

						
					

						
							
{
    "object_state": "VALID",
    "object_status": "QUEUED",
    "object_purpose": "QUOTE",
    "object_created": "2013-12-01T06:24:20.121Z",
    "object_updated": "2013-12-01T06:24:20.121Z",
    "object_id": "694b1057e5f046c684ce05fe2d8ae525",
    "object_owner": "tech@goshippo.com",
    "address_from": "4f406a13253945a8bc8deb0f8266b245",
    "address_to": "4c7185d353764d0985a6a7825aed8ffb",
    "address_return": "4f406a13253945a8bc8deb0f8266b245",
    "parcel": "ec952343dd4843c39b42aca620471fd5",
    "submission_type": "PICKUP",
    "submission_date": "2013-12-03T12:00:00.000Z",
    "insurance_amount": "200",
    "insurance_currency": "USD",
    "extra": {
        "signature_confirmation": "standard",
        "insurance_content": "Electronics"
    },
    "customs_declaration": "b741b99f95e841639b54272834bc478c",
    "reference_1": "",
    "reference_2": "",
    "rates_url": "https://api.goshippo.com/v1/shipments/694b1057e5f046c684ce05fe2d8ae525/rates/",
    "metadata": "Customer ID 123456",
    "messages": [
        {
            "code": "Endicia",
            "text": "Parcel dimensions exceed maximum dimensions."
        }
    ]
}

						
					

Creates a new shipment object.

Attributes

						
							
curl https://api.goshippo.com/v1/shipments/ \
    -u <USERNAME>:<PASSWORD> \
    -d object_purpose="QUOTE" \
    -d address_from="d799c2679e644279b59fe661ac8fa488" \
    -d address_to="42236bcf36214f62bcc6d7f12f02a849" \
    -d parcel="7df2ecf8b4224763ab7c71fae7ec8274" \
    -d submission_type="PICKUP" \
    -d submission_date="2013-12-03T12:00:00.000Z" \
    -d insurance_amount="30" \
    -d insurance_currency="USD"

						
					

						
							
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:04:06.163Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"unittest",
   "object_state":"VALID",
   "object_status":"QUEUED",
   "object_purpose":"PURCHASE",
   "address_from":"fdabf0abb93c4460b60aa596116872a7",
   "address_to":"0476d70c612a423f9509ba5f807569db",
   "address_return":"fdabf0abb93c4460b60aa596116872a7",
   "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
   "submission_type":"PICKUP",
   "submission_date":"2013-12-03T12:00:00Z",
   "insurance_amount":"30",
   "insurance_currency":"USD",
   "extra":{

   },
   "customs_declaration":null,
   "reference_1":"",
   "reference_2":"",
   "rates_url":"https://api.goshippo.com/v1/shipments/89436997a794439ab47999701e60392e/rates/",
   "messages":[

   ],
   "metadata":"Customer ID 123456"
}

						
					

To create a return label, simply pass the object_id of the original outbound Transaction to the "return_of" field. If this flag is set, purchasing the generated rates will create a Scan-based return label. The advantage of using a Scan-based label is that you will only be charged if the label is used/scanned (not when the label is created).The Shippo api currently supports Scan-based returns for USPS, Fedex and UPS. When the return_of flag is set, Shippo will automatically swap the address_from and address_to fields for label creation. Please check the return service terms and condition for the carrier you intend to use, and please let us know if you have any questions.

Attributes

						
							
curl https://api.goshippo.com/v1/shipments/ \
    -u <USERNAME>:<PASSWORD> \
    -d object_purpose="QUOTE" \
    -d address_from="d799c2679e644279b59fe661ac8fa488" \
    -d address_to="42236bcf36214f62bcc6d7f12f02a849" \
    -d parcel="7df2ecf8b4224763ab7c71fae7ec8274" \
    -d submission_type="PICKUP" \
    -d submission_date="2013-12-03T12:00:00.000Z" \
    -d return_of="763ab7c71fae7ec82747df2ecf8b4224" \
    -d insurance_amount="30" \
    -d insurance_currency="USD"

						
					

						
							
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:04:06.163Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"unittest",
   "object_state":"VALID",
   "object_status":"QUEUED",
   "object_purpose":"PURCHASE",
   "address_from":"fdabf0abb93c4460b60aa596116872a7",
   "address_to":"0476d70c612a423f9509ba5f807569db",
   "address_return":"fdabf0abb93c4460b60aa596116872a7",
   "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
   "submission_type":"PICKUP",
   "submission_date":"2013-12-03T12:00:00Z",
   "return_of":"763ab7c71fae7ec82747df2ecf8b4224",
   "insurance_amount":"30",
   "insurance_currency":"USD",
   "extra":{

   },
   "customs_declaration":null,
   "reference_1":"",
   "reference_2":"",
   "rates_url":"https://api.goshippo.com/v1/shipments/89436997a794439ab47999701e60392e/rates/",
   "messages":[

   ],
   "metadata":"Customer ID 123456"
}

						
					

Retrieve an existing shipment by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/shipments/7c47d12aa95a4cbb9d90c167cca7bea7 \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "object_created":"2014-07-17T00:04:06.163Z",
   "object_updated":"2014-07-17T00:06:05.416Z",
   "object_id":"89436997a794439ab47999701e60392e",
   "object_owner":"unittest",
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_purpose":"PURCHASE",
   "address_from":"fdabf0abb93c4460b60aa596116872a7",
   "address_to":"0476d70c612a423f9509ba5f807569db",
   "address_return":"fdabf0abb93c4460b60aa596116872a7",
   "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
   "submission_type":"PICKUP",
   "submission_date":"2013-12-03T12:00:00Z",
   "insurance_amount":"30.00",
   "insurance_currency":"USD",
   "extra":{

   },
   "customs_declaration":null,
   "reference_1":"",
   "reference_2":"",
   "rates_url":"https://api.goshippo.com/v1/shipments/89436997a794439ab47999701e60392e/rates/",
   "messages":[
      {
         "source":"UPS",
         "code":"",
         "text":"RatedShipmentWarning: Ship To Address Classification is changed from Commercial to Residential"
      },
      {
         "source":"UPS",
         "code":"",
         "text":"RatedShipmentWarning: Your invoice may vary from the displayed reference rates"
      },
      {
         "source":"UPS",
         "code":"",
         "text":"RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
      }
   ],
   "metadata":"Customer ID 123456"
}

						
					

List all shipment objects.

Attributes

						
							
curl https://api.goshippo.com/v1/shipments/ \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "count":1269,
   "next":"https://api.goshippo.com/v1/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":"unittest",
         "object_state":"VALID",
         "object_status":"SUCCESS",
         "object_purpose":"PURCHASE",
         "address_from":"fdabf0abb93c4460b60aa596116872a7",
         "address_to":"0476d70c612a423f9509ba5f807569db",
         "parcel":"7df2ecf8b4224763ab7c71fae7ec8274",
         "submission_type":"PICKUP",
         "submission_date":"2013-12-03T12:00:00Z",
         "address_return":"fdabf0abb93c4460b60aa596116872a7",
         "customs_declaration":null,
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "extra":{

         },
         "reference_1":"",
         "reference_2":"",
         "rates_url":"https://api.goshippo.com/v1/shipments/89436997a794439ab47999701e60392e/rates/",
         "messages":[
            {
               "source":"UPS",
               "code":"",
               "text":"RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
            },
            {
               "source":"UPS",
               "code":"",
               "text":"RatedShipmentWarning: Your invoice may vary from the displayed reference rates"
            },
            {
               "source":"UPS",
               "code":"",
               "text":"RatedShipmentWarning: Ship To Address Classification is changed from Commercial to Residential"
            }
         ],
         "metadata":"Customer ID 123456"
      },
      {...},
      {...}
   ]
}

						
					

Each valid Shipment object will automatically trigger the calculation of all available Rates. Depending on your Addresses and Parcel, there may be none, one or multiple Rates.

By default, the calculated Rates will return the price in two currencies under the "amount" and "amount_local" keys, respectively. The "amount" key will contain the price of a Rate expressed in the currency that is used in the country from which Parcel originates, and the "amount_local" key will contain the price expressed in the currency that is used in the country the Parcel is shipped to. You can request Rates with prices expressed in a different currency by adding the desired currency code in the end of the resource URL. The full list of supported currencies along with their codes can be viewed on open exchange rates.

Rates are created asynchronously. The response time depends exclusively on the carrier's server.

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "object_state": "VALID",
    "object_purpose": "PURCHASE",
    "object_created": "2013-12-09T01:56:52.780Z",
    "object_updated": "2013-12-09T01:56:52.780Z",
    "object_id": "cf6fea899f1848b494d9568e8266e076",
    "object_owner": "tech@goshippo.com",
    "attributes": [],
    "amount_local": "5.35",
    "currency_local": "USD",
    "amount": "5.35",
    "currency": "USD",
    "provider": "USPS",
    "provider_image_75": "https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
    "provider_image_200": "https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
    "servicelevel_name": "Priority Mail",
    "servicelevel_terms": "",
    "days": 2,
    "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
    "trackable": true,
    "insurance": true,
    "insurance_amount_local": "50.00",
    "insurance_currency_local": "USD",
    "insurance_amount": "50.00",
    "insurance_currency": "USD",
    "messages": [
        {
            "code": "",
            "text": ""
        }
    ]
}

						
					

Get rates for a shipping object.

Attributes

						
							
curl https://api.goshippo.com/v1/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/USD \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "count":10,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:10.118Z",
         "object_updated":"2014-07-17T00:04:10.627Z",
         "object_id":"ee81fab0372e419ab52245c8952ccaeb",
         "object_owner":"unittest",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[

         ],
         "amount":"5.35",
         "currency":"USD",
         "amount_local":"5.35",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
         "servicelevel_name":"Priority Mail",
         "servicelevel_terms":"",
         "days":1,
         "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"50.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"50.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      },
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:10.492Z",
         "object_updated":"2014-07-17T00:04:10.682Z",
         "object_id":"801084d9fa37403aa79a2dca2f84cbc5",
         "object_owner":"unittest",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[

         ],
         "amount":"3.62",
         "currency":"USD",
         "amount_local":"3.62",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
         "servicelevel_name":"Media Mail",
         "servicelevel_terms":"The material sent must be educational media. It cannot contain advertising, video games, computer drives, or digital drives of any kind.",
         "days":5,
         "duration_terms":"Delivery in 2 to 8 days.",
         "trackable":false,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      },
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:10.430Z",
         "object_updated":"2014-07-17T00:04:10.674Z",
         "object_id":"5e5f24e3806c452cadbc013f4a86a6eb",
         "object_owner":"unittest",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[
            "CHEAPEST",
            "BESTVALUE"
         ],
         "amount":"3.47",
         "currency":"USD",
         "amount_local":"3.47",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
         "servicelevel_name":"Library Mail",
         "servicelevel_terms":"Library Mail is a service for mailing items on loan from or mailed between academic institutions, public libraries, museums, and other qualified organizations in 2 to 8 days. Content is limited to books, sound recordings, academic theses, and certain other items. Each piece must show in the address or return address the name of a school or nonprofit organization.",
         "days":5,
         "duration_terms":"Delivery in 2 to 8 days.",
         "trackable":false,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      },
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:10.334Z",
         "object_updated":"2014-07-17T00:04:10.661Z",
         "object_id":"fd31f301b61c49048f861573d4364ff6",
         "object_owner":"unittest",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[

         ],
         "amount":"16.03",
         "currency":"USD",
         "amount_local":"16.03",
         "currency_local":"USD",
         "provider":"USPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
         "servicelevel_name":"Priority Mail Express",
         "servicelevel_terms":"",
         "days":1,
         "duration_terms":"Overnight delivery to most U.S. locations.",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      },
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:13.188Z",
         "object_updated":"2014-07-17T00:04:13.569Z",
         "object_id":"67f2d6c93d4f42f398ff4af787959bf6",
         "object_owner":"unittest",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[

         ],
         "amount":"10.92",
         "currency":"USD",
         "amount_local":"10.92",
         "currency_local":"USD",
         "provider":"UPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/UPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/UPS.png",
         "servicelevel_name":"Ground",
         "servicelevel_terms":"",
         "days":3,
         "duration_terms":"Delivery times vary. Delivered usually in 1-5 business days.",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      },
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:04:13.275Z",
         "object_updated":"2014-07-17T00:04:13.608Z",
         "object_id":"c41cdeaf28194fbe8b5f71cfccca09b4",
         "object_owner":"unittest",
         "shipment":"89436997a794439ab47999701e60392e",
         "attributes":[

         ],
         "amount":"13.05",
         "currency":"USD",
         "amount_local":"13.05",
         "currency_local":"USD",
         "provider":"UPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/UPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/UPS.png",
         "servicelevel_name":"Three-Day Select",
         "servicelevel_terms":"",
         "days":3,
         "duration_terms":"",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      }
   ]
}

						
					

Retrieve an existing rate by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/rates/ee81fab0372e419ab52245c8952ccaeb \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{
   "object_state":"VALID",
   "object_purpose":"PURCHASE",
   "object_created":"2014-07-17T00:04:10.118Z",
   "object_updated":"2014-07-17T00:04:10.627Z",
   "object_id":"ee81fab0372e419ab52245c8952ccaeb",
   "object_owner":"unittest",
   "shipment":"89436997a794439ab47999701e60392e",
   "attributes":[

   ],
   "amount":"5.77",
   "currency":"USD",
   "amount_local":"5.77",
   "currency_local":"USD",
   "provider":"USPS",
   "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/USPS.png",
   "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/USPS.png",
   "servicelevel_name":"Priority Mail",
   "servicelevel_terms":"",
   "days":1,
   "duration_terms":"Delivery within 1, 2, or 3 days based on where your package started and where it’s being sent.",
   "trackable":true,
   "insurance":true,
   "insurance_amount_local":"30.00",
   "insurance_currency_local":"USD",
   "insurance_amount":"30.00",
   "insurance_currency":"USD",
   "messages":[

   ]
}

						
					

List all the rate objects that have been previously obtained through the get rates method.

Attributes

						
							
curl https://api.goshippo.com/v1/rates/ \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{
   "count":13845,
   "next":"https://api.goshippo.com/v1/rates/?page=2",
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_purpose":"PURCHASE",
         "object_created":"2014-07-17T00:03:47.601Z",
         "object_updated":"2014-07-17T00:03:47.933Z",
         "object_id":"cdadc9ea3d334635b2b577d97728c912",
         "object_owner":"unittest",
         "shipment":"025af8c79f23436b9ce4a3541864eab2",
         "attributes":[

         ],
         "amount":"13.05",
         "currency":"USD",
         "amount_local":"13.05",
         "currency_local":"USD",
         "provider":"UPS",
         "provider_image_75":"https://shippo-static.s3.amazonaws.com/providers/75/UPS.png",
         "provider_image_200":"https://shippo-static.s3.amazonaws.com/providers/200/UPS.png",
         "servicelevel_name":"Three-Day Select",
         "servicelevel_terms":"",
         "days":3,
         "duration_terms":"",
         "trackable":true,
         "insurance":true,
         "insurance_amount_local":"30.00",
         "insurance_currency_local":"USD",
         "insurance_amount":"30.00",
         "insurance_currency":"USD",
         "messages":[

         ]
      },
      {...}
   ]
}

						
					

A Transaction is the purchase of a Shipment Label for a given Shipment Rate. Transactions can be as simple as posting a Rate ID, but also allow you to define further parameters of the desired Label, such as pickup and notifications.

Transactions can only be created for Rates that are less than 7 days old and that have an object_purpose of "PURCHASE".

Transactions are created asynchronous. The response time depends exclusively on the carrier's server.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "rate": "67891d0ebaca4973ae2569d759da6139",
    "metadata": "Customer ID 123456"
}

						
					

						
							
{
    "object_state": "VALID",
    "object_status": "SUCCESS",
    "object_created": "2013-12-27T19:14:48.273Z",
    "object_updated": "2013-12-27T19:14:48.273Z",
    "object_id": "64bba01845ef40d29374032599f22588",
    "object_owner": "laura@goshippo.com",
    "was_test": false,
    "rate": "67891d0ebaca4973ae2569d759da6139",
    "tracking_number": "ZW70QJC",
    "tracking_status": {
        "object_created": "2013-12-27T23:17:41.411Z",
        "object_updated": "2013-12-29T23:14:49.373Z",
        "object_id": "a21b3d6831c14ceaba6730179ce6e784",
        "object_owner": "laura@goshippo.com",
        "status": "DELIVERED",
        "status_details": "Delivered, December 28, 2013, 2:17 pm, RIVERSIDE, CA 92504",
        "status_date": "2013-12-28T12:04:04.214Z"
    },
    "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction.action?tLabels=ZW70QJC",
    "label_url": "https://shippo-delivery.s3.amazonaws.com/96.pdf?Signature=PEdWrp0mFWAGwJp7FW3b%2FeA2eyY%3D&Expires=1385930652&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
    "metadata": "Customer ID 123456",
    "messages": [
        {
            "code": "",
            "text": "Carrier Information: Shipping Label Invoice will be sent to Sender only."
        }
    ]
}

						
					

Creates a new transaction object and purchases the shipping label for the provided rate.

Attributes

						
							
curl https://api.goshippo.com/v1/transactions \
    -u <USERNAME>:<PASSWORD> \
    -d rate="ee81fab0372e419ab52245c8952ccaeb"

						
					

						
							
{
   "object_state":"VALID",
   "object_status":"QUEUED",
   "object_created":"2014-07-25T02:09:34.422Z",
   "object_updated":"2014-07-25T02:09:34.513Z",
   "object_id":"ef8808606f4241ee848aa5990a09933c",
   "object_owner":"unittest",
   "was_test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"",
   "tracking_status":null,
   "tracking_url_provider":"",
   "label_url":"",
   "messages":[

   ],
   "customs_note":"",
   "submission_note":"",
   "metadata":""
}

						
					

Retrieve an existing transaction by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/transactions/70ae8117ee1749e393f249d5b77c45e0 \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "object_state":"VALID",
   "object_status":"SUCCESS",
   "object_created":"2014-07-17T00:43:40.842Z",
   "object_updated":"2014-07-17T00:43:50.531Z",
   "object_id":"70ae8117ee1749e393f249d5b77c45e0",
   "object_owner":"unittest",
   "was_test":true,
   "rate":"ee81fab0372e419ab52245c8952ccaeb",
   "tracking_number":"9499907123456123456781",
   "tracking_status":{
      "object_created":"2014-07-17T00:43:50.402Z",
      "object_updated":"2014-07-17T00:43:50.402Z",
      "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
      "object_owner":"unittest",
      "status":"UNKNOWN",
      "status_details":"",
      "status_date":null
   },
   "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
   "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
   "messages":[

   ],
   "customs_note":"",
   "submission_note":"",
   "metadata":""
}

						
					

List all transaction objects.

Attributes

						
							
curl https://api.goshippo.com/v1/transactions/ \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "count":1234,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_state":"VALID",
         "object_status":"SUCCESS",
         "object_created":"2014-07-17T00:43:40.842Z",
         "object_updated":"2014-07-17T00:43:50.531Z",
         "object_id":"70ae8117ee1749e393f249d5b77c45e0",
         "object_owner":"unittest",
         "was_test":true,
         "rate":"ee81fab0372e419ab52245c8952ccaeb",
         "tracking_number":"9499907123456123456781",
         "tracking_status":{
            "object_created":"2014-07-17T00:43:50.402Z",
            "object_updated":"2014-07-17T00:43:50.402Z",
            "object_id":"907d5e6120ed491ea27d4f681a7ccd4d",
            "object_owner":"unittest",
            "status":"UNKNOWN",
            "status_details":"",
            "status_date":null
         },
         "tracking_url_provider":"https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781",
         "label_url":"https://shippo-delivery.s3.amazonaws.com/70ae8117ee1749e393f249d5b77c45e0.pdf?Signature=vDw1ltcyGveVR1OQoUDdzC43BY8%3D&Expires=1437093830&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA",
         "messages":[

         ],
         "customs_note":"",
         "submission_note":"",
         "metadata":""
      },
      {...},
      {...}
   ]
}

						
					

Customs items are distinct items in your international shipment parcel.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "description": "T-Shirt",
    "quantity": 2,
    "net_weight": "400",
    "mass_unit": "g",
    "value_amount": "20",
    "value_currency": "USD",
    "tariff_number": "",
    "origin_country": "US",
    "metadata": "Order ID #123123"
}

						
					

						
							
{
    "object_created": "2014-02-24T22:05:55.014",
    "object_updated": "2014-02-24T22:05:55.016",
    "object_id": "0265b7cc4d71468197b2e8584cf8fc05",
    "object_owner": "tech@goshippo.com",
    "object_state": "VALID",
    "description": "T-Shirt",
    "quantity": 2,
    "net_weight": "400",
    "mass_unit": "g",
    "value_amount": "20",
    "value_currency": "USD",
    "tariff_number": "",
    "origin_country": "US",
    "metadata": "Order ID #123123"
}

						
					

Creates a new Customs Item object.

Attributes

						
							
curl  https://api.goshippo.com/v1/customs/items/ \
    -u <USERNAME>:<PASSWORD> \
    -d description="T-Shirt" \
    -d quantity=2 \
    -d net_weight="400" \
    -d mass_unit="g" \
    -d value_amount="20" \
    -d value_currency="USD" \
    -d tariff_number="" \
    -d origin_country="US" \
    -d metadata="Order ID '123123'"

						
					

						
							
{
   "object_created":"2014-07-17T00:49:20.631Z",
   "object_updated":"2014-07-17T00:49:20.631Z",
   "object_id":"55358464c7b740aca199b395536981bd",
   "object_owner":"unittest",
   "object_state":"VALID",
   "description":"T-Shirt",
   "quantity":2,
   "net_weight":"400",
   "mass_unit":"g",
   "value_amount":"20",
   "value_currency":"USD",
   "origin_country":"US",
   "tariff_number":"",
   "metadata":"Order ID '123123'"
}

						
					

Retrieve an existing Customs Item by object id.

Attributes

						
							
curl  https://api.goshippo.com/v1/customs/items/55358464c7b740aca199b395536981bd \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "object_created":"2014-07-17T00:49:20.631Z",
   "object_updated":"2014-07-17T00:49:20.631Z",
   "object_id":"55358464c7b740aca199b395536981bd",
   "object_owner":"unittest",
   "object_state":"VALID",
   "description":"T-Shirt",
   "quantity":2,
   "net_weight":"400.0000",
   "mass_unit":"g",
   "value_amount":"20.00",
   "value_currency":"USD",
   "origin_country":"US",
   "tariff_number":"",
   "metadata":"Order ID '123123'"
}

						
					

List all custom-items objects.

Attributes

						
							
curl  https://api.goshippo.com/v1/customs/items/ \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "count":10,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T00:49:20.631Z",
         "object_updated":"2014-07-17T00:49:20.631Z",
         "object_id":"55358464c7b740aca199b395536981bd",
         "object_owner":"unittest",
         "object_state":"VALID",
         "description":"T-Shirt",
         "quantity":2,
         "net_weight":"400.0000",
         "mass_unit":"g",
         "value_amount":"20.00",
         "value_currency":"USD",
         "origin_country":"US",
         "tariff_number":"",
         "metadata":"Order ID '123123'"
      },
      {...},
      {...}
   ]
}

						
					

Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your international shipments.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Laura Behrens Wu",
    "disclaimer": "",
    "incoterm": "",
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123"
}

						
					

						
							
{
    "object_created": "2014-02-24T22:35:44.358",
    "object_updated": "2014-02-24T22:35:44.358",
    "object_id": "b741b99f95e841639b54272834bc478c",
    "object_owner": "tech@goshippo.com",
    "object_state": "VALID",
    "exporter_reference": "",
    "importer_reference": "",
    "contents_type": "MERCHANDISE",
    "contents_explanation": "T-Shirt purchase",
    "invoice": "#123123",
    "license": "",
    "certificate": "",
    "notes": "",
    "eel_pfc": "NOEEI_30_37_a",
    "aes_itn": "",
    "non_delivery_option": "ABANDON",
    "certify": true,
    "certify_signer": "Laura Behrens Wu",
    "disclaimer": "",
    "incoterm": "",
    "items": [
        "0c1a723687164307bb2175972fbcd9ef"
    ],
    "metadata": "Order ID #123123"
}

						
					

Creates a new Customs Declaration object.

Attributes

						
							
curl  https://api.goshippo.com/v1/customs/declarations/ \
    -u <USERNAME>:<PASSWORD> \
    -d exporter_reference="" \
    -d importer_reference="" \
    -d contents_type="MERCHANDISE" \
    -d contents_explanation="T-Shirt purchase" \
    -d invoice="#123123" \
    -d license="" \
    -d certificate="" \
    -d notes="" \
    -d eel_pfc="NOEEI_30_37_a" \
    -d aes_itn="" \
    -d non_delivery_option="ABANDON" \
    -d certify=true \
    -d certify_signer="Laura Behrens Wu" \
    -d disclaimer="" \
    -d incoterm="" \
    -d items="5087f181d1dc4b14b73fdbf636498886" \
    -d metadata="Order ID #123123"

						
					

						
							
{
   "object_created":"2014-07-17T01:01:08.306Z",
   "object_updated":"2014-07-17T01:01:08.306Z",
   "object_id":"e2197a54da9d470480f4f8796cc419cb",
   "object_owner":"unittest",
   "object_state":"VALID",
   "certify_signer":"Laura Behrens Wu",
   "certify":true,
   "items":[
      "5087f181d1dc4b14b73fdbf636498886"
   ],
   "non_delivery_option":"ABANDON",
   "contents_type":"MERCHANDISE",
   "contents_explanation":"T-Shirt purchase",
   "exporter_reference":"",
   "importer_reference":"",
   "invoice":"#123123",
   "commercial_invoice":false,
   "license":"",
   "certificate":"",
   "notes":"",
   "eel_pfc":"NOEEI_30_37_a",
   "aes_itn":"",
   "disclaimer":"",
   "incoterm":"",
   "metadata":"Order ID #123123"
}

						
					

Retrieve an existing customs-declaration by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/customs/declarations/e2197a54da9d470480f4f8796cc419cb \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "object_created":"2014-07-17T01:01:08.306Z",
   "object_updated":"2014-07-17T01:01:08.306Z",
   "object_id":"e2197a54da9d470480f4f8796cc419cb",
   "object_owner":"unittest",
   "object_state":"VALID",
   "certify_signer":"Laura Behrens Wu",
   "certify":true,
   "items":[
      "5087f181d1dc4b14b73fdbf636498886"
   ],
   "non_delivery_option":"ABANDON",
   "contents_type":"MERCHANDISE",
   "contents_explanation":"T-Shirt purchase",
   "exporter_reference":"",
   "importer_reference":"",
   "invoice":"#123123",
   "commercial_invoice":false,
   "license":"",
   "certificate":"",
   "notes":"",
   "eel_pfc":"NOEEI_30_37_a",
   "aes_itn":"",
   "disclaimer":"",
   "incoterm":"",
   "metadata":"Order ID #123123"
}

						
					

List all customs-declaration objects.

Attributes

						
							
curl https://api.goshippo.com/v1/customs/declarations/ \
	-u <USERNAME>:<PASSWORD>


						
					

						
							
{
   "count":11,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T01:01:08.306Z",
         "object_updated":"2014-07-17T01:01:08.306Z",
         "object_id":"e2197a54da9d470480f4f8796cc419cb",
         "object_owner":"unittest",
         "object_state":"VALID",
         "certify_signer":"Laura Behrens Wu",
         "certify":true,
         "items":[
            "5087f181d1dc4b14b73fdbf636498886"
         ],
         "non_delivery_option":"ABANDON",
         "contents_type":"MERCHANDISE",
         "contents_explanation":"T-Shirt purchase",
         "exporter_reference":"",
         "importer_reference":"",
         "invoice":"#123123",
         "commercial_invoice":false,
         "license":"",
         "certificate":"",
         "notes":"",
         "eel_pfc":"NOEEI_30_37_a",
         "aes_itn":"",
         "disclaimer":"",
         "incoterm":"",
         "metadata":"Order ID #123123"
      },
      {...},
      {...}
   ]
}

						
					

Refunds are reimbursements for successfully created but unused Transaction.

Please keep the following in mind:

• Once a Refund has been claimed, you must not use the shipping label for actual postage.
• Refunds take several days to be processed.
• Some carriers, e.g. FedEx and UPS, don't require refunds since the corresponding labels will only be charged after they have been scanned, i.e. used. The Shippo refund may be used for refunding of the $0.05 Shippo label fee.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "transaction": "35ed59f23a514ecfa2faeaed93a00086"
}

						
					

						
							
{
    "object_created": "2014-04-21T07:12:41.044Z",
    "object_updated": "2014-04-21T07:12:41.045Z",
    "object_id": "bd7b8379a2e847bcb0818125943dde5d",
    "object_owner": "tech@goshippo.com",
    "object_status": "QUEUED",
    "transaction": "35ed59f23a514ecfa2faeaed93a00086"
}

						
					

Creates a new refund object.

Attributes

						
							
curl  https://api.goshippo.com/v1/refunds/ \
    -u <USERNAME>:<PASSWORD> \
    -d transaction="4503427478ea45a899e9b54abc4c5803"	

						
					

						
							
{
   "object_created":"2014-07-17T15:38:37.372Z",
   "object_updated":"2014-07-17T15:38:37.381Z",
   "object_id":"d7c811cff9e24e4387418876f1ffd371",
   "object_owner":"unittest",
   "object_status":"QUEUED",
   "transaction":"8b7f25f33d2a4bb58060df94cb152434"
}

						
					

Retrieve an existing refund by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/refunds/d7c811cff9e24e4387418876f1ffd371 \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{
   "object_created":"2014-07-17T15:38:37.372Z",
   "object_updated":"2014-07-17T15:38:43.070Z",
   "object_id":"d7c811cff9e24e4387418876f1ffd371",
   "object_owner":"unittest",
   "object_status":"SUCCESS",
   "transaction":"8b7f25f33d2a4bb58060df94cb152434"
}

						
					

Retrieve an existing refund by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/refunds/ \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T15:38:37.372Z",
         "object_updated":"2014-07-17T15:38:43.070Z",
         "object_id":"d7c811cff9e24e4387418876f1ffd371",
         "object_owner":"unittest",
         "object_status":"SUCCESS",
         "transaction":"8b7f25f33d2a4bb58060df94cb152434"
      },
      {...}
   ]
}

						
					

Manifests are close-outs of shipping labels of a certain day. Some carriers require Manifests to properly process the shipments.

The following carriers require Manifests:

• DHL Express purchased through Shippo: if you use Shippo's DHL Express rates, you need to manifest ("close out") your shipments each day before submitting them to the carrier. If you don't close out a shipment, it might not be processed at all by DHL Express.

The following carriers offer Manifests optionally:

• USPS scan form: the USPS allows you to create "scan forms", which also is a Manifest. By creating scan forms, the USPS doesn't need to scan each of your packages individually and all tracking codes are updated immediately.

Attributes

Response attributes

A response from the Address resource contains the request data, plus the data outlined below.

						
							
{
    "provider": "USPS",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "28828839a2b04e208ac2aa4945fbca9a"
}

						
					

						
							
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "tech@goshippo.com",
    "object_status": "SUCCESS",
    "provider": "USPS",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "28828839a2b04e208ac2aa4945fbca9a",
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ]
}

						
					

Creates a new manifest object.

Attributes

						
							
curl https://api.goshippo.com/v1/manifests/ \
    -u <USERNAME>:<PASSWORD> \
    -d provider="USPS" \
    -d submission_date="2014-05-16T23:59:59Z" \
    -d address_from="d799c2679e644279b59fe661ac8fa488" 

						
					

						
							
{
    "object_created": "2014-05-16T03:43:52.765Z",
    "object_updated": "2014-05-16T03:43:55.445Z",
    "object_id": "0fadebf6f60c4aca95fa01bcc59c79ae",
    "object_owner": "tech@goshippo.com",
    "object_status": "SUCCESS",
    "provider": "USPS",
    "submission_date": "2014-05-16T23:59:59Z",
    "address_from": "d799c2679e644279b59fe661ac8fa488",
    "documents": [
        "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
    ]
}

						
					

Retrieve an existing manifest by object id.

Attributes

						
							
curl https://api.goshippo.com/v1/manifests/0fadebf6f60c4aca95fa01bcc59c79ae \
    -u <USERNAME>:<PASSWORD> 

						
					

						
							
{
   "object_created":"2014-05-16T03:43:52.765Z",
   "object_updated":"2014-05-16T03:43:55.445Z",
   "object_id":"0fadebf6f60c4aca95fa01bcc59c79ae",
   "object_owner":"admin",
   "object_status":"SUCCESS",
   "provider":"USPS",
   "submission_date":"2014-05-16T23:59:59Z",
   "address_from":"008ee72b723c4f129371b7346fe2f55f",
   "documents":[
      "https://shippo-delivery.s3.amazonaws.com/0fadebf6f60c4aca95fa01bcc59c79ae.pdf?Signature=tlQU3RECwdHUQJQadwqg5bAzGFQ%3D&Expires=1402803835&AWSAccessKeyId=AKIAJTHP3LLFMYAWALIA"
   ]
}

						
					

List all Manifest objects.

Attributes

						
							
curl https://api.goshippo.com/v1/manifests/ \
    -u <USERNAME>:<PASSWORD>

						
					

						
							
{
   "count":2,
   "next":null,
   "previous":null,
   "results":[
      {
         "object_created":"2014-07-17T16:09:46.079Z",
         "object_updated":"2014-07-17T16:09:46.079Z",
         "object_id":"aa41ad380c53413ab2cee8ba98d2cc34",
         "object_owner":"unittest",
         "object_status":"QUEUED",
         "provider":"USPS",
         "submission_date":"2014-05-16T23:59:59Z",
         "address_from":"d799c2679e644279b59fe661ac8fa488",
         "documents":[

         ]
      },
      {...}
   ]
}

						
					

Both Rate and Transaction API calls trigger asynchronous object creations. This means that shipping rates and label purchases are not available in the API response right after you have created the corresponding object.

Why rates & labels are returned asynchronously

The advantage of asynchronous rates and labels is that your API request won't be blocked while Shippo calls the upstream APIs (e.g. USPS or FedEx API). This gives you a much higher flexibility of building a fast application that does not depend on external API response times.

How long does it take for rates and labels to be created?

The time until rates and labels have been created depends exclusively on the corresponding carrier's API response time. Usually, most carriers return rates and labels within 1 second or less. In test mode, response times might be a bit higher.

What's the best way to retrieve rates and labels?

Depending on the use case, we recommend one of the following ways:

• Server-side API calls: simply access the corresponding API resource (Shipment for rates or Transaction for labels) one or multiple times after object creation. As soon as a carrier has returned a rate or label, it will be accessible in the corresponding Shippo API resource.
• Client-side API calls: you can GET a resource by using your Authentication Token in a client-side AJAX call. This is the preferred solution for client-side rating and label display.
• Websockets: Shippo offers a websocket streaming solution for both client- and server-side use cases. Please contact us at support@goshippo.com for more details.

The Shippo api also supports nested API calls. This enables the creation of objects that require the passing of other objects as parameters.

The example provided demonstrates how a shipment object can be created, in one request, by passing address_from, address_to, and parcels objects in a nested fashion.

						
							
curl https://api.goshippo.com/v1/shipments/  \
    -u <USERNAME>:<PASSWORD> \
    -H "Content-Type: application/json"  \
    -d '{
       "object_purpose":"PURCHASE",
       "address_from":{
          "object_purpose":"PURCHASE",
          "name":"Laura Behrens Wu",
          "company":"Shippo",
          "street1":"Clayton St.",
          "street_no":"215",
          "street2":"",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94117",
          "country":"US",
          "phone":"+1 555 341 9393",
          "email":"laura@goshippo.com",
          "metadata":"Customer ID 123456"
       },
       "address_to":{
          "object_purpose":"PURCHASE",
          "name":"Laura Behrens Wu",
          "company":"Shippo",
          "street1":"Mission St.",
          "street_no":"814",
          "street2":"",
          "city":"San Francisco",
          "state":"CA",
          "zip":"94105",
          "country":"US",
          "phone":"+1 555 341 9393",
          "email":"laura@goshippo.com",
          "metadata":"Customer ID 123456"
       },
       "parcel":{
          "length":"5",
          "width":"5",
          "height":"5",
          "distance_unit":"in",
          "weight":"2",
          "mass_unit":"lb",
          "template":"",
          "metadata":"Customer ID 123456"
       },
       "submission_type":"DROPOFF",
       "submission_date":"2014-06-06T12:00:00.000Z",
       "insurance_value":"",
       "insurance_currency":"",
       "extra":{
          "signature_confirmation":true
       },
       "customs_declaration":"",
       "reference_1":"",
       "reference_2":"",
       "metadata":"Customer ID 123456"
    }'

						
					

						
							
{
   "object_created":"2014-07-25T23:44:40.866Z",
   "object_updated":"2014-07-25T23:44:40.866Z",
   "object_id":"3be9d9e89bba4f98b6b1255e4655e732",
   "object_owner":"unittest",
   "object_state":"VALID",
   "object_status":"QUEUED",
   "object_purpose":"PURCHASE",
   "address_from":"45edd61cd6db40b287d6e7a498a3ae49",
   "address_to":"19b92a52e854448bb70b693303902ac7",
   "parcel":"886ed7269e144c32a5e4166e6604fb50",
   "submission_type":"DROPOFF",
   "submission_date":"2014-06-06T12:00:00Z",
   "address_return":"45edd61cd6db40b287d6e7a498a3ae49",
   "customs_declaration":null,
   "insurance_amount":"0",
   "insurance_currency":null,
   "extra":{
      "signature_confirmation":true
   },
   "reference_1":"",
   "reference_2":"",
   "rates_url":"https://api.goshippo.com/v1/shipments/3be9d9e89bba4f98b6b1255e4655e732/rates/",
   "messages":[

   ],
   "metadata":"Customer ID 123456"
}

						
					

You can specify webhooks in your Shippo API settings. Every time the tracking status of one of your packages has been updated, we will send a POST request to each of the webhook URLs set up for your account.

Webhooks format

We will serialize the corresponding Transaction object into JSON and POST to each of your webhook URLs.

Webhooks handling

For each tracking update, we will POST to your webhooks up to 5 times with a 600 millisecond delay. You should return a HTTP status 200. If the 5th webhook POST requests fails, we will automatically deactivate this specific webhook.