Create shipment
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
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
| Parameter | Description |
|---|---|
| address_from* | Refer to the Address object |
| address_to* | Refer to the Address object |
| parcels* | Refer to the Parcel object |
| extra | Shipments Extras |
| carrier_accounts | An 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 |
| async | If 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 mandatoryObjects
Address
| Parameter | Description |
|---|---|
| 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_no | Street number of the addressed building. This field can be included in street1 |
| street2 | Second 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 |
| phone | Phone number of the addressee |
| E-mail address of the contact person, RFC3696/5321-compliant |
Parcel
| Parameter | Description |
|---|---|
| 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 --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken shippo_live_******' \
--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.