Ship From a Warehouse

You likely have one or more warehouse locations that you frequently ship from, in which case it would be annoying to have to specify the ship_from and return_to addresses on every shipment. The solution is to Create a Warehouse, then you can simply pass the warehouse_id instead.

Using warehouses also allows you to Create Manifests of everything you're shipping from each warehouse.

Origin Address vs. Return Address

The Create a Warehouse request will include both an origin address and a return address. These two addresses serve different purposes when shipping.

The origin address is used to calculate shipping costs. This address lets the carrier know where your packages are shipping from and allows the carrier to accurately determine rates.

The return address is the address that will be printed on your outgoing label. This address determines where any packages will be returned to in the event that the package cannot reach its destination.

These addresses are often the same. However, there are times when packages ship from one location and need to be returned to a different location. Creating and using a warehouse allows unique addresses to be specified for each of these purposes.

Example

POST /v1/shipments/

The following example demonstrates how to create a shipment using a warehouse_id instead of a ship_from address. Other than that, it's the same as the normal Create a Shipment workflow.

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
POST /v1/shipments HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "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"
      },
      "warehouse_id": "se-277331",
      "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
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
{
  "has_errors": false,
  "shipments": [
    {
      "errors": null,
      "address_validation": {
        "status": "verified",
        "original_address": {
          "name": "Amanda Miller",
          "phone": "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"
        },
        "matched_address": {
          "name": "AMANDA MILLER",
          "phone": "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"
        },
        "messages": []
      },
      "shipment_id": "se-202927168",
      "carrier_id": "se-123890",
      "service_code": "usps_priority_mail",
      "external_shipment_id": null,
      "ship_date": "2018-02-12T00:00:00Z",
      "created_at": "2018-02-13T02:17:28.5734844Z",
      "modified_at": "2018-02-13T02:17:28.5734844Z",
      "shipment_status": "pending",
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "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": "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": "se-277331",
      "return_to": {
        "company_name": "Example Corp.",
        "name": "John Doe",
        "phone": "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",
      "customs": null,
      "advanced_options": {
        "bill_to_account": null,
        "bill_to_country_code": null,
        "bill_to_party": null,
        "bill_to_postal_code": null,
        "contains_alcohol": false,
        "delivered_duty_paid": false,
        "non_machinable": false,
        "saturday_delivery": false,
        "freight_class": null,
        "custom_field1": null,
        "custom_field2": null,
        "custom_field3": null
      },
      "insurance_provider": "none",
      "tags": [],
      "packages": [
        {
          "package_code": "package",
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          },
          "dimensions": {
            "unit": "inch",
            "length": 0.0,
            "width": 0.0,
            "height": 0.0
          },
          "insured_value": {
            "currency": "usd",
            "amount": 0.0
          },
          "label_messages": {
            "reference1": null,
            "reference2": null,
            "reference3": null
          }
        }
      ],
      "total_weight": {
        "value": 1.0,
        "unit": "ounce"
      }
    }
  ]
}

Overriding the Return Address

By default, specifying a warehouse_id will automatically set ship_from and return_to addresses of the shipment. But there are some scenarios where you may want to override the return address that's printed on the shipping label. ShipEngine allows you to do that by specifying a return_to address in addition to the warehouse_id.

This feature is currently only supported for Stamps.com, Endicia, FedEx, UPS, DHL E-Commerce, and FirstMile. Please let us know if you need support for additional carriers.

Example HTTP 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
POST /v1/shipments HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "shipments": [
    {
      "service_code": "usps_priority_mail",
      "ship_to": {
        "name": "Amanda Miller",
        "phone": "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"
      },
      "return_to": {
        "name": "Example Corp. Returns",
        "phone": "222-222-2222",
        "company_name": "Example Corp.",
        "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": "se-277331",
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}