Skip to main content
The second step is to create a shipment. The shipment includes all the details about the item you are shipping including
  • the “from” and “to” addresses
  • the parcel details
  • extra parameters
  • customs declaration, that are required for international shipments (see Request Example below)
Creating a shipment automatically generates a list of shipping rates that you can use to select the best shipping option for you.

​
HTTP Method

POST

​
URL

https://api.goshippo.com/shipments/

​
Request Payload

ParameterDescription
address_from*Refer to the Address object
address_to*Refer to the Address object
parcels*Refer to the Parcel object
extraShipments Extras
carrier_accountsAn array of object_ids of the carrier account objects to be used for getting shipping rates for this shipment. This carrier account object_id is available when an account is created. See carrier account response sample. 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 active field set to true
asyncIf set to false in the request, this will be populated with all available rates in the response. Otherwise, rates will be created asynchronously and this array will initially be empty
Note: Parameters with an * are mandatory

​
Objects

​
Address

ParameterDescription
name*First and Last name of the addressee
company*Company Name
street1*First street line, 35 character limit. Usually street number and street name
street_noStreet number of the addressed building. This field can be included in street1
street2Second street line, 35 character limit
city*Name of a city
zip*Postal code of an address
state*State/Province values are required for shipments from/to the US.
country*ISO 2 country code
phonePhone number of the addressee
emailE-mail address of the contact person, RFC3696/5321-compliant

​
Parcel

ParameterDescription
length*Length of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted
width*Width of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted
height*Height of the Parcel. Up to six digits in front and four digits after the decimal separator are accepted
distance_unit*“cm”, “in”, “ft”, “mm”, “m”, “yd”
weight*Weight of the parcel. Up to six digits in front and four digits after the decimal separator are accepted
mass_unit*“g”, “oz”, “lb”, “kg”

​
Response Code

201

​
Examples

​
Request Example

Note(Shipments to Northern Ireland require Customs Declaration & Items object)
cURL
curl --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
    "async": false,
    "object_purpose": "PURCHASE",
    "carrier_accounts": ["aa79df9091b44e03a5de1538585fdd88"],
    "address_from": {
        "object_purpose": "PURCHASE",
        "name": "London Sender",
        "street1": "10 Downing St",
        "city": "London",
        "state": "",
        "zip": "SW1A 2AA",
        "country": "GB",
        "phone": "+44 20 7925 0918",
        "email": "sender@example.com",
        "company": "London Logistics"
    },
    "address_to": {
        "object_purpose": "PURCHASE",
        "name": "Northern Ireland Recipient",
        "street1": "123 Causeway Road",
        "city": "Bushmills",
        "state": "County Antrim",
        "zip": "BT57 8SU",
        "country": "GB",
        "phone": "+44 28 2073 0918",
        "email": "recipient.ni@example.com"
    },
    "customs_declaration": {
        "contents_type": "MERCHANDISE",
        "non_delivery_option": "RETURN",
        "certify": true,
        "certify_signer": "Saurabh Sharan",
        "incoterm": "DDU",
        "items": [
            {
                "description": "T-shirt",
                "quantity": 10,
                "net_weight": "2",
                "mass_unit": "lb",
                "value_amount": "200",
                "value_currency": "USD",
                "tariff_number": "1",
                "sku_code": "TS-WHT-MD",
                "origin_country": "GB"
            }
        ]
    },
    "parcels": {
        "length": 5,
        "width": 5,
        "height": 5,
        "distance_unit": "in",
        "weight": 2,
        "mass_unit": "lb"
    }
}'

​
Response Sample

