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

​
Customs Declaration

ParameterDescription
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_chargesRefer Invoiced charges object. An object holding optional invoiced charges data to be printed on the Commercial Invoice. Mandatory for international shipping
incotermThe 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_explanationThis field is mandatory for contents_type = OTHER
hs_codeThe HS (Harmonised System) or product code is used by customs officers worldwide to categorise products
invoiceInvoice reference of the shipment

​
Items

ParameterDescription
descriptionText 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

ParameterDescription
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
}