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
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
extraRefer to the Extra object
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”

​
Extra

ParameterDescription
signature_confirmationSets if signature confirmation is required for this shipment. Possible values true or false for one of such fields:
- signature_confirmation
- Is_over_21_required
alcoholNeed 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
}