Ship From a Warehouse

When you have one or more warehouse locations that you frequently ship from, it can be cumbersome to specify the ship_from and return_to addresses on every shipment. When you create a warehouse for each of the locations you ship from, you define the ship_from and return_to addresses for each location and then pass the warehouse_id in your request instead.

For some operations, a warehouse_id is required, as when creating batches and creating manifests.

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 or you generate a return label for the shipment at a later date.

While these addresses are often the same, 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 Request & Response

POST /v1/shipments/

The following example demonstrates how to create a shipment using a warehouse_id instead of a ship_from address. Other than the warehouse_id property, the request is the same as any other create shipment workflow.

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
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",
        "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"
      },
      "warehouse_id": "se-277331",
      "packages": [
        {
          "weight": {
            "value": 1.0,
            "unit": "ounce"
          }
        }
      ]
    }
  ]
}

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 the ship_from and return_to addresses of the shipment. But there are some scenarios where you may want to override the return address. ShipStation API 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 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"
          }
        }
      ]
    }
  ]
}