Site Logo

Create a Shipment

Many ShipEngine endpoints require a shipment_id, which is the unique identifier for a shipment object created in ShipEngine. You can think of shipment objects as the gatekeepers to more advanced functionality in ShipEngine.

Certain actions will automatically create a shipment object for you, like purchasing a label and rating 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 defined.

See the full API reference for details on the available objects and properties for the request body.

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.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
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": "[email protected]",
        "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": "[email protected]"
        "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 inside of ShipEngine. 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

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
{
  "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": "[email protected]",
        "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": "[email protected]",
        "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:

1
2
3
{
  "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 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 amanifest, you'll need to provide the warehouse_id rather than the ship_from address in your request body. You can create a warehouse for each location that you want to create manifests for.
  • Getting shipment rates: You can also use the shipments endpoint to get rates. To do so, just include the rate_options field in the shipment payload.