# Create a Shipment Many ShipStation API endpoints require a `shipment_id`, which is the unique identifier for a shipment object created with ShipStation API. You can think of shipment objects as the gatekeepers to more advanced functionality in the ShipStation API. Certain actions will automatically create a shipment object for you, like [purchasing a label](/apis/shipengine/docs/labels/create-a-label) and [rating multiple shipments](/apis/shipengine/docs/rates/multiple-shipments). However, you can also create shipments independently so you can use shipment IDs for features like getting rates in bulk or batch shipping. When you create a shipment, the response includes the `shipment_id`. We also realize that you may have your own shipment identifier, which you can set using the `external_shipment_id` field in the request body. The `external_shipment_id` is useful with our responses to easily match them to your own records. Please note that when using the `external_shipment_id` this ID **must be unique**. If you provide a duplicate ID, you receive an error message. ## Requirements When creating a shipment you can define multiple objects within the request body, but only a few are required. * `carrier_id` * `service_code` * `ship_to` * `ship_from` The `ship_to` and `ship_from` objects have multiple required properties. Additionally, other objects may be necessary depending on what actions you plan to take. For example, cross-border shipments will need customs details, manifests will need `ship_date` and `warehouse_id`, and some shipments may need [advanced options](/apis/shipengine/docs/carriers/advanced-options) defined. See the [full API reference](https://shipengine.github.io/shipengine-openapi/#operation/create_shipments) for details on the available objects and properties for the request body. > **IMPORTANT:** ### Phone Number Formatting The `phone` property in the `ship_to` and `ship_from` objects is a string and is not validated based on format. However, some carriers may return an error if the format is not valid for the countries they deliver to. Best practice is to use the phone number format specific to the Ship To and Ship From country, including the calling-code prefix. ## Example Request & Response **POST /v1/shipments** In this example, we create a single shipment and include an `external_shipment_id` to demonstrate using this optional property, if needed. ```http POST /v1/shipments HTTP/1.1 Host: api.shipengine.com API-Key: __YOUR_API_KEY_HERE__ Content-Type: application/json { "shipments": [ { "validate_address": "no_validation", "service_code": "usps_priority_mail", "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c", "ship_to": { "name": "Amanda Miller", "phone": "+1 555-555-5555", "email": "recipient@example.com", "address_line1": "525 S Winchester Blvd", "city_locality": "San Jose", "state_province": "CA", "postal_code": "95128", "country_code": "US", "address_residential_indicator": "yes" }, "ship_from": { "company_name": "Example Corp.", "name": "John Doe", "phone": "+1 111-111-1111", "email": "sender@example.com" "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "confirmation": "none", "advanced_options": {}, "insurance_provider": "none", "tags": [], "packages": [ { "weight": { "value": 1.0, "unit": "ounce" } } ] } ] } ``` The `shipment_id` that is returned is the unique identifier within ShipStation API. Many of our endpoints require the use of our internal `shipment_id`. The `external_shipment_id` is useful with our responses to easily match them to your own records. **Response** ```json { "has_errors": false, "shipments": [ { "errors": null, "address_validation": null, "shipment_id": "se-202902255", "carrier_id": "se-123890", "service_code": "usps_priority_mail", "external_shipment_id": "0bcb569d-1727-4ff9-ab49-b2fec0cee5ae", "ship_date": "2018-02-12T00:00:00Z", "created_at": "2018-02-13T00:53:52.0275877Z", "modified_at": "2018-02-13T00:53:52.0275877Z", "shipment_status": "pending", "ship_to": { "name": "Amanda Miller", "phone": "+1 555-555-5555", "email": "recipient@example.com", "address_line1": "525 S Winchester Blvd", "city_locality": "San Jose", "state_province": "CA", "postal_code": "95128", "country_code": "US", "address_residential_indicator": "yes" }, "ship_from": { "company_name": "Example Corp.", "name": "John Doe", "phone": "+1 111-111-1111", "email": "sender@example.com", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "warehouse_id": null, "return_to": { "company_name": "Example Corp.", "name": "John Doe", "phone": "+1 111-111-1111", "address_line1": "4009 Marathon Blvd", "address_line2": "Suite 300", "city_locality": "Austin", "state_province": "TX", "postal_code": "78756", "country_code": "US", "address_residential_indicator": "no" }, "insurance_provider": "none", "tags": [], "packages": [ { "package_code": "package", "weight": { "value": 1, "unit": "ounce" }, "insured_value": { "currency": "usd", "amount": 0 } } ], "total_weight": { "value": 1, "unit": "ounce" } } ] } ``` ### Duplicate External Shipment ID Error If you provide a duplicate external shipment ID, you'll receive an error message like this: ```json { "message": "external_shipment_id 1daa0c22-0519-46d0-8653-9f3dc62e7d2c already exists" } ``` ## Notes about Creating Shipments * **Create multiple shipments**: You can use this same method to [create multiple shipments](/apis/shipengine/docs/reference/create-shipments) at once simply by adding more objects to the `shipments` array. The response will include the corresponding `shipment_id` (and related properties) for each shipment you created. * **Manifests**: If you want your shipment to be included in a[manifest](/apis/shipengine/docs/shipping/manifests), you'll need to provide the `warehouse_id` rather than the `ship_from` address in your request body. You can [create a warehouse](/apis/shipengine/docs/reference/create-warehouse) for each location that you want to create manifests for. * **Getting shipment rates**: You can also use the shipments endpoint to [get rates](/apis/shipengine/docs/rates/get-shipment-rates). To do so, just include the `rate_options` field in the shipment payload.