{
    "object_id": "ecfa8357e93f40b4a5b247a4794208a6",
    "object_created": "2025-08-05T05:11:50.747Z",
    "object_updated": "2025-08-05T05:11:51.633Z",
    "object_owner": "expn-prod-test@goshippo.com",
    "test": false,
    "metadata": "",
    "messages": [],
    "extra": {},
    "order": null,
    "carrier_accounts": [
        "*****"
    ],
    "address_from": {
        "name": "London Sender",
        "street1": "10 Downing St",
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "SW1A 2AA",
        "country": "GB",
        "street_no": "",
        "phone": "00442079250918",
        "email": "sender@example.com",
        "company": "London Logistics",
        "is_residential": null,
        "test": false,
        "object_id": "c81c84d3206a42138378a28bc6a37c21",
        "is_complete": true,
        "validation_results": {}
    },
    "address_to": {
        "name": "Northern Ireland Recipient",
        "street1": "123 Causeway Road",
        "street2": "",
        "street3": "",
        "city": "Bushmills",
        "state": "County Antrim",
        "zip": "BT57 8SU",
        "country": "GB",
        "street_no": "",
        "phone": "00442820730918",
        "email": "recipient.ni@example.com",
        "company": "",
        "is_residential": null,
        "test": false,
        "object_id": "9523b3754f504c73810eb3ec6520ee79",
        "is_complete": true,
        "validation_results": {}
    },
    "parcels": [
        {
            "object_owner": "expn-prod-test@goshippo.com",
            "object_state": "VALID",
            "mass_unit": "lb",
            "template": null,
            "extra": {},
            "metadata": "",
            "test": false,
            "object_id": "76bba84bd1824a9fa1b57f1d4d27ef8e",
            "object_created": "2025-08-05T05:11:50.747Z",
            "object_updated": "2025-08-05T05:11:50.747Z",
            "length": "5.0000",
            "width": "5.0000",
            "height": "5.0000",
            "distance_unit": "in",
            "weight": "2.0000",
            "line_items": []
        }
    ],
    "status": "SUCCESS",
    "shipment_date": "2025-08-05T05:11:50.747Z",
    "address_return": {
        "name": "London Sender",
        "street1": "10 Downing St",
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "SW1A 2AA",
        "country": "GB",
        "street_no": "",
        "phone": "00442079250918",
        "email": "sender@example.com",
        "company": "London Logistics",
        "is_residential": null,
        "test": false,
        "object_id": "c81c84d3206a42138378a28bc6a37c21",
        "is_complete": true,
        "validation_results": {}
    },
    "rates": [
        {
            "object_id": "32444e5afe5c4d5fa44de02e4b56870d",
            "object_created": "2025-08-05T05:11:51.609Z",
            "object_owner": "expn-prod-test@goshippo.com",
            "shipment": "ecfa8357e93f40b4a5b247a4794208a6",
            "amount": "2.96",
            "currency": "GBP",
            "amount_local": "2.96",
            "currency_local": "GBP",
            "attributes": [
                "FASTEST"
            ],
            "provider": "Royal Mail SF",
            "provider_image_75": "https://shippo-static.s3.amazonaws.com/providers/75/royal_mail_sf.png",
            "provider_image_200": "https://shippo-static.s3.amazonaws.com/providers/200/royal_mail_sf.png",
            "arrives_by": null,
            "duration_terms": "Two business days.",
            "messages": [],
            "carrier_account": "aa79df9091b44e03a5de1538585fdd88",
            "zone": null,
            "test": false,
            "servicelevel": {
                "name": "Tracked 48 for Post Office Drop",
                "token": "royal_mail_sf_tracked_48_for_post_office_drop",
                "terms": "{\"base_price\": 2.76, \"vat\": 0.00, \"dropoff_surcharge\": 0, \"currency\": \"GBP\", \"total_price\": 2.76}",
                "extended_token": "royal_mail_sf_tracked_48_for_post_office_drop",
                "display_name": null,
                "parent_servicelevel": null
            },
            "estimated_days": 2,
            "included_insurance_price": null
        }
    ],
    "alternate_address_to": null,
    "customs_declaration": {
        "object_owner": "expn-prod-test@goshippo.com",
        "object_state": "VALID",
        "certify": true,
        "certify_signer": "Saurabh Sharan",
        "non_delivery_option": "RETURN",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "aes_itn": "",
        "incoterm": "DDU",
        "eel_pfc": "",
        "b13a_filing_option": "",
        "b13a_number": "",
        "disclaimer": "",
        "notes": "",
        "metadata": "",
        "test": false,
        "is_vat_collected": null,
        "object_id": "4ab606eef0f74c479d4df6e47963212b",
        "object_created": "2025-08-05T05:11:50.747Z",
        "object_updated": "2025-08-05T05:11:50.747Z",
        "items": [
            "e3a0bcbb45044228b127d7efa3ee5d2a"
        ],
        "invoiced_charges": null,
        "address_importer": null,
        "duties_payor": null,
        "exporter_identification": null
    }
}
Once you have created your shipment, proceed to Step 3: Purchase label.