> ## Documentation Index
> Fetch the complete documentation index at: https://docs.goshippo.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.goshippo.com/feedback
```json
{
"path": "/docs/stories/intl_rating_guide",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Ship to international customers
> Follow a step-by-step guide to ship internationally with the Shippo API, including customs declarations and label purchase.
**Meet Sarah**
Sarah owns a guitar distribution website, **[www.wesellguitars.net](http://www.wesellguitars.net)**. They have been steadily growing for the past eight years. Until now, Sarah has focused on the US market but lately has been getting requests from Europe to start selling there too. She wants to expand her business and sees this as a great opportunity.
To begin, she wants to start small and learn. She’s going to start shipping guitar pedals to the UK.
To start, Sarah [creates an address object](/api-reference/addresses/create-a-new-address) for her “for address”. For international shipping, it is essential the address object for both sender and recipient contains a phone number.
The response includes the `object_id` of her premises address that can be reused throughout her application. If she ever changes her premises, it’s easy for her to update this information in a single location rather than updating in a number of different places in her application.
```shell Create address request theme={null}
curl --location 'https://api.goshippo.com/addresses/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data-raw '{
"name": "Sarah",
"company":"We Sell Guitars",
"street1": "215 Clayton St.",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"country": "US",
"phone": "+1 555 341 9393",
"email": "sarah@wesellguitars.net",
"is_residential": "False",
"metadata":"We Sell Guitars HQ"
}'
```
```json Create address response theme={null}
{
"object_created": "2023-07-26T12:14:05.145Z",
"object_updated": "2023-07-26T12:14:05.155Z",
"object_id": "9d4bb72a14fe42c19e63a563c3a7abd7",
"is_complete": true,
"validation_results": {},
"object_owner": "sarah@wesellguitars.net",
"name": "Sarah",
"company": "We Sell Guitars",
"street_no": "",
"street1": "215 Clayton St.",
"street2": "",
"street3": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"country": "US",
"longitude": null,
"latitude": null,
"phone": "0015553419393",
"email": "sarah@wesellguitars.net",
"is_residential": false,
"metadata": "We Sell Guitars HQ",
"test": true
}
```
For international shipments, you must include a [customs declaration](/docs/International_Shipping/InternationalShipping#create-a-customs-declaration-and-customs-items). Sarah uses this example to create hers.
```shell Create customs declaration request theme={null}
curl --location 'https://api.goshippo.com/customs/declarations/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data '{
"contents_type": "MERCHANDISE",
"non_delivery_option": "RETURN",
"certify": true,
"certify_signer": "Tom Marks",
"incoterm": "DDP",
"items": [{
"description": "Guitar Pedal",
"quantity": 1,
"net_weight": "5",
"mass_unit": "lb",
"value_amount": "200",
"value_currency": "USD",
"tariff_number": "",
"origin_country": "US"
}]
}'
```
```json Create customs declaration response theme={null}
{
"object_created": "2023-07-26T12:20:27.408Z",
"object_updated": "2023-07-26T12:20:27.408Z",
"object_id": "3793642fe422479aab94e446ba9d648f",
"object_owner": "sarah@wesellguitars.net",
"object_state": "VALID",
"address_importer": null,
"certify_signer": "Tom Marks",
"certify": true,
"items": [
"29608b4814d44f4cbb42b0f28223a660"
],
"non_delivery_option": "RETURN",
"contents_type": "MERCHANDISE",
"contents_explanation": "",
"exporter_reference": "",
"importer_reference": "",
"invoice": "",
"commercial_invoice": false,
"license": "",
"certificate": "",
"notes": "",
"eel_pfc": "",
"aes_itn": "",
"disclaimer": "",
"incoterm": "DDP",
"metadata": "",
"test": true,
"duties_payor": null,
"b13a_filing_option": "",
"b13a_number": "",
"invoiced_charges": null,
"exporter_identification": null,
"is_vat_collected": false
}
```
Creating an international shipment is the same as creating a [domestic shipment](/docs/Guides_general/generate_shipping_label#create-a-shipment-object) with the addition of a customs declaration.
Sarah wants to ship with confidence and wants her international customers to be confident about their purchase so she’s added insurance to her shipments too.
```shell Create shipment request theme={null}
curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data-raw '{
"address_from": "9d4bb72a14fe42c19e63a563c3a7abd7",
"address_to": {
"name": "Tom Marks",
"street1": "159 Broadhurst Gardens",
"city": "London",
"zip": "NW6 3AU",
"country": "GB",
"phone": "4159876543",
"email": "tommarks@gmmail.com"
},
"parcels":{
"weight": "5",
"length": "10",
"width": "5",
"height": "4",
"distance_unit": "in",
"mass_unit": "lb"
},
"customs_declaration": "3793642fe422479aab94e446ba9d648f",
"extra.insurance": {"amount": "200", "currency": "USD", "content": "guitar pedal" },
"async": false
}'
```
```json Create shipment request response theme={null}
{
"carrier_accounts": [],
"object_created": "2023-07-26T12:36:05.526Z",
"object_updated": "2023-07-26T12:36:07.279Z",
"object_id": "d0feffbc471f4d75b8be276739a79839",
"object_owner": "sarah@wesellguitars.net",
"status": "SUCCESS",
"address_from": {
"object_id": "9d4bb72a14fe42c19e63a563c3a7abd7",
"is_complete": true,
"name": "Sarah",
"company": "We Sell Guitars",
"street_no": "",
"street1": "215 Clayton St.",
"validation_results": {},
"street2": "",
"street3": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"country": "US",
"phone": "0015553419393",
"email": "sarah@wesellguitars.net",
"is_residential": false,
"test": true
},
"address_to": {
"object_id": "39e1c6ddd250477788202ce8c7a51dc0",
"is_complete": true,
"name": "Tom Marks",
"company": "",
"street_no": "",
"street1": "159 Broadhurst Gardens",
"validation_results": {},
"street2": "",
"street3": "",
"city": "London",
"state": "",
"zip": "NW6 3AU",
"country": "GB",
"phone": "4159876543",
"email": "tommarks@gmmail.com",
"is_residential": null,
"test": true
},
"parcels": [
{
"object_state": "VALID",
"object_created": "2023-07-26T12:36:05.500Z",
"object_updated": "2023-07-26T12:36:05.532Z",
"object_id": "f2602a1e13d34250b9e05267cd0efa87",
"object_owner": "sarah@wesellguitars.net",
"template": null,
"extra": {},
"length": "10.0000",
"width": "5.0000",
"height": "4.0000",
"distance_unit": "in",
"weight": "5.0000",
"mass_unit": "lb",
"value_amount": null,
"value_currency": null,
"metadata": "",
"line_items": [],
"test": true
}
],
"shipment_date": "2023-07-26T12:36:05.645Z",
"address_return": {
"object_id": "9d4bb72a14fe42c19e63a563c3a7abd7",
"is_complete": true,
"name": "Sarah",
"company": "We Sell Guitars",
"street_no": "",
"street1": "215 Clayton St.",
"validation_results": {},
"street2": "",
"street3": "",
"city": "San Francisco",
"state": "CA",
"zip": "94117",
"country": "US",
"phone": "0015553419393",
"email": "sarah@wesellguitars.net",
"is_residential": false,
"test": true
},
"alternate_address_to": null,
"customs_declaration": {
"object_created": "2023-07-26T12:20:27.408Z",
"object_updated": "2023-07-26T12:36:05.515Z",
"object_id": "3793642fe422479aab94e446ba9d648f",
"object_owner": "sarah@wesellguitars.net",
"object_state": "VALID",
"address_importer": null,
"certify_signer": "Tom Marks",
"certify": true,
"items": [
"29608b4814d44f4cbb42b0f28223a660"
],
"non_delivery_option": "RETURN",
"contents_type": "MERCHANDISE",
"contents_explanation": "",
"exporter_reference": "",
"importer_reference": "",
"invoice": "",
"commercial_invoice": false,
"license": "",
"certificate": "",
"notes": "",
"eel_pfc": "",
"aes_itn": "",
"disclaimer": "",
"incoterm": "DDP",
"metadata": "",
"test": true,
"duties_payor": null,
"b13a_filing_option": "",
"b13a_number": "",
"invoiced_charges": null,
"exporter_identification": null,
"is_vat_collected": false
},
"extra": {},
"rates": [
{
"object_created": "2023-07-26T12:36:05.729Z",
"object_id": "65d6e49881864e63994519909a607d2d",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [],
"amount": "76.97",
"currency": "USD",
"amount_local": "59.66",
"currency_local": "GBP",
"provider": "DHL Express",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/DHL.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/DHL.png",
"servicelevel": {
"name": "Worldwide",
"token": "dhl_express_worldwide",
"terms": "",
"extended_token": "dhl_express_worldwide",
"parent_servicelevel": null
},
"estimated_days": 2,
"arrives_by": "23:59:00",
"duration_terms": "",
"messages": [],
"carrier_account": "50fb8af2e7a849b89db4fc02fa207f01",
"test": true,
"zone": "C",
"included_insurance_price": null
},
{
"object_created": "2023-07-26T12:36:06.281Z",
"object_id": "da6ff1989fa74b0aa086118a3873c375",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [
"FASTEST"
],
"amount": "97.46",
"currency": "USD",
"amount_local": "75.55",
"currency_local": "GBP",
"provider": "UPS",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
"servicelevel": {
"name": "Worldwide Express Plus®",
"token": "ups_express_plus_worldwide_eu",
"terms": "",
"extended_token": "ups_express_plus_worldwide_eu",
"parent_servicelevel": {
"extended_token": "ups_express_plus",
"name": "Worldwide Express Plus®",
"terms": "",
"token": "ups_express_plus"
}
},
"estimated_days": 2,
"arrives_by": "09:00:00",
"duration_terms": "",
"messages": [],
"carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
"test": true,
"zone": null,
"included_insurance_price": null
},
{
"object_created": "2023-07-26T12:36:06.281Z",
"object_id": "792f8dddee0149e48c7a8d06fbaf6fa2",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [],
"amount": "57.86",
"currency": "USD",
"amount_local": "44.85",
"currency_local": "GBP",
"provider": "UPS",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
"servicelevel": {
"name": "Express®",
"token": "ups_express",
"terms": "",
"extended_token": "ups_express_eu",
"parent_servicelevel": {
"extended_token": "ups_express_worldwide",
"name": "Worldwide Express®",
"terms": "",
"token": "ups_express"
}
},
"estimated_days": 2,
"arrives_by": null,
"duration_terms": "Next day delivery by 10:30 a.m. or 12:00 noon.",
"messages": [],
"carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
"test": true,
"zone": null,
"included_insurance_price": null
},
{
"object_created": "2023-07-26T12:36:06.281Z",
"object_id": "5d3df0b7638e413b8d8061bbf6bd0a50",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [
"BESTVALUE"
],
"amount": "53.90",
"currency": "USD",
"amount_local": "41.78",
"currency_local": "GBP",
"provider": "UPS",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
"servicelevel": {
"name": "Saver®",
"token": "ups_saver",
"terms": "",
"extended_token": "ups_saver_eu",
"parent_servicelevel": {
"extended_token": "ups_saver",
"name": "Saver®",
"terms": "",
"token": "ups_saver"
}
},
"estimated_days": 2,
"arrives_by": null,
"duration_terms": "Delivery usually in 1-3 business days.",
"messages": [],
"carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
"test": true,
"zone": null,
"included_insurance_price": null
},
{
"object_created": "2023-07-26T12:36:06.281Z",
"object_id": "833c28c75ffb4dfcaed15324578dad69",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [
"CHEAPEST"
],
"amount": "48.18",
"currency": "USD",
"amount_local": "37.35",
"currency_local": "GBP",
"provider": "UPS",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/UPS.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/UPS.png",
"servicelevel": {
"name": "Expedited®",
"token": "ups_expedited",
"terms": "",
"extended_token": "ups_expedited_eu",
"parent_servicelevel": {
"extended_token": "ups_expedited_worldwide",
"name": "Worldwide Expedited®",
"terms": "",
"token": "ups_expedited"
}
},
"estimated_days": 4,
"arrives_by": null,
"duration_terms": "Delivery time usually 2-5 business days.",
"messages": [],
"carrier_account": "f1f8b350f37c4147a592ac6877743ae4",
"test": true,
"zone": null,
"included_insurance_price": null
},
{
"object_created": "2023-07-26T12:36:07.261Z",
"object_id": "99913f5c1fbe4091b84253ac38872843",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [],
"amount": "80.83",
"currency": "USD",
"amount_local": "62.65",
"currency_local": "GBP",
"provider": "USPS",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/USPS.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/USPS.png",
"servicelevel": {
"name": "Priority Mail International",
"token": "usps_priority_mail_international",
"terms": "",
"extended_token": "usps_priority_mail_international",
"parent_servicelevel": null
},
"estimated_days": 8,
"arrives_by": null,
"duration_terms": "Delivery in 6 to 10 business days.",
"messages": [],
"carrier_account": "b19e750708384303ac19ca693fe037ce",
"test": true,
"zone": "20",
"included_insurance_price": null
},
{
"object_created": "2023-07-26T12:36:07.261Z",
"object_id": "81748d1fa1ec4f59b6dd33f735d40e26",
"object_owner": "sarah@wesellguitars.net",
"shipment": "d0feffbc471f4d75b8be276739a79839",
"attributes": [],
"amount": "92.90",
"currency": "USD",
"amount_local": "72.00",
"currency_local": "GBP",
"provider": "USPS",
"provider_image_75": "https://shippo-static-v2.s3.amazonaws.com/providers/75/USPS.png",
"provider_image_200": "https://shippo-static-v2.s3.amazonaws.com/providers/200/USPS.png",
"servicelevel": {
"name": "Priority Mail Express International",
"token": "usps_priority_mail_express_international",
"terms": "",
"extended_token": "usps_priority_mail_express_international",
"parent_servicelevel": null
},
"estimated_days": 4,
"arrives_by": null,
"duration_terms": "Delivery in 3 to 5 business days.",
"messages": [],
"carrier_account": "b19e750708384303ac19ca693fe037ce",
"test": true,
"zone": "20",
"included_insurance_price": null
}
],
"messages": [
{
"source": "ShippoCommon",
"code": "shipment_date_not_eligibl",
"text": "Shipment to or from countries other than the US are not allowed"
},
{
"source": "UPS",
"code": "113005",
"text": "RatedShipmentAlert: The selected service may not guarantee early AM arrival to the requested location."
},
{
"source": "UPS",
"code": "112239",
"text": "RatedShipmentAlert: International movement is not in scope"
},
{
"source": "UPS",
"code": "110971",
"text": "RatedShipmentAlert: Your invoice may vary from the displayed reference rates"
}
],
"metadata": "",
"test": true,
"order": null
}
```
Sarah then uses her preferred Rate to [purchase the label](/docs/Guides_general/generate_shipping_label#create-a-transaction-object).
```shell Purchase label request theme={null}
curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken ' \
--header 'Content-Type: application/json' \
--data-raw '{
"rate": "78ac2f9710a543a3836cf985be8fa304",
"async": false,
"label_file_type": "PDF"
}'
```