First-time users and those looking for specific integration tutorials,
see our full API documentation and guides.
For example, the /addresses/
resource is reachable at https://api.goshippo.com/addresses/
.
In order to authenticate properly, please put Authorization: ShippoToken <token>
in your header. You can find your token on the
Shippo API settings page.
For more information about authentication and test mode, please visit our Authentication guide.
The API is available via Secure Socket Layer (SSL) only. All requests to the Shippo API must use TLS version 1.2 or higher.
Response data also formatted as JSON object. You can specify how many results per page are to be returned. For instance,
/rates/?results=25
will return up to 25 results.
Only the Carrier Accounts object can be updated via PUT requests. All other objects such as Addresses, Parcels, Shipments, Rates, Transactions, Refunds, Customs Items, and Customs Declarations are disposable. This means that once you have created an object, you cannot change it. Instead, create a new one with the desired values.
This reference guide supports the Shippo API version: 2018-02-08
.
To see reference guides for older API versions, see our legacy reference guide. For more information about Shippo API versions, see our API versions guide.
Addresses are the locations a parcel is being shipped from and to. They represent company and residential places. Among other things, you can use address objects to create shipments, calculate shipping rates, and purchase shipping labels.
Address represents the address as retrieved from the database
city | string required for purchase |
company | string Company Name |
country required | string Example: |
string E-mail address of the contact person, RFC3696/5321-compliant. | |
is_residential | boolean Indicates whether the address provided is a residential address or not. |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
name | string required for purchase |
phone | string Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. |
state | string required for purchase for some countries |
street1 | string required for purchase |
street2 | string Second street line, 35 character limit. |
street3 | string Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. |
street_no | string Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany. |
zip | string required for purchase |
latitude | number Latitude of address |
longitude | number Longitude of address |
is_complete | boolean Complete addresses contain all required values. |
object_created | string <date-time> Date and time of Address creation. |
object_id | string Unique identifier of the given Address object. This ID is required to create a Shipment object. |
object_owner | string Username of the user who created the Address object. |
object_updated | string <date-time> Date and time of last Address update. Since you cannot update Addresses after they were created, this time stamp reflects the time when the Address was changed by Shippo's systems for the last time, e.g., during the approximation of one or more values. |
object (AddressValidationResults) Object that contains information regarding if an address had been validated or not. Also contains any messages
generated during validation. Children keys are | |
test | boolean Indicates whether the object has been created in test mode. |
{- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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
}
Returns a list of all address objects that have been created in this account.
curl https://api.goshippo.com/addresses/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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
}
]
}
Creates a new address object. You can use address objects to create new shipments, calculate rates, and to create orders.
Address details.
city | string required for purchase |
company | string Company Name |
country required | string Example: |
string E-mail address of the contact person, RFC3696/5321-compliant. | |
is_residential | boolean Indicates whether the address provided is a residential address or not. |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
name | string required for purchase |
phone | string Addresses containing a phone number allow carriers to call the recipient when delivering the Parcel. This increases the probability of delivery and helps to avoid accessorial charges after a Parcel has been shipped. |
state | string required for purchase for some countries |
street1 | string required for purchase |
street2 | string Second street line, 35 character limit. |
street3 | string Third street line, 35 character limit. Only accepted for USPS international shipments, UPS domestic and UPS international shipments. |
street_no | string Street number of the addressed building. This field can be included in street1 for all carriers except for DHL Germany. |
zip | string required for purchase |
latitude | number Latitude of address |
longitude | number Longitude of address |
validate | boolean Set to true to validate Address object. |
{- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "validate": true
}
{- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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
}
Returns an existing address using an object ID.
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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
}
Validates an existing address using an object ID
curl https://api.goshippo.com/addresses/d799c2679e644279b59fe661ac8fa488/validate/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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
}
A parcel is an item you are shipping. The parcel object includes details about its physical make-up of the parcel. It includes dimensions and weight that Shippo uses to calculate rates.
distance_unit required | string (DistanceUnitTemplate) The measure unit used for length, width and height. Required if template is not specified. |
object (ParcelExtra) An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Parcel Extra table below for all available services. | |
height required | string Required if template is not specified |
length required | string Required if template is not specified |
mass_unit required | string (WeightUnit) The unit used for weight. |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
object_created | string <date-time> Date and time of Parcel creation. |
object_id | string Unique identifier of the given Parcel object. This ID is required to create a Shipment object. |
object_owner | string Username of the user who created the Parcel object. |
object_state | string A Parcel will only be valid when all required values have been sent and validated successfully. |
object_updated | string <date-time> Date and time of last Parcel update. Since you cannot update Parcels after they were created, this time stamp reflects the time when the Parcel was changed by Shippo's systems for the last time, e.g., during sorting the dimensions given. |
ParcelTemplateFedEx (string) or ParcelTemplateUPS (string) or ParcelTemplateUSPS (string) or ParcelTemplateDHLeCommerce (string) or ParcelTemplateDPDUK (string) or ParcelTemplateCouriersPlease (string) or ParcelTemplateAramexAustralia (string) (ParcelTemplateEnumSet) If template is passed, | |
test | boolean Indicates whether the object has been created in test mode. |
weight required | string Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted. |
width required | string Required if template is not specified |
{- "distance_unit": "in",
- "extra": {
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "insurance": {
- "amount": "5.5",
- "content": "Laptop",
- "currency": "USD",
- "provider": "UPS"
}
}, - "height": "1",
- "length": "1",
- "mass_unit": "lb",
- "metadata": "string",
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-09T02:19:13.174Z",
- "template": "FedEx_Box_10kg",
- "test": true,
- "weight": "1",
- "width": "1"
}
The following values are supported for the extra
field of the parcel object.
An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Parcel Extra table below for all available services.
object (COD Specify collection on delivery details (UPS, and FedEx only).) Specify collection on delivery details (UPS, and FedEx only). | |
object (ParcelInsurance) ParcelInsurance Specify insurance details |
{- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "insurance": {
- "amount": "5.5",
- "content": "Laptop",
- "currency": "USD",
- "provider": "UPS"
}
}
curl https://api.goshippo.com/parcels/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "distance_unit": "in",
- "extra": {
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "insurance": {
- "amount": "5.5",
- "content": "Laptop",
- "currency": "USD",
- "provider": "UPS"
}
}, - "height": "1",
- "length": "1",
- "mass_unit": "lb",
- "metadata": "string",
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-09T02:19:13.174Z",
- "template": "FedEx_Box_10kg",
- "test": true,
- "weight": "1",
- "width": "1"
}
]
}
Creates a new parcel object.
Parcel details.
distance_unit required | string (DistanceUnitTemplate) The measure unit used for length, width and height. Required if template is not specified. |
object (ParcelExtra) An object holding optional extra services to be requested for each parcel in a multi-piece shipment. See the Parcel Extra table below for all available services. | |
height required | string Required if template is not specified. Height of the parcel. Up to six digits in front and four digits after the decimal separator are accepted. |
length required | string Required if template is not specified. Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted. |
mass_unit required | string (WeightUnit) The unit used for weight. |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
ParcelTemplateFedEx (string) or ParcelTemplateUPS (string) or ParcelTemplateUSPS (string) or ParcelTemplateDHLeCommerce (string) or ParcelTemplateDPDUK (string) or ParcelTemplateCouriersPlease (string) or ParcelTemplateAramexAustralia (string) (ParcelTemplateEnumSet) If template is passed, | |
test | boolean Indicates whether the object has been created in test mode. |
weight required | string Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted. |
width required | string Required if template is not specified. Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted. |
{- "distance_unit": "in",
- "extra": {
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "insurance": {
- "amount": "5.5",
- "content": "Laptop",
- "currency": "USD",
- "provider": "UPS"
}
}, - "height": "1",
- "length": "1",
- "mass_unit": "lb",
- "metadata": "string",
- "template": "FedEx_Box_10kg",
- "test": true,
- "weight": "1",
- "width": "1"
}
{- "distance_unit": "in",
- "extra": {
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "insurance": {
- "amount": "5.5",
- "content": "Laptop",
- "currency": "USD",
- "provider": "UPS"
}
}, - "height": "1",
- "length": "1",
- "mass_unit": "lb",
- "metadata": "string",
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-09T02:19:13.174Z",
- "template": "FedEx_Box_10kg",
- "test": true,
- "weight": "1",
- "width": "1"
}
Returns an existing parcel using an object ID.
curl https://api.goshippo.com/parcels/7df2ecf8b4224763ab7c71fae7ec8274/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "distance_unit": "in",
- "extra": {
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "insurance": {
- "amount": "5.5",
- "content": "Laptop",
- "currency": "USD",
- "provider": "UPS"
}
}, - "height": "1",
- "length": "1",
- "mass_unit": "lb",
- "metadata": "string",
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-09T02:19:13.174Z",
- "template": "FedEx_Box_10kg",
- "test": true,
- "weight": "1",
- "width": "1"
}
A shipment is the act of transporting goods. A shipment object contains to and from addresses, and the parcel details that you are shipping. You can use the shipment object to retrieve shipping rates and purchase a shipping label.
Shipment represents the parcel as retrieved from the database
customs_declaration | string ID of the Customs Declarations object for an international shipment. |
object (ShipmentExtra) An object holding optional extra services to be requested. | |
metadata required | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
shipment_date | string Date the shipment will be tendered to the carrier. Must be in the format |
required | object (AddressFrom) Address object of the sender / seller. Will be returned expanded by default. |
object (AddressReturn) 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). | |
required | object (AddressTo) Address object of the recipient / buyer. Will be returned expanded by default. |
carrier_accounts required | Array of strings 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 |
required | Array of objects An array containing elements of the following schema: |
object_created required | string <date-time> Date and time of Shipment creation. |
object_id required | string Unique identifier of the given Shipment object. |
object_owner required | string Username of the user who created the Shipment object. |
object_updated required | string <date-time> Date and time of last Shipment update. |
required | Array of objects (ParcelTemplate) Array of IDs of the Parcel objects to be shipped. |
required | Array of objects (Rate) An array with all available rates. If |
status required | string
|
test | boolean Indicates whether the object has been created in test mode. |
{- "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
- "extra": {
- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}, - "metadata": "Customer ID 123456",
- "shipment_date": "2021-03-22T12:00:00Z",
- "address_from": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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_return": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "pp@gmail.com",
- "object_updated": "2019-08-24T14:15:22Z",
- "parcels": [
- {
- "distance_unit": "in",
- "height": "1",
- "is_default": true,
- "length": "1",
- "mass_unit": "lb",
- "name": "Oven Box",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "template": "FedEx_Box_10kg",
- "weight": "1",
- "width": "1"
}
], - "rates": [
- {
- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
], - "status": "SUCCESS",
- "test": true
}
The following values are supported for the extra
field of the shipment object.
An object holding optional extra services to be requested.
ancillary_endorsement | any Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only). |
authority_to_leave | boolean Request |
object (Alcohol) Indicates that a shipment contains Alcohol (Fedex and UPS only). | |
object (Billing) Specify billing details (UPS, FedEx, and DHL Germany only). | |
bypass_address_validation | boolean Bypasses address validation (USPS, UPS, & LaserShip only). |
carbon_neutral | boolean Request carbon offsets by passing true (UPS only). |
carrier_hub_id | string Identifies the carrier injection site. |
carrier_hub_travel_time | integer Travel time in hours from fulfillment center to carrier injection site. |
object (COD Specify collection on delivery details (UPS, and FedEx only).) Specify collection on delivery details (UPS, and FedEx only). | |
container_type | string Specify container type. |
critical_pull_time | string Carrier arrival time to pickup packages from the fulfillment center.
UTC format: |
customer_branch | string Specify customer branch (Lasership only). |
dangerous_goods_code | any Dangerous Goods Code (DHL eCommerce only). See Category Codes |
delivery_instructions | string Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only). |
object (DryIce) Specify that the package contains Dry Ice (FedEx and UPS only). | |
fulfillment_center | string The fulfilment center where the package originates from. |
object (Insurance) Specify amount, content, provider, and currency of shipment insurance (UPS, FedEx and Ontrac only). | |
is_return | boolean This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details. |
lasership_attrs | any Specify Lasership Attributes (Lasership only). Multiple options accepted. |
lasership_declared_value | string Declared value (Lasership only). Defaults to |
preferred_delivery_timeframe | any Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is |
premium | boolean Add premium service to a shipment (DHL Germany international shipments only). |
qr_code_requested | boolean Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only). |
reference_1 | string Optional text to be printed on the shipping label. Up to 50 characters. |
reference_2 | string Optional text to be printed on the shipping label. Up to 50 characters. For DHL eCommerce, this field can be used for billing reference. |
request_retail_rates | boolean Returns retail rates instead of account-based rates (UPS and FedEx only). |
return_service_type | any Request additional return option for return shipments (UPS only). |
saturday_delivery | boolean Marks shipment as to be delivered on a Saturday. |
signature_confirmation | any Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only). |
{- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}
The following values are supported for the extra
field of the shipment object.
An object holding optional extra services to be requested.
ancillary_endorsement | any Specify an ancillary service endorsement to provide the USPS with instructions on how to handle undeliverable-as-addressed pieces (DHL eCommerce only). |
authority_to_leave | boolean Request |
object (Alcohol) Indicates that a shipment contains Alcohol (Fedex and UPS only). | |
object (Billing) Specify billing details (UPS, FedEx, and DHL Germany only). | |
bypass_address_validation | boolean Bypasses address validation (USPS, UPS, & LaserShip only). |
carbon_neutral | boolean Request carbon offsets by passing true (UPS only). |
carrier_hub_id | string Identifies the carrier injection site. |
carrier_hub_travel_time | integer Travel time in hours from fulfillment center to carrier injection site. |
object (COD Specify collection on delivery details (UPS, and FedEx only).) Specify collection on delivery details (UPS, and FedEx only). | |
container_type | string Specify container type. |
critical_pull_time | string Carrier arrival time to pickup packages from the fulfillment center.
UTC format: |
customer_branch | string Specify customer branch (Lasership only). |
dangerous_goods_code | any Dangerous Goods Code (DHL eCommerce only). See Category Codes |
delivery_instructions | string Specify delivery instructions. Up to 500 characters. (FedEx and OnTrac only). |
object (DryIce) Specify that the package contains Dry Ice (FedEx and UPS only). | |
fulfillment_center | string The fulfilment center where the package originates from. |
object (Insurance) Specify amount, content, provider, and currency of shipment insurance (UPS, FedEx and Ontrac only). | |
is_return | boolean This field specifies if it is a scan-based return shipment. See the Create a return shipment section for more details. |
lasership_attrs | any Specify Lasership Attributes (Lasership only). Multiple options accepted. |
lasership_declared_value | string Declared value (Lasership only). Defaults to |
preferred_delivery_timeframe | any Required for DHL Germany Paket Sameday. Designates a desired timeframe for delivery. Format is |
premium | boolean Add premium service to a shipment (DHL Germany international shipments only). |
qr_code_requested | boolean Request a QR code for a given transaction when creating a shipping label (USPS domestic and Evri UK only). |
reference_1 | string Optional text to be printed on the shipping label. Up to 50 characters. |
reference_2 | string Optional text to be printed on the shipping label. Up to 50 characters. For DHL eCommerce, this field can be used for billing reference. |
request_retail_rates | boolean Returns retail rates instead of account-based rates (UPS and FedEx only). |
return_service_type | any Request additional return option for return shipments (UPS only). |
saturday_delivery | boolean Marks shipment as to be delivered on a Saturday. |
signature_confirmation | any Request standard or adult signature confirmation. You can alternatively request Certified Mail (USPS only) or Indirect signature (FedEx only) or Carrier Confirmation (Deutsche Post only). |
{- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}
Returns a list of all shipment objects.
In order to filter results, you must use the below path parameters.
A maximum date range of 90 days is permitted.
Provided dates should be ISO 8601 UTC dates (timezone offsets are currently not supported).
Optional path parameters:
object_created_gt
- object(s) created greater than a provided date time
object_created_gte
- object(s) created greater than or equal to a provided date time
object_created_lt
- object(s) created less than a provided date time
object_created_lte
- 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:
https://api.goshippo.com/shipments/?object_created_gte=2017-01-01T00:00:30&object_created_lt=2017-04-01T00:00:30
curl https://api.goshippo.com/shipments/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
- "extra": {
- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}, - "metadata": "Customer ID 123456",
- "shipment_date": "2021-03-22T12:00:00Z",
- "address_from": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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_return": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "pp@gmail.com",
- "object_updated": "2019-08-24T14:15:22Z",
- "parcels": [
- {
- "distance_unit": "in",
- "height": "1",
- "is_default": true,
- "length": "1",
- "mass_unit": "lb",
- "name": "Oven Box",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "template": "FedEx_Box_10kg",
- "weight": "1",
- "width": "1"
}
], - "rates": [
- {
- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
], - "status": "SUCCESS",
- "test": true
}
]
}
Creates a new shipment object.
Shipment details and contact info.
{- "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
- "extra": {
- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}, - "metadata": "Customer ID 123456",
- "shipment_date": "2021-03-22T12:00:00Z",
- "address_from": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "validate": true
}, - "address_return": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "validate": true
}, - "address_to": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "validate": true
}, - "async": true,
- "parcels": [
- {
- "distance_unit": "in",
- "height": "1",
- "length": "1",
- "mass_unit": "lb",
- "template": "FedEx_Box_10kg",
- "weight": "1",
- "width": "1",
- "metadata": "Customer ID 123456"
}
]
}
{- "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
- "extra": {
- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}, - "metadata": "Customer ID 123456",
- "shipment_date": "2021-03-22T12:00:00Z",
- "address_from": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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_return": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "pp@gmail.com",
- "object_updated": "2019-08-24T14:15:22Z",
- "parcels": [
- {
- "distance_unit": "in",
- "height": "1",
- "is_default": true,
- "length": "1",
- "mass_unit": "lb",
- "name": "Oven Box",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "template": "FedEx_Box_10kg",
- "weight": "1",
- "width": "1"
}
], - "rates": [
- {
- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
], - "status": "SUCCESS",
- "test": true
}
Returns an existing shipment using an object ID
curl https://api.goshippo.com/shipments/7c47d12aa95a4cbb9d90c167cca7bea7 \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "customs_declaration": "adcfdddf8ec64b84ad22772bce3ea37a",
- "extra": {
- "ancillary_endorsement": "FORWARDING_SERVICE_REQUESTED",
- "authority_to_leave": true,
- "alcohol": {
- "contains_alcohol": true,
- "recipient_type": "licensee"
}, - "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": 0,
- "COD": {
- "amount": "5.5",
- "currency": "USD",
- "payment_method": "CASH"
}, - "container_type": "string",
- "critical_pull_time": "string",
- "customer_branch": "string",
- "dangerous_goods_code": "01",
- "delivery_instructions": "string",
- "dry_ice": {
- "contains_dry_ice": true,
- "weight": "string"
}, - "fulfillment_center": "string",
- "insurance": {
- "amount": "5.5",
- "content": "string",
- "currency": "USD",
- "provider": "FEDEX"
}, - "is_return": true,
- "lasership_attrs": "TwoPersonDelivery",
- "lasership_declared_value": "string",
- "preferred_delivery_timeframe": "10001200",
- "premium": true,
- "qr_code_requested": true,
- "reference_1": "string",
- "reference_2": "string",
- "request_retail_rates": true,
- "return_service_type": "PRINT_AND_MAIL",
- "saturday_delivery": true,
- "signature_confirmation": "STANDARD"
}, - "metadata": "Customer ID 123456",
- "shipment_date": "2021-03-22T12:00:00Z",
- "address_from": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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_return": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "string",
- "street3": "",
- "street_no": "",
- "zip": "94117",
- "latitude": 0,
- "longitude": 0,
- "is_complete": true,
- "object_created": "2014-07-09T02:19:13.174Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.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": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "object_owner": "pp@gmail.com",
- "object_updated": "2019-08-24T14:15:22Z",
- "parcels": [
- {
- "distance_unit": "in",
- "height": "1",
- "is_default": true,
- "length": "1",
- "mass_unit": "lb",
- "name": "Oven Box",
- "object_id": "adcfdddf8ec64b84ad22772bce3ea37a",
- "template": "FedEx_Box_10kg",
- "weight": "1",
- "width": "1"
}
], - "rates": [
- {
- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
], - "status": "SUCCESS",
- "test": true
}
A rate is the cost to ship a parcel from a carrier. The rate object details the service level including the cost and transit time.
amount required | string Final Rate price, expressed in the currency used in the sender's country. |
amount_local required | string Final Rate price, expressed in the currency used in the recipient's country. |
arrives_by | object |
attributes required | Array of strings An array containing specific attributes of this Rate in context of the entire shipment.
Attributes can be assigned |
carrier_account required | string Object ID of the carrier account that has been used to retrieve the rate. |
currency required | string Currency used in the sender's country, refers to |
currency_local required | string Currency used in the recipient's country, refers to |
duration_terms | string Further clarification of the transit times. Often, this includes notes that the transit time as given in "days" is only an average, not a guaranteed time. |
estimated_days | integer <int64> Estimated transit time (duration) in days of the Parcel at the given servicelevel. Please note that this is not binding, but only an average value as given by the provider. Shippo is not able to guarantee any transit times. |
included_insurance_price | number Cost to the user to insure the Rate for the requested amount of coverage, if insurance coverage was requested.
Expressed in the currency used in the sender's country. Will be null if no insurance coverage was requested, or if insurance is requested from a non-standard insurance provider.
Please note this is price is already included in the |
Array of objects (RateMessage) An array containing elements of the following schema: | |
object_created required | string <date-time> Date and time of Rate creation. |
object_id required | string Unique identifier of the given Rate object. |
object_owner required | string Username of the user who created the rate object. |
provider required | string Carrier offering the rate, e.g., |
provider_image_75 | string URL to the provider logo with max. dimensions of 75*75px. Please refer to the provider's Logo Usage Guidelines before using the logo. |
provider_image_200 | string URL to the provider logo with max. dimensions of 200*200px. Please refer to the provider's Logo Usage Guidelines before using the logo. |
required | object (ServiceLevel) Contains details regarding the service level for the given rate. |
shipment required | string |
test | boolean Indicates whether the object has been created in test mode. |
zone | string The parcel's transit zone token. These tokens can vary depending on the provider. |
{- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
Returns an existing rate using a rate object ID.
curl https://api.goshippo.com/rates/ee81fab0372e419ab52245c8952ccaeb \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
Returns a paginated list of rates associated with a shipment
curl https://api.goshippo.com/shipments/5e40ead7cffe4cc1ad45108696162e42/rates/USD \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
]
}
Returns all available shipping rates for a shipment object.
When you create a new valid shipment object, Shippo automatically calculates all available rates. Depending on your shipment data, 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 where the 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 currency code to the end of the resource URL. The full list of supported currencies along with their codes can be viewed on open exchange rates.
Note: re-requesting the rates with a different currency code will re-queue the shipment (i.e. set the Shipment's status
to QUEUED
) and the converted currency rates will only be available when the Shipment's status
is set to SUCCESS
.
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "amount": "5.5",
- "amount_local": "5.5",
- "arrives_by": { },
- "attributes": [
- "BESTVALUE"
], - "carrier_account": "078870331023437cb917f5187429b093",
- "currency": "USD",
- "currency_local": "USD",
- "duration_terms": "Delivery in 1 to 3 business days",
- "estimated_days": 2,
- "included_insurance_price": "1.05",
- "messages": [
- {
- "code": "string",
- "source": "UPS",
- "text": "RatedShipmentWarning: User Id and Shipper Number combination is not qualified to receive negotiated rates."
}
], - "object_created": "2019-08-24T14:15:22Z",
- "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": "string"
}, - "shipment": "adcfdddf8ec64b84ad22772bce3ea37a",
- "test": true,
- "zone": "1"
}
]
}
A transaction is the purchase of a shipping label from a shipping provider for a specific service. You can print purchased labels and used them to ship a parcel with a carrier, such as USPS or FedEx.
commercial_invoice_url | string A URL pointing to the commercial invoice as a 8.5x11 inch PDF file. A value will only be returned if the Transactions has been processed successfully and if the shipment is international. |
eta | string The estimated time of arrival according to the carrier. |
label_file_type | string (LabelFileType) Print format of the label. If empty, will use the default format set from the Shippo dashboard. |
label_url | string A URL pointing directly to the label in the format you've set in your settings. A value will only be returned if the Transactions has been processed successfully. |
messages | Array of objects An array containing elements of the following schema: |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
object_created | string <date-time> Date and time of Transaction creation. |
object_id | string Unique identifier of the given Transaction object. |
object_owner | string Username of the user who created the Transaction object. |
object_state | string (ObjectState) Indicates the validity of the enclosing object |
object_updated | string <date-time> Date and time of last Transaction update. |
qr_code_url | string A URL pointing directly to the QR code in PNG format. A value will only be returned if requested using qr_code_requested flag and the carrier provides such an option. |
rate | string ID of the Rate object for which a Label has to be obtained. Please note that only rates that are not older than 7 days can be purchased in order to ensure up-to-date pricing. |
status | string Indicates the status of the Transaction. |
test | boolean Indicates whether the object has been created in test mode. |
tracking_number | string The carrier-specific tracking number that can be used to track the Shipment. A value will only be returned if the Rate is for a trackable Shipment and if the Transactions has been processed successfully. |
tracking_status | string Indicates the high level status of the shipment: |
tracking_url_provider | string A link to track this item on the carrier-provided tracking website. A value will only be returned if tracking is available and the carrier provides such a service. |
{- "commercial_invoice_url": "string",
- "eta": "string",
- "label_file_type": "PDF_4x6",
- "messages": [ ],
- "metadata": "string",
- "object_created": "2019-08-24T14:15:22Z",
- "object_id": "915d94940ea54c3a80cbfa328722f5a1",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2019-08-24T14:15:22Z",
- "rate": "ec9f0d3adc9441449c85d315f0997fd5",
- "status": "SUCCESS",
- "test": true,
- "tracking_number": "9499907123456123456781",
- "tracking_status": "UNKOWN",
- "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}
Returns a list of all transaction objects.
curl https://api.goshippo.com/transactions/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "commercial_invoice_url": "string",
- "eta": "string",
- "label_file_type": "PDF_4x6",
- "messages": [ ],
- "metadata": "string",
- "object_created": "2019-08-24T14:15:22Z",
- "object_id": "915d94940ea54c3a80cbfa328722f5a1",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2019-08-24T14:15:22Z",
- "rate": "ec9f0d3adc9441449c85d315f0997fd5",
- "status": "SUCCESS",
- "test": true,
- "tracking_number": "9499907123456123456781",
- "tracking_status": "UNKOWN",
- "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}
]
}
Creates a new transaction object and purchases the shipping label using a rate object that has previously been created.
OR
Creates a new transaction object and purchases the shipping label instantly using shipment details, an existing carrier account, and an existing service level token.
Examples.
async | boolean |
label_file_type | string (LabelFileType) Print format of the label. If empty, will use the default format set from the Shippo dashboard. |
metadata | string |
rate required | string |
{- "carrier_account": "b741b99f95e841639b54272834bc478c",
- "label_file_type": "PDF",
- "metadata": "Order ID",
- "servicelevel_token": "usps_priority",
- "shipment": {
- "address_from": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "215 Clayton St.",
- "validate": true,
- "zip": 94117
}, - "address_return": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "215 Clayton St.",
- "validate": true,
- "zip": 94117
}, - "address_to": {
- "city": "San Francisco",
- "company": "Shippo",
- "country": "US",
- "email": "shippotle@goshippo.com",
- "is_residential": true,
- "metadata": "Customer ID 123456",
- "name": "Shwan Ippotle",
- "phone": "+1 555 341 9393",
- "state": "CA",
- "street1": "215 Clayton St.",
- "street2": "215 Clayton St.",
- "validate": true,
- "zip": 94117
}, - "parcels": [
- {
- "distance_unit": "in",
- "height": 1,
- "length": 1,
- "mass_unit": "lb",
- "template": "USPS_LargeFlatRateBox",
- "weight": 1,
- "width": 1
}
]
}
}
{- "commercial_invoice_url": "string",
- "eta": "string",
- "label_file_type": "PDF_4x6",
- "messages": [ ],
- "metadata": "string",
- "object_created": "2019-08-24T14:15:22Z",
- "object_id": "915d94940ea54c3a80cbfa328722f5a1",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2019-08-24T14:15:22Z",
- "rate": "ec9f0d3adc9441449c85d315f0997fd5",
- "status": "SUCCESS",
- "test": true,
- "tracking_number": "9499907123456123456781",
- "tracking_status": "UNKOWN",
- "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}
Returns an existing transaction using an object ID.
curl https://api.goshippo.com/transactions/70ae8117ee1749e393f249d5b77c45e0 \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "commercial_invoice_url": "string",
- "eta": "string",
- "label_file_type": "PDF_4x6",
- "messages": [ ],
- "metadata": "string",
- "object_created": "2019-08-24T14:15:22Z",
- "object_id": "915d94940ea54c3a80cbfa328722f5a1",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2019-08-24T14:15:22Z",
- "rate": "ec9f0d3adc9441449c85d315f0997fd5",
- "status": "SUCCESS",
- "test": true,
- "tracking_number": "9499907123456123456781",
- "tracking_status": "UNKOWN",
- "tracking_url_provider": "https://tools.usps.com/go/TrackConfirmAction_input?origTrackNum=9499907123456123456781"
}
Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your international shipments.
description required | string Text description of your item. |
eccn_ear99 | string Export Control Classification Number, required on some exports from the United States. |
mass_unit required | string (WeightUnit) The unit used for weight. |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
net_weight required | string Total weight of this item, i.e. quantity * weight per item. |
origin_country required | string Country of origin of the item. Example: |
quantity required | integer <int64> Quantity of this item in the shipment you send. Must be greater than 0. |
sku_code | string SKU code of the item, which is required by some carriers. |
tariff_number | string The tariff number of the item. |
value_amount required | string Total value of this item, i.e. quantity * value per item. |
value_currency required | string Currency used for value_amount. The official ISO 4217
currency codes are used, e.g. |
object_created | string <date-time> Date and time of object creation. |
object_id | string Unique identifier of the given object. |
object_owner | string Username of the user who created the object. |
object_state | string (ObjectState) Indicates the validity of the enclosing object |
object_updated | string <date-time> Date and time of last object update. |
test | boolean Indicates whether the object has been created in test mode. |
{- "description": "T-Shirt",
- "eccn_ear99": "string",
- "mass_unit": "lb",
- "metadata": "Order ID \"123454\"",
- "net_weight": "5",
- "origin_country": "string",
- "quantity": 20,
- "sku_code": "HM-123",
- "tariff_number": "string",
- "value_amount": "200",
- "value_currency": "USD",
- "object_created": "2014-07-17T00:49:20.631Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-17T00:49:20.631Z",
- "test": true
}
Returns a list all customs items objects.
curl https://api.goshippo.com/customs/items/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "description": "T-Shirt",
- "eccn_ear99": "string",
- "mass_unit": "lb",
- "metadata": "Order ID \"123454\"",
- "net_weight": "5",
- "origin_country": "string",
- "quantity": 20,
- "sku_code": "HM-123",
- "tariff_number": "string",
- "value_amount": "200",
- "value_currency": "USD",
- "object_created": "2014-07-17T00:49:20.631Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-17T00:49:20.631Z",
- "test": true
}
]
}
Creates a new customs item object.
CustomsItem details.
description required | string Text description of your item. |
eccn_ear99 | string Export Control Classification Number, required on some exports from the United States. |
mass_unit required | string (WeightUnit) The unit used for weight. |
metadata | string A string of up to 100 characters that can be filled with any additional information you want to attach to the object. |
net_weight required | string Total weight of this item, i.e. quantity * weight per item. |
origin_country required | string Country of origin of the item. Example: |
quantity required | integer <int64> Quantity of this item in the shipment you send. Must be greater than 0. |
sku_code | string SKU code of the item, which is required by some carriers. |
tariff_number | string The tariff number of the item. |
value_amount required | string Total value of this item, i.e. quantity * value per item. |
value_currency required | string Currency used for value_amount. The official ISO 4217
currency codes are used, e.g. |
{- "description": "T-Shirt",
- "eccn_ear99": "string",
- "mass_unit": "lb",
- "metadata": "Order ID \"123454\"",
- "net_weight": "5",
- "origin_country": "string",
- "quantity": 20,
- "sku_code": "HM-123",
- "tariff_number": "string",
- "value_amount": "200",
- "value_currency": "USD"
}
{- "description": "T-Shirt",
- "eccn_ear99": "string",
- "mass_unit": "lb",
- "metadata": "Order ID \"123454\"",
- "net_weight": "5",
- "origin_country": "string",
- "quantity": 20,
- "sku_code": "HM-123",
- "tariff_number": "string",
- "value_amount": "200",
- "value_currency": "USD",
- "object_created": "2014-07-17T00:49:20.631Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-17T00:49:20.631Z",
- "test": true
}
Returns an existing customs item using an object ID
curl https://api.goshippo.com/customs/items/55358464c7b740aca199b395536981bd \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "description": "T-Shirt",
- "eccn_ear99": "string",
- "mass_unit": "lb",
- "metadata": "Order ID \"123454\"",
- "net_weight": "5",
- "origin_country": "string",
- "quantity": 20,
- "sku_code": "HM-123",
- "tariff_number": "string",
- "value_amount": "200",
- "value_currency": "USD",
- "object_created": "2014-07-17T00:49:20.631Z",
- "object_id": "d799c2679e644279b59fe661ac8fa488",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-17T00:49:20.631Z",
- "test": true
}
Customs declarations are relevant information, including one or multiple customs items, you need to provide for customs clearance for your international shipments.
aes_itn | string required if eel_pfc is |
b13a_filing_option | string B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. |
b13a_number | string must be provided if and only if b13a_filing_option is provided |
certificate | string Certificate reference of the shipment. |
certify required | boolean Expresses that the certify_signer has provided all information of this customs declaration truthfully. |
certify_signer required | string Name of the person who created the customs declaration and is responsible for the validity of all information provided. |
commercial_invoice | string |
contents_explanation | string required if contents_type is |
contents_type required | string Type of goods of the shipment. |
disclaimer | string Disclaimer for the shipment and customs information that have been provided. |
eel_pfc | string EEL / PFC type of the shipment. For most shipments from the US to CA, |
exporter_reference | string Exporter reference of an export shipment. |
importer_reference | string Importer reference of an import shipment. |
is_vat_collected | any Indicates whether the shipment's destination VAT has been collected. May be required for some destinations. |
invoice | string Invoice reference of the shipment. |
object (CustomsInvoicedCharges) Additional invoiced charges to be shown on the Customs Declaration Commercial Invoice. | |
items required | Array of strings Distinct Parcel content items as Customs Items object_ids. |
license | string License reference of the 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. |
non_delivery_option required | string Indicates how the carrier should proceed in case the shipment can't be delivered. |
notes | string Additional notes to be included in the customs declaration. |
object (CustomsExporterIdentification) Additional exporter identification that may be required to ship in certain countries | |
object (CustomsTaxIdentification) Tax identification that may be required to ship in certain countries. Typically used to assess duties on goods that are crossing a border. | |
object_created | string <date-time> Date and time of object creation. |
object_id | string Unique identifier of the given object. |
object_owner | string Username of the user who created the object. |
object_state | string (ObjectState) Indicates the validity of the enclosing object |
object_updated | string <date-time> Date and time of last object update. |
test | boolean Indicates whether the object has been created in test mode. |
{- "aes_itn": "string",
- "b13a_filing_option": "FILED_ELECTRONICALLY",
- "b13a_number": "string",
- "certificate": "string",
- "certify": true,
- "certify_signer": "Shawn Ippotle",
- "commercial_invoice": "string",
- "contents_explanation": "T-Shirt purchase",
- "contents_type": "MERCHANDISE",
- "disclaimer": "string",
- "eel_pfc": "NOEEI_30_37_a",
- "exporter_reference": "string",
- "importer_reference": "string",
- "is_vat_collected": null,
- "invoice": "#123123",
- "invoiced_charges": {
- "currency": "string",
- "total_shipping": "string",
- "total_taxes": "string",
- "total_duties": "string",
- "other_fees": "string"
}, - "items": [
- "5087f181d1dc4b14b73fdbf636498886"
], - "license": "string",
- "metadata": "Order ID #123123",
- "non_delivery_option": "ABANDON",
- "notes": "string",
- "exporter_identification": {
- "eori_number": "PL123456790ABCDE",
- "tax_id": {
- "number": "123456789",
- "type": "EIN"
}
}, - "tax_id": {
- "number": "123456789",
- "type": "EIN"
}, - "object_created": "2014-07-17T01:01:08.306Z",
- "object_id": "e2197a54da9d470480f4f8796cc419cb",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-17T01:01:08.306Z",
- "test": true
}
Returns a a list of all customs declaration objects
curl https://api.goshippo.com/customs/declarations/ \ -H "Authorization: ShippoToken shippo_test_3a47d23c032ca626fce863c48d0f93d63a394396"
{- "next": "baseurl?page=3&results=10",
- "previous": "baseurl?page=1&results=10",
- "results": [
- {
- "aes_itn": "string",
- "b13a_filing_option": "FILED_ELECTRONICALLY",
- "b13a_number": "string",
- "certificate": "string",
- "certify": true,
- "certify_signer": "Shawn Ippotle",
- "commercial_invoice": "string",
- "contents_explanation": "T-Shirt purchase",
- "contents_type": "MERCHANDISE",
- "disclaimer": "string",
- "eel_pfc": "NOEEI_30_37_a",
- "exporter_reference": "string",
- "importer_reference": "string",
- "is_vat_collected": null,
- "invoice": "#123123",
- "invoiced_charges": {
- "currency": "string",
- "total_shipping": "string",
- "total_taxes": "string",
- "total_duties": "string",
- "other_fees": "string"
}, - "items": [
- "5087f181d1dc4b14b73fdbf636498886"
], - "license": "string",
- "metadata": "Order ID #123123",
- "non_delivery_option": "ABANDON",
- "notes": "string",
- "exporter_identification": {
- "eori_number": "PL123456790ABCDE",
- "tax_id": {
- "number": "123456789",
- "type": "EIN"
}
}, - "tax_id": {
- "number": "123456789",
- "type": "EIN"
}, - "object_created": "2014-07-17T01:01:08.306Z",
- "object_id": "e2197a54da9d470480f4f8796cc419cb",
- "object_owner": "shippotle@goshippo.com",
- "object_state": "VALID",
- "object_updated": "2014-07-17T01:01:08.306Z",
- "test": true
}
]
}
Creates a new customs declaration object
CustomsDeclaration details.
aes_itn | string required if eel_pfc is |
b13a_filing_option | string B13A Option details are obtained by filing a B13A Canada Export Declaration via the Canadian Export Reporting System (CERS). More information on reporting commercial exports from Canada. |
b13a_number | string must be provided if and only if b13a_filing_option is provided |
certificate | string Certificate reference of the shipment. |
certify required | boolean Expresses that the certify_signer has provided all information of this customs declaration truthfully. |
certify_signer required | string Name of the person who created the customs declaration and is responsible for the validity of all information provided. |
commercial_invoice | string |
contents_explanation | string required if contents_type is |