Create shipment - Shippo API Documentation

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	Refer to the Extra object
customs_declaration*	Refer to the Customs declaration object. Required for international shipments
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. 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
location_external_id	Should be set when a Pickup point ID is required. For example for `colissimo_pick_up_point` service level
signature_confirmation	Sets if signature confirmation is required for this shipment. Will be used to determine the correct service level. Optional
reference_1	Optional text to be printed on the shipping label. Up to 50 characters

Customs Declaration

Parameter	Description
certify*	Boolean. Expresses that the certify_signer has provided all information of this customs declaration truthfully
certify_signer*	Name of the person who created the customs declaration and is responsible for the validity of all information provided
items*	Refer Items object
invoiced_charges	Refer Invoiced charges object. An object holding optional invoiced charges data to be printed on the Commercial Invoice. Mandatory for international shipping
incoterm	The incoterm reference of the shipment. For International Overseas shipment we can not use DDP. For International Shipment DDP, DDU, DAP, Empty can be used
contents_type*	Type of goods of the shipment
contents_explanation	This field is mandatory for contents_type = OTHER
hs_code	The HS (Harmonised System) or product code is used by customs officers worldwide to categorise products
invoice	Invoice reference of the shipment

Items

Parameter	Description
description	Text description of your item.
quantity*	Quantity of this item in the shipment you send. Must be greater than 0
net_weight*	Total weight of this item, i.e. quantity * weight per item
mass_unit*	The unit used for net_weight
value_amount*	Total value of this item, i.e. quantity * value per item
value_currency*	Currency in which value is specified
origin_country*	ISO 2 country code

Invoiced charges

Parameter	Description
currency*	Currency for the invoiced charges amounts incurred on the end consumer. Needs to be in euros. Check shipment/customs_declarations/invoiced_charges/currency, if the currency is other than euros then convert to EUR
total_shipping*	Total shipping paid by the buyer

Response Code

201

Examples

Request Sample for a Domestic 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": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street1": "3 Place du Berry",
        "street2": "Rue Jacques Coeur 756",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "+1888-999-1500",
        "email": "Picardie@shippo.com"
  },
  "address_to": {
      "name": "Chapelaine Carnot",
      "company": "Louis Ulbach",
      "street1": "8 Rue de La Vicomté",
      "street2": "Rue de la Pierre",
      "city": "Aube",
      "state": "Troyes",
      "zip": "10000",
      "country": "FR",
      "phone": "+18889575900",
      "email": "Chapelaine@shippo.com"
  },
  "parcels": [{
    "weight": "1",
    "length": "5",
    "width": "4",
    "height": "1",
    "distance_unit": "cm",
    "mass_unit": "kg"
  }],
    "extra": {
       "reference_1": "Ship.Label_Chrono_Ok"

    },
  "carrier_accounts": ["4a4dfb5425ea41b6be2e851306284bf5"],
  "async": false
}'

Response Sample for a Domestic shipment

