Create a Shipment

You may have already noticed that when you Got a Shipping Rate that you actually created a new object inside of ShipEngine. Shipments are the gatekeeper to more advanced functionality inside ShipEngine.

The Basics

When you create a shipment, we respond with a shipment_id that is a unique identifier inside of ShipEngine. Additionally, we realize that you may have your own identifier, you can set this by setting the external_shipment_id field in the request body.

Creating a Shipment

To create a shipment, we will use the same command as we do when we get a rate, with one small modification, we remove the rate_options property, this tells the server not to rate the shipment.

Tip

Do you plan on creating manifests?

If you want your shipment to be included in a manifest, then you'll need to provide the warehouse_id rather than the ship_from address. You can create a warehouse for each location that you want to create manifests for.

Info

Getting Rate Options

As we discussed in Get Shipping Rates, you can also use this method to get rates. You need to simply include the rate_options field in the shipment payload. Here we have excluded this functionality.

Notice that we included a external_shipment_id, that was then persisted back in the JSON response:

"shipment_id": "se-2126691",
"external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",

Tip

ShipEngine Shipment ID

The shipment_id that is returned is the unique identifier inside of ShipEngine. Many of our endpoints require the use of our internal shipment_id; however, the external_shipment_id is useful with our responses to easily match them to your own records.

Example Request

curl -iX POST https://api.shipengine.com/v1/shipments \
-H 'Content-Type: application/json' \
-H 'API-Key: __YOUR_API_KEY_HERE__' \
-d '
{
  "shipments": [
    {
      "validate_address": "no_validation",
      "service_code": "usps_priority_mail",
      "external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c",
      "ship_to": {
        "name": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 South Buena Vista Street",
        "city_locality": "Burbank",
        "state_province": "CA",
        "postal_code": "91521",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "ship_from": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "confirmation": "none",
      "advanced_options": {},
      "insurance_provider": "none",
      "tags": [],
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}'

Example Response

{
  "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": "Mickey and Minnie Mouse",
        "phone": "714-781-4565",
        "company_name": "The Walt Disney Company",
        "address_line1": "500 South Buena Vista Street",
        "address_line2": null,
        "address_line3": null,
        "city_locality": "Burbank",
        "state_province": "CA",
        "postal_code": "91521",
        "country_code": "US",
        "address_residential_indicator": "no"
      },
      "ship_from": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "address_line3": null,
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "unknown"
      },
      "warehouse_id": null,
      "return_to": {
        "name": "Dade Murphy",
        "phone": "512-485-4282",
        "company_name": "Zero Cool",
        "address_line1": "345 Chambers Street",
        "address_line2": "Suite 100",
        "address_line3": null,
        "city_locality": "New York City",
        "state_province": "NY",
        "postal_code": "10282",
        "country_code": "US",
        "address_residential_indicator": "unknown"
      },
      "insurance_provider": "none",
      "tags": [],
      "packages": [
        {
          "package_code": "package",
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          }
        }
      ],
      "total_weight": {
        "value": 1.0,
        "unit": "ounce"
      }
    }
  ]
}

Duplicate External Shipment ID's

We allow you to set your own external_shipment_id; however, this must be unqiue. If you provide a duplicate id, you receive an error message like this.

{
  "message": "external_shipment_id 1daa0c22-0519-46d0-8653-9f3dc62e7d2c already exists"
}