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

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	Refer to the Extra object
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 mandatory

Objects

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
email	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”

Extra

Parameter	Description
signature_confirmation	Sets if signature confirmation is required for this shipment. Possible values `true` or `false` for one of such fields: - `signature_confirmation` - `Is_over_21_required`
alcohol	Need to fill if shipment contains alcohol: “alcohol”: “contains_alcohol”: false

Response Code

201

Examples

Request Sample for a shipment

cURL

curl --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken <API_TOKEN>' \
--header 'Content-Type: application/json' \
--data-raw '{
   "address_from": {
       "name": "Richard Smith",
       "company": "Smith & Son",
       "street1": "4638 Demaret Drive",
       "street2": "Carls Men",
       "city": "Agnew",
       "state": "California",
       "zip": "60612",
       "country": "US",
       "phone": "+15187674210",
       "email": "rsmith@shippo.com",
       "is_residential": true,
       "metadata":"Testing purposes"
   },
   "address_to": {
       "name": "John doe",
       "company": "Does Co.",
       "street1": "1009 Independence",
       "street2": "Happy Ford",
       "city": "Capitol Hill",
       "state": "Washington",
       "zip": "30064",
       "country": "US",
       "phone": "+16783034845",
       "email": "rchamberlain@shippo.com",
       "is_residential": true,
       "metadata": "Testing_purposes"
   },
   "parcels": [
       {
           "weight": "49",
           "length": "36",
           "width": "22",
           "height": "22",
           "distance_unit": "in",
           "mass_unit": "lb"
        }
   ],
   "extra": {
       "signature_confirmation": true,
       "alcohol": {
           "contains_alcohol": false
       }
   },
   "carrier_accounts": [
       "{{BETTER_TRUCKS_ACC}}"
   ],
   "async": false
}’

Response Sample for a shipment

  {
   "carrier_accounts": [
       "a00414e75df144b596673979108bbab5"
   ],
   "object_created": "2023-01-26T09:51:40.552Z",
   "object_updated": "2023-01-26T09:51:40.552Z",
   "object_id": "bccddc15133b485d8353a647992abc46",
   "object_owner": "nataliya_eng@shippo.com",
   "status": "SUCCESS",
   "address_from": {
       "object_id": "63970df719d24376b52a65dcae9bdf66",
       "is_complete": true,
       "name": "Richard Smith",
       "company": "Smith & Son",
       "street_no": "",
       "street1": "4638 Demaret Drive",
       "validation_results": {},
       "street2": "Carls Men",
       "street3": "",
       "city": "Agnew",
       "state": "CA",
       "zip": "60612",
       "country": "US",
       "phone": "0015187674210",
       "email": "rsmith@shippo.com",
       "is_residential": true,
       "test": false
   },
   "address_to": {
       "object_id": "4c9dd8a1d13748b2a7770e8e0d004180",
       "is_complete": true,
       "name": "John doe",
       "company": "Does Co.",
       "street_no": "",
       "street1": "1009 Independence",
       "validation_results": {},
       "street2": "Happy Ford",
       "street3": "",
       "city": "Capitol Hill",
       "state": "WA",
       "zip": "30064",
       "country": "US",
       "phone": "0016783034845",
       "email": "rchamberlain@shippo.com",
       "is_residential": true,
       "test": false
   },
   "parcels": [
       {
           "object_state": "VALID",
           "object_created": "2023-01-26T09:51:40.509Z",
           "object_updated": "2023-01-26T09:51:40.597Z",
           "object_id": "203ce92b5a0944ada594bde482f719ff",
           "object_owner": "nataliya_eng@shippo.com",
           "template": null,
           "extra": {},
           "length": "36.0000",
           "width": "22.0000",
           "height": "22.0000",
           "distance_unit": "in",
           "weight": "49.0000",
           "mass_unit": "lb",
           "value_amount": null,
           "value_currency": null,
           "metadata": "",
           "line_items": [],
           "test": false
       }
   ],
   "shipment_date": "2023-01-26T09:51:40.509Z",
   "address_return": {
       "object_id": "63970df719d24376b52a65dcae9bdf66",
       "is_complete": true,
       "name": "Richard Smith",
       "company": "Smith & Son",
       "street_no": "",
       "street1": "4638 Demaret Drive",
       "validation_results": {},
       "street2": "Carls Men",
       "street3": "",
       "city": "Agnew",
       "state": "CA",
       "zip": "60612",
       "country": "US",
       "phone": "0015187674210",
       "email": "rsmith@shippo.com",
       "is_residential": true,
       "test": false
   },
   "alternate_address_to": null,
   "customs_declaration": null,
   "extra": {
       "signature_confirmation": true,
       "alcohol": {
           "contains_alcohol": false
       }
   },
   "rates": [
       {
           "object_created": "2023-01-26T09:51:41.097Z",
           "object_id": "85e1d73986d648bba2b0151e1f90719a",
           "object_owner": "nataliya_eng@shippo.com",
           "shipment": "bccddc15133b485d8353a647992abc46",
           "attributes": [
               "CHEAPEST"
           ],
           "amount": "48.76",
           "currency": "USD",
           "amount_local": "48.76",
           "currency_local": "USD",
           "provider": "Better Trucks",
           "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/bettertrucks.png",
           "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/bettertrucks.png",
           "servicelevel": {
               "name": "Next Day",
               "token": "better_trucks_next_day",
               "terms": "",
               "extended_token": "better_trucks_next_day",
               "parent_servicelevel": null
           },
           "estimated_days": null,
           "arrives_by": "13:00:00",
           "duration_terms": "",
           "messages": [],
           "carrier_account": "a00414e75df144b596673979108bbab5",
           "test": false,
           "zone": null
       }
   ],
   "messages": [],
   "metadata": "",
   "test": false,
   "order": null
}

Overview

Get started

AI & agents

Guides

Concepts

HTTP Method

URL

Request Payload

Objects

Address

Parcel

Extra

Response Code

Examples

Request Sample for a shipment

Response Sample for a shipment

​HTTP Method

​URL

​Request Payload

​Objects

​ Address

​ Parcel

​ Extra

​Response Code

​Examples

​Request Sample for a shipment

​Response Sample for a shipment

HTTP Method

URL

Request Payload

Objects

Address

Parcel

Extra

Response Code

Examples

Request Sample for a shipment

Response Sample for a shipment