Ship to international customers

Meet Sarah

Sarah owns a guitar distribution website, 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 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.

Create address request

curl --location 'https://api.goshippo.com/addresses/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--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"
}'

Create address response

{
    "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. Sarah uses this example to create hers.

Create customs declaration request

curl --location 'https://api.goshippo.com/customs/declarations/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--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"
  }]
}'

Create customs declaration response

{
    "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 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.

Create shipment request

curl --location 'https://api.goshippo.com/shipments/' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--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
}'

Create shipment request response

{
    "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.

Purchase label request

curl --location --request POST 'https://api.goshippo.com/transactions' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
  "rate": "78ac2f9710a543a3836cf985be8fa304",
  "async": false,
  "label_file_type": "PDF"
}'

Overview

Get started

AI & agents

Guides

Concepts