# ![](/assets/step2.37831ee18f1f0290fe49fb6b512319f7a374b18f4063f0302fe35b4afcd9816b.9c1bb791.svg) 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](#request-sample-for-an-international-shipment)


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) |
| address_to* | [Refer to the Address object](#address) |
| parcels* | [Refer to the Parcel object](#parcel) |
| extra | [Refer to the Extra object](#extra) |
| customs_declaration* | [Refer to the Customs declaration object](#customs_declaration). 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 |
|  --- | --- |
| 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](#items) |
| invoiced_charges | [Refer Invoiced charges object](#invoiced_charges). 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


```shell
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


```json
{
    "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


```shell
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


```json
{
    "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
}
```