Overview
Addresses API v2
cURL
curl https://api.goshippo.com/shipments/ \
-H "Authorization: ShippoToken <API_TOKEN>"{
"next": "baseurl?page=3&results=10",
"previous": "baseurl?page=1&results=10",
"results": [
{
"metadata": "Customer ID 123456",
"address_from": {
"country": "US",
"name": "Shwan Ippotle",
"company": "Shippo",
"street1": "215 Clayton St.",
"street2": "<string>",
"street3": "",
"street_no": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"phone": "+1 555 341 9393",
"email": "shippotle@shippo.com",
"is_residential": true,
"metadata": "Customer ID 123456",
"is_complete": true,
"latitude": 123,
"longitude": 123,
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "d799c2679e644279b59fe661ac8fa488",
"object_owner": "shippotle@shippo.com",
"object_updated": "2014-07-09T02:19:13.174Z",
"validation_results": {
"is_valid": false,
"messages": [
{
"code": "Unknown Street",
"source": "Shippo Address Validator",
"text": "City, State and ZIP Code are valid, but street address is not a match.",
"type": "address_warning"
}
]
},
"test": false
},
"address_to": {
"country": "US",
"name": "Shwan Ippotle",
"company": "Shippo",
"street1": "215 Clayton St.",
"street2": "<string>",
"street3": "",
"street_no": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"phone": "+1 555 341 9393",
"email": "shippotle@shippo.com",
"is_residential": true,
"metadata": "Customer ID 123456",
"is_complete": true,
"latitude": 123,
"longitude": 123,
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "d799c2679e644279b59fe661ac8fa488",
"object_owner": "shippotle@shippo.com",
"object_updated": "2014-07-09T02:19:13.174Z",
"validation_results": {
"is_valid": false,
"messages": [
{
"code": "Unknown Street",
"source": "Shippo Address Validator",
"text": "City, State and ZIP Code are valid, but street address is not a match.",
"type": "address_warning"
}
]
},
"test": false
},
"carrier_accounts": [
"<string>"
],
"messages": [
{
"source": "UPS",
"code": "carrier_timeout",
"text": "UPS API did not respond. Please try again in a few minutes."
}
],
"object_created": "2023-11-07T05:31:56Z",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"object_owner": "pp@gmail.com",
"object_updated": "2023-11-07T05:31:56Z",
"parcels": [
{
"mass_unit": "lb",
"weight": "1",
"distance_unit": "in",
"height": "1",
"length": "1",
"width": "1",
"extra": {
"COD": {
"amount": "5.5",
"currency": "USD",
"payment_method": "CASH"
},
"insurance": {
"amount": "5.5",
"content": "Laptop",
"currency": "USD",
"provider": "UPS"
},
"reference_1": "<string>",
"reference_2": "<string>"
},
"metadata": "Customer ID 123456",
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"object_owner": "shippotle@shippo.com",
"object_state": "VALID",
"object_updated": "2014-07-09T02:19:13.174Z",
"template": "FedEx_Box_10kg",
"test": true
}
],
"rates": [
{
"amount": "5.5",
"amount_local": "5.5",
"currency": "USD",
"currency_local": "USD",
"attributes": [
"BESTVALUE"
],
"carrier_account": "078870331023437cb917f5187429b093",
"object_created": "2023-11-07T05:31:56Z",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"object_owner": "pp@gmail.com",
"provider": "USPS",
"servicelevel": {
"name": "Priority Mail Express",
"terms": "<string>",
"token": "usps_priority_express",
"extended_token": "<string>",
"parent_servicelevel": {
"name": "Priority Mail Express",
"terms": "<string>",
"token": "usps_priority_express",
"extended_token": "<string>"
}
},
"shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
"arrives_by": "08:30:00",
"duration_terms": "Delivery in 1 to 3 business days",
"estimated_days": 2,
"included_insurance_price": "1.05",
"messages": [
{
"source": "UPS",
"code": "carrier_timeout",
"text": "UPS API did not respond. Please try again in a few minutes."
}
],
"provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
"provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
"test": true,
"zone": "1"
}
],
"status": "QUEUED",
"extra": {
"accounts_receivable_customer_account": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"alcohol": {
"contains_alcohol": true,
"recipient_type": "licensee"
},
"ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
"appropriation_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"authority_to_leave": true,
"bill_of_lading_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"billing": {
"account": "<string>",
"country": "<string>",
"participation_code": "<string>",
"type": "SENDER",
"zip": "<string>"
},
"bypass_address_validation": true,
"carbon_neutral": true,
"carrier_hub_id": "<string>",
"carrier_hub_travel_time": 123,
"COD": {
"amount": "5.5",
"currency": "USD",
"payment_method": "CASH"
},
"cod_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"container_type": "<string>",
"critical_pull_time": "<string>",
"customer_branch": "<string>",
"customer_reference": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 1
},
"dangerous_goods": {
"contains": true,
"biological_material": {
"contains": true
},
"lithium_batteries": {
"contains": true
}
},
"dangerous_goods_code": "01",
"dealer_order_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"delivery_instructions": "<string>",
"dept_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 3
},
"dry_ice": {
"contains_dry_ice": true,
"weight": "<string>"
},
"fda_product_code": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"fulfillment_center": "<string>",
"insurance": {
"amount": "5.5",
"content": "<string>",
"currency": "USD",
"provider": "FEDEX"
},
"invoice_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 2
},
"is_return": true,
"lasership_attrs": [
"TwoPersonDelivery"
],
"lasership_declared_value": "<string>",
"manifest_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"model_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"part_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"po_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 2
},
"preferred_delivery_timeframe": "10001200",
"premium": true,
"production_code": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"purchase_request_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"qr_code_requested": true,
"reference_1": "<string>",
"reference_2": "<string>",
"request_retail_rates": true,
"return_service_type": "PRINT_AND_MAIL",
"rma_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 1
},
"saturday_delivery": true,
"salesperson_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"serial_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"signature_confirmation": "STANDARD",
"store_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"transaction_reference_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"usmca_eligible": true
},
"shipment_date": "2021-03-22T12:00:00Z",
"address_return": {
"country": "US",
"name": "Shwan Ippotle",
"company": "Shippo",
"street1": "215 Clayton St.",
"street2": "<string>",
"street3": "",
"street_no": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"phone": "+1 555 341 9393",
"email": "shippotle@shippo.com",
"is_residential": true,
"metadata": "Customer ID 123456",
"is_complete": true,
"latitude": 123,
"longitude": 123,
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "d799c2679e644279b59fe661ac8fa488",
"object_owner": "shippotle@shippo.com",
"object_updated": "2014-07-09T02:19:13.174Z",
"validation_results": {
"is_valid": false,
"messages": [
{
"code": "Unknown Street",
"source": "Shippo Address Validator",
"text": "City, State and ZIP Code are valid, but street address is not a match.",
"type": "address_warning"
}
]
},
"test": false
},
"customs_declaration": {
"certify": true,
"certify_signer": "Shawn Ippotle",
"contents_type": "MERCHANDISE",
"items": [
"5087f181d1dc4b14b73fdbf636498886"
],
"non_delivery_option": "RETURN",
"aes_itn": "<string>",
"b13a_filing_option": "FILED_ELECTRONICALLY",
"b13a_number": "<string>",
"certificate": "<string>",
"commercial_invoice": true,
"contents_explanation": "T-Shirt purchase",
"disclaimer": "<string>",
"duties_payor": {
"account": "2323434543",
"type": "THIRD_PARTY",
"address": {
"name": "Patrick Kavanagh",
"zip": "80331",
"country": "DE"
}
},
"exporter_identification": {
"eori_number": "PL123456790ABCDE",
"tax_id": {
"number": "123456789",
"type": "EIN"
}
},
"exporter_reference": "<string>",
"importer_reference": "<string>",
"is_vat_collected": true,
"invoice": "#123123",
"license": "<string>",
"metadata": "Order ID #123123",
"notes": "<string>",
"address_importer": "257ba08436604d2aaf069caafe7acb2a",
"eel_pfc": "NOEEI_30_37_a",
"incoterm": "DDP",
"invoiced_charges": {
"currency": "<string>",
"total_shipping": "<string>",
"total_taxes": "<string>",
"total_duties": "<string>",
"other_fees": "<string>"
},
"object_created": "2014-07-17T01:01:08.306Z",
"object_id": "e2197a54da9d470480f4f8796cc419cb",
"object_owner": "shippotle@shippo.com",
"object_state": "VALID",
"object_updated": "2014-07-17T01:01:08.306Z",
"test": true
},
"test": true
}
]
}Shipments
List all shipments
Returns a list of all shipment objects.<br><br>
In order to filter results, you must use the below path parameters.
Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).<br><br>
Optional path parameters:<br>
`object_created_gt`- object(s) created greater than a provided date time<br>
`object_created_gte` - object(s) created greater than or equal to a provided date time<br>
`object_created_lt` - object(s) created less than a provided date time<br>
`object_created_lte` - object(s) created less than or equal to a provided date time<br>
Date format examples:<br>
`2017-01-01`<br>
`2017-01-01T03:30:30` or `2017-01-01T03:30:30.5`<br>
`2017-01-01T03:30:30Z`<br><br>
Example URL:<br>
`https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30`<br><br>
Note: Shipment objects older than 390 days are not returned.
GET
/
shipments
cURL
curl https://api.goshippo.com/shipments/ \
-H "Authorization: ShippoToken <API_TOKEN>"{
"next": "baseurl?page=3&results=10",
"previous": "baseurl?page=1&results=10",
"results": [
{
"metadata": "Customer ID 123456",
"address_from": {
"country": "US",
"name": "Shwan Ippotle",
"company": "Shippo",
"street1": "215 Clayton St.",
"street2": "<string>",
"street3": "",
"street_no": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"phone": "+1 555 341 9393",
"email": "shippotle@shippo.com",
"is_residential": true,
"metadata": "Customer ID 123456",
"is_complete": true,
"latitude": 123,
"longitude": 123,
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "d799c2679e644279b59fe661ac8fa488",
"object_owner": "shippotle@shippo.com",
"object_updated": "2014-07-09T02:19:13.174Z",
"validation_results": {
"is_valid": false,
"messages": [
{
"code": "Unknown Street",
"source": "Shippo Address Validator",
"text": "City, State and ZIP Code are valid, but street address is not a match.",
"type": "address_warning"
}
]
},
"test": false
},
"address_to": {
"country": "US",
"name": "Shwan Ippotle",
"company": "Shippo",
"street1": "215 Clayton St.",
"street2": "<string>",
"street3": "",
"street_no": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"phone": "+1 555 341 9393",
"email": "shippotle@shippo.com",
"is_residential": true,
"metadata": "Customer ID 123456",
"is_complete": true,
"latitude": 123,
"longitude": 123,
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "d799c2679e644279b59fe661ac8fa488",
"object_owner": "shippotle@shippo.com",
"object_updated": "2014-07-09T02:19:13.174Z",
"validation_results": {
"is_valid": false,
"messages": [
{
"code": "Unknown Street",
"source": "Shippo Address Validator",
"text": "City, State and ZIP Code are valid, but street address is not a match.",
"type": "address_warning"
}
]
},
"test": false
},
"carrier_accounts": [
"<string>"
],
"messages": [
{
"source": "UPS",
"code": "carrier_timeout",
"text": "UPS API did not respond. Please try again in a few minutes."
}
],
"object_created": "2023-11-07T05:31:56Z",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"object_owner": "pp@gmail.com",
"object_updated": "2023-11-07T05:31:56Z",
"parcels": [
{
"mass_unit": "lb",
"weight": "1",
"distance_unit": "in",
"height": "1",
"length": "1",
"width": "1",
"extra": {
"COD": {
"amount": "5.5",
"currency": "USD",
"payment_method": "CASH"
},
"insurance": {
"amount": "5.5",
"content": "Laptop",
"currency": "USD",
"provider": "UPS"
},
"reference_1": "<string>",
"reference_2": "<string>"
},
"metadata": "Customer ID 123456",
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"object_owner": "shippotle@shippo.com",
"object_state": "VALID",
"object_updated": "2014-07-09T02:19:13.174Z",
"template": "FedEx_Box_10kg",
"test": true
}
],
"rates": [
{
"amount": "5.5",
"amount_local": "5.5",
"currency": "USD",
"currency_local": "USD",
"attributes": [
"BESTVALUE"
],
"carrier_account": "078870331023437cb917f5187429b093",
"object_created": "2023-11-07T05:31:56Z",
"object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
"object_owner": "pp@gmail.com",
"provider": "USPS",
"servicelevel": {
"name": "Priority Mail Express",
"terms": "<string>",
"token": "usps_priority_express",
"extended_token": "<string>",
"parent_servicelevel": {
"name": "Priority Mail Express",
"terms": "<string>",
"token": "usps_priority_express",
"extended_token": "<string>"
}
},
"shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
"arrives_by": "08:30:00",
"duration_terms": "Delivery in 1 to 3 business days",
"estimated_days": 2,
"included_insurance_price": "1.05",
"messages": [
{
"source": "UPS",
"code": "carrier_timeout",
"text": "UPS API did not respond. Please try again in a few minutes."
}
],
"provider_image_75": "https://cdn2.goshippo.com/providers/75/USPS.png",
"provider_image_200": "https://cdn2.goshippo.com/providers/200/USPS.png",
"test": true,
"zone": "1"
}
],
"status": "QUEUED",
"extra": {
"accounts_receivable_customer_account": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"alcohol": {
"contains_alcohol": true,
"recipient_type": "licensee"
},
"ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
"appropriation_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"authority_to_leave": true,
"bill_of_lading_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"billing": {
"account": "<string>",
"country": "<string>",
"participation_code": "<string>",
"type": "SENDER",
"zip": "<string>"
},
"bypass_address_validation": true,
"carbon_neutral": true,
"carrier_hub_id": "<string>",
"carrier_hub_travel_time": 123,
"COD": {
"amount": "5.5",
"currency": "USD",
"payment_method": "CASH"
},
"cod_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"container_type": "<string>",
"critical_pull_time": "<string>",
"customer_branch": "<string>",
"customer_reference": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 1
},
"dangerous_goods": {
"contains": true,
"biological_material": {
"contains": true
},
"lithium_batteries": {
"contains": true
}
},
"dangerous_goods_code": "01",
"dealer_order_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"delivery_instructions": "<string>",
"dept_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 3
},
"dry_ice": {
"contains_dry_ice": true,
"weight": "<string>"
},
"fda_product_code": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"fulfillment_center": "<string>",
"insurance": {
"amount": "5.5",
"content": "<string>",
"currency": "USD",
"provider": "FEDEX"
},
"invoice_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 2
},
"is_return": true,
"lasership_attrs": [
"TwoPersonDelivery"
],
"lasership_declared_value": "<string>",
"manifest_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"model_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"part_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"po_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 2
},
"preferred_delivery_timeframe": "10001200",
"premium": true,
"production_code": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"purchase_request_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"qr_code_requested": true,
"reference_1": "<string>",
"reference_2": "<string>",
"request_retail_rates": true,
"return_service_type": "PRINT_AND_MAIL",
"rma_number": {
"prefix": "<string>",
"value": "<string>",
"ref_sort": 1
},
"saturday_delivery": true,
"salesperson_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"serial_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"signature_confirmation": "STANDARD",
"store_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"transaction_reference_number": {
"prefix": "ABC",
"value": "value",
"ref_sort": 1
},
"usmca_eligible": true
},
"shipment_date": "2021-03-22T12:00:00Z",
"address_return": {
"country": "US",
"name": "Shwan Ippotle",
"company": "Shippo",
"street1": "215 Clayton St.",
"street2": "<string>",
"street3": "",
"street_no": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"phone": "+1 555 341 9393",
"email": "shippotle@shippo.com",
"is_residential": true,
"metadata": "Customer ID 123456",
"is_complete": true,
"latitude": 123,
"longitude": 123,
"object_created": "2014-07-09T02:19:13.174Z",
"object_id": "d799c2679e644279b59fe661ac8fa488",
"object_owner": "shippotle@shippo.com",
"object_updated": "2014-07-09T02:19:13.174Z",
"validation_results": {
"is_valid": false,
"messages": [
{
"code": "Unknown Street",
"source": "Shippo Address Validator",
"text": "City, State and ZIP Code are valid, but street address is not a match.",
"type": "address_warning"
}
]
},
"test": false
},
"customs_declaration": {
"certify": true,
"certify_signer": "Shawn Ippotle",
"contents_type": "MERCHANDISE",
"items": [
"5087f181d1dc4b14b73fdbf636498886"
],
"non_delivery_option": "RETURN",
"aes_itn": "<string>",
"b13a_filing_option": "FILED_ELECTRONICALLY",
"b13a_number": "<string>",
"certificate": "<string>",
"commercial_invoice": true,
"contents_explanation": "T-Shirt purchase",
"disclaimer": "<string>",
"duties_payor": {
"account": "2323434543",
"type": "THIRD_PARTY",
"address": {
"name": "Patrick Kavanagh",
"zip": "80331",
"country": "DE"
}
},
"exporter_identification": {
"eori_number": "PL123456790ABCDE",
"tax_id": {
"number": "123456789",
"type": "EIN"
}
},
"exporter_reference": "<string>",
"importer_reference": "<string>",
"is_vat_collected": true,
"invoice": "#123123",
"license": "<string>",
"metadata": "Order ID #123123",
"notes": "<string>",
"address_importer": "257ba08436604d2aaf069caafe7acb2a",
"eel_pfc": "NOEEI_30_37_a",
"incoterm": "DDP",
"invoiced_charges": {
"currency": "<string>",
"total_shipping": "<string>",
"total_taxes": "<string>",
"total_duties": "<string>",
"other_fees": "<string>"
},
"object_created": "2014-07-17T01:01:08.306Z",
"object_id": "e2197a54da9d470480f4f8796cc419cb",
"object_owner": "shippotle@shippo.com",
"object_state": "VALID",
"object_updated": "2014-07-17T01:01:08.306Z",
"test": true
},
"test": true
}
]
}Authorizations
Authorization
string
header
default:ShippoToken shippo_test_d41a6f04796998570c521a50828eae8e3cccf0eb
required
API key authentication using the ShippoToken scheme. Format: Authorization: ShippoToken <API_TOKEN> Example: Authorization: ShippoToken shippo_live_abc123
Headers
Optional string used to pick a non-default API version to use. See our API version guide.
Example:
"2018-02-08"
Query Parameters
The page token for paginated results
The page number you want to select
The number of results to return per page (max 100)
Required range:
x <= 100Object(s) created greater than a provided date and time.
Object(s) created greater than or equal to a provided date and time.
Object(s) created lesser than a provided date and time.
Object(s) created lesser than or equal to a provided date and time.
Was this page helpful?
⌘I