Site Logo

Create a Shipment

You may have already noticed that when you Get a Shipping Rate, a new shipment object is created inside of ShipEngine. Shipments are the gatekeepers 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.

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

1
2
3
4
{
"shipment_id": "se-2126691",
"external_shipment_id": "1daa0c22-0519-46d0-8653-9f3dc62e7d2c"
}

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

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
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",
"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",
"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"
}
}
]
}
]
}

Example 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
{
"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",
"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",
"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 IDs

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

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