{
    "carrier_accounts": [
        "4a4dfb5425ea41b6be2e851306284bf5"
    ],
    "object_created": "2022-11-30T12:54:06.091Z",
    "object_updated": "2022-11-30T12:54:06.547Z",
    "object_id": "f500a2e404ac42d5bdf00a92283a8e00",
    "object_owner": "test@shippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "8024d39aeca24c21a095a2c057ded999",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "691f13e12e584d5eaa5b56c870237f3a",
        "is_complete": true,
        "name": "Chapelaine Carnot",
        "company": "Louis Ulbach",
        "street_no": "",
        "street1": "8 Rue de La Vicomté",
        "validation_results": {},
        "street2": "Rue de la Pierre",
        "street3": "",
        "city": "Aube",
        "state": "Troyes",
        "zip": "10000",
        "country": "FR",
        "phone": "0018889575900",
        "email": "Chapelaine@shippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2022-11-30T12:54:06.062Z",
            "object_updated": "2022-11-30T12:54:06.127Z",
            "object_id": "574491335b634d89b3edaca0b55cf420",
            "object_owner": "test@shippo.com",
            "template": null,
            "extra": {},
            "length": "5.0000",
            "width": "4.0000",
            "height": "1.0000",
            "distance_unit": "cm",
            "weight": "1.0000",
            "mass_unit": "kg",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2022-11-30T12:54:06.177Z",
    "address_return": {
        "object_id": "8024d39aeca24c21a095a2c057ded999",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": null,
    "extra": {
        "reference_1": "Ship.Label_Chrono_Ok"
    },
    "rates": [
        {
            "object_created": "2022-11-30T12:54:06.518Z",
            "object_id": "0bd2f0a39733436da688ce2158dd3ad6",
            "object_owner": "test@shippo.com",
            "shipment": "f500a2e404ac42d5bdf00a92283a8e00",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "6.74",
            "currency": "EUR",
            "amount_local": "6.74",
            "currency_local": "EUR",
            "provider": "Colissimo",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
            "servicelevel": {
                "name": "Point Retrait",
                "token": "colissimo_pick_up_point",
                "terms": "",
                "extended_token": "colissimo_pick_up_point",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5",
            "test": true,
            "zone": "1"
        },
        {
            "object_created": "2022-11-30T12:54:06.518Z",
            "object_id": "8f9ad8dd7bf14991ac2a229254256246",
            "object_owner": "test@shippo.com",
            "shipment": "f500a2e404ac42d5bdf00a92283a8e00",
            "attributes": [],
            "amount": "8.14",
            "currency": "EUR",
            "amount_local": "8.14",
            "currency_local": "EUR",
            "provider": "Colissimo",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
            "servicelevel": {
                "name": "Domicile",
                "token": "colissimo_home",
                "terms": "",
                "extended_token": "colissimo_home",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5",
            "test": true,
            "zone": "1"
        }
    ],
    "messages": [],
    "metadata": "",
    "test": true,
    "order": null
}

Request sample for an international 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": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street1": "3 Place du Berry",
        "street2": "Rue Jacques Coeur 756",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "+1888-999-1500",
        "email": "Picardie@shippo.com"
    },
    "address_to": {
        "name": "Mr. Hippo",
        "street1": "24 Endell",
        "city": "London",
        "state": "",
        "zip": "W1D 4HS",
        "country": "GB",
        "phone": "01159 663055",
        "email": "mrhippo@shippo.com"
    },
    "parcels": [
        {
            "weight": "1",
            "length": "5",
            "width": "4",
            "height": "1",
            "distance_unit": "cm",
            "mass_unit": "kg"
        }
    ],
    "customs_declaration": {
        "invoiced_charges": {
            "total_shipping": "10.00",
            "currency": "EUR"
        },
        "contents_type": "MERCHANDISE",
        "contents_explanation": "T-Shirt purchase",
        "invoice": "#123123",
        "notes": "Notes here",
        "certify": true,
        "certify_signer": "Test User",
        "incoterm": "DDU",
        "items": [
            {
                "description": "shirt",
                "quantity": 1,
                "net_weight": "7",
                "mass_unit": "oz",
                "hs_code": "AB123C",
                "sku_code": "A333BFEQA",
                "value_amount": "10",
                "value_currency": "EUR",
                "origin_country": "FR"
            }
        ]
    },
    "carrier_accounts": [
        "4a4dfb5425ea41b6be2e851306284bf5"
    ],
    "async": false
}'

Response sample for international shipment

{
    "carrier_accounts": [
        "4a4dfb5425ea41b6be2e851306284bf5"
    ],
    "object_created": "2022-12-01T11:09:50.513Z",
    "object_updated": "2022-12-01T11:09:51.028Z",
    "object_id": "c9b3601e6ede46ca8732ee1dd16b9b3e",
    "object_owner": "test@shippo.com",
    "status": "SUCCESS",
    "address_from": {
        "object_id": "30a89b461cad4a2f91d6187d94aba5a8",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "address_to": {
        "object_id": "f2a9d19e9cde4bbc89dce5a769fcab45",
        "is_complete": true,
        "name": "Mr. Hippo",
        "company": "",
        "street_no": "",
        "street1": "24 Endell",
        "validation_results": {},
        "street2": "",
        "street3": "",
        "city": "London",
        "state": "",
        "zip": "W1D 4HS",
        "country": "GB",
        "phone": "01159663055",
        "email": "mrhippo@shippo.com",
        "is_residential": null,
        "test": true
    },
    "parcels": [
        {
            "object_state": "VALID",
            "object_created": "2022-12-01T11:09:50.291Z",
            "object_updated": "2022-12-01T11:09:50.575Z",
            "object_id": "037869846bab4e2987ca054d4f31b97e",
            "object_owner": "test@shippo.com",
            "template": null,
            "extra": {},
            "length": "5.0000",
            "width": "4.0000",
            "height": "1.0000",
            "distance_unit": "cm",
            "weight": "1.0000",
            "mass_unit": "kg",
            "value_amount": null,
            "value_currency": null,
            "metadata": "",
            "line_items": [],
            "test": true
        }
    ],
    "shipment_date": "2022-12-01T11:09:50.656Z",
    "address_return": {
        "object_id": "30a89b461cad4a2f91d6187d94aba5a8",
        "is_complete": true,
        "name": "Èmile Zola",
        "company": "Palais Jacques Coeur",
        "street_no": "",
        "street1": "3 Place du Berry",
        "validation_results": {},
        "street2": "Rue Jacques Coeur 756",
        "street3": "",
        "city": "Cher",
        "state": "Bourges",
        "zip": "18000",
        "country": "FR",
        "phone": "0018889991500",
        "email": "Picardie@shippo.com",
        "is_residential": null,
        "test": true
    },
    "alternate_address_to": null,
    "customs_declaration": {
        "object_created": "2022-12-01T11:09:50.410Z",
        "object_updated": "2022-12-01T11:09:50.410Z",
        "object_id": "aa43df470809469688a13ab37e624074",
        "object_owner": "test@shippo.com",
        "object_state": "VALID",
        "address_importer": null,
        "certify_signer": "Test User",
        "certify": true,
        "items": [
            "7e39fad7c4e64285ba4224a6962a0bb4"
        ],
        "non_delivery_option": "RETURN",
        "contents_type": "MERCHANDISE",
        "contents_explanation": "T-Shirt purchase",
        "exporter_reference": "",
        "importer_reference": "",
        "invoice": "#123123",
        "commercial_invoice": false,
        "license": "",
        "certificate": "",
        "notes": "Notes here",
        "eel_pfc": "",
        "aes_itn": "",
        "disclaimer": "",
        "incoterm": "DDU",
        "metadata": "",
        "test": true,
        "duties_payor": null,
        "b13a_filing_option": "",
        "b13a_number": "",
        "invoiced_charges": {
            "total_shipping": "10.00",
            "total_taxes": null,
            "total_duties": null,
            "other_fees": null,
            "currency": "EUR"
        },
        "exporter_identification": null,
        "is_vat_collected": null
    },
    "extra": {},
    "rates": [
        {
            "object_created": "2022-12-01T11:09:50.997Z",
            "object_id": "18db7a1211ee4b2d97e1bad0cbb5ca2f",
            "object_owner": "test@shippo.com",
            "shipment": "c9b3601e6ede46ca8732ee1dd16b9b3e",
            "attributes": [
                "CHEAPEST"
            ],
            "amount": "13.10",
            "currency": "EUR",
            "amount_local": "11.26",
            "currency_local": "GBP",
            "provider": "Colissimo",
            "provider_image_75": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/75/colissimo.png",
            "provider_image_200": "https://dev-qa-static-shippodev-com.s3.amazonaws.com/providers/200/colissimo.png",
            "servicelevel": {
                "name": "Domicile",
                "token": "colissimo_home",
                "terms": "",
                "extended_token": "colissimo_home",
                "parent_servicelevel": null
            },
            "estimated_days": null,
            "arrives_by": null,
            "duration_terms": "",
            "messages": [],
            "carrier_account": "4a4dfb5425ea41b6be2e851306284bf5",
            "test": true,
            "zone": "international_2_gb"
        }
    ],
    "messages": [],
    "metadata": "",
    "test": true,
    "order": null
}

​HTTP Method

​URL

​Request Payload

​Objects

​ Address

​ Parcel

​ Extra

​ Customs Declaration

​ Items

​ Invoiced charges

​Response Code

​Examples

​Request Sample for a Domestic shipment

​Response Sample for a Domestic shipment

​Request sample for an international shipment

​Response sample for international shipment