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 | 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 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" |
Extra
| Parameter | Description |
|---|---|
| local_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 --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken shippo_live_******' \
--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 --location --request POST 'https://api.goshippo.com/shipments' \
--header 'Authorization: ShippoToken shippo_live_******' \
--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
}