Create a Warehouse

Use this API request call to create a warehouse location in ShipEngine. The response will generate and return the warehouse_id that serves as an identifier for that warehouse, for example, "warehouse_id": "se-123456".

You can use a warehouse_id to enable many special features in ShipEngine. They're necessary to create manifests, and they help to more efficiently and reliably indicate Ship From information. If you generate and print return shipping labels, use a warehouse_id to provide the address of your returns department. This is especially helpful if that Returns Location exists at a separate address from your primary warehouse.

If you do not supply the return address in the request body, then ShipEngine assumes that the origin address and return address are both the same.

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

CLICK TO OPEN: Table with Parameter Requirements (properties, type, description) to Create a Warehouse. For samples of a full request, see the EXAMPLE REQUEST section below.

NOTE: The symbol --> in this table means that property is part of an object.

Property Name	Required	Type	Description
`is_default`		boolean	Nullable. Default: `false` Designates which single warehouse is the default on the account. NOTE: The first warehouse created on the account automatically becomes the default. Should you want to delete this warehouse, you must create another warehouse, make the new one the default, and then you can remove the first one.
`name`	✔	string	`non-empty` Name of the warehouse.
`origin_address`	✔	object	The origin address of the warehouse.
--> `name`	✔	string	`non-empty` The name of a contact person at this address. This field may be set instead of, or in addition to, the `company_name` field.
--> `phone`	✔	string	`non-empty` The phone number of a contact person at this address. The format of this phone number varies depending on the country.
--> `email`		string	Nullable Email for the address owner.
--> `company_name`		string	Nullable `non-empty` If this is a business address, then specify the company name here.
--> `address_line1`	✔	string	`non-empty` The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
--> `address_line2`		string	Nullable `non-empty` The second line of the street address. For some addresses, this line may not be needed.
--> `address_line3`		string	Nullable `non-empty` The third line of the street address. For some addresses, this line may not be needed.
--> `city_locality`	✔	string	`non-empty` The name of the city or locality.
--> `state_province`	✔	string	`non-empty` The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
--> `postal_code`	✔	string	`non-empty` postal code
--> `country_code`	✔	string	2 characters The two-letter ISO 3166-1 country code.
--> `address_residential_indicator`	✔	string	Default: `"unknown"` Enum: `"unknown"` `"yes"` `"no"` Indicates whether or not this is a residential address.
`return_address`		object	The return address of the warehouse.
--> `name`	✔	string	`non-empty` The name of a contact person at this address. This field may be set instead of, or in addition to, the `company_name` field.
--> `phone`	✔	string	`non-empty` The phone number of a contact person at this address. The format of this phone number varies depending on the country.
--> `email`		string	Nullable Email for the address owner.
--> `company_name`		string	Nullable `non-empty` If this is a business address, then specify the company name here.
--> `address_line1`	✔	string	`non-empty` The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
--> `address_line2`		string	`non-empty` Nullable
--> `address_line3`		string	`non-empty` Nullable
--> `city_locality`	✔	string	`non-empty` The name of the city or locality.
--> `state_province`	✔	string	`non-empty` The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
--> `postal_code`	✔	string	`non-empty` postal code
--> `country_code`	✔	string	2 characters The two-letter ISO 3166-1 country code.
--> `address_residential_indicator`	✔	string	Default: `"unknown"` Enum: `"unknown"` `"yes"` `"no"` Indicates whether or not this is a residential address.

POST /v1/warehouses

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
POST /v1/warehouses HTTP/1.1
Host: api.shipengine.com
API-Key: __YOUR_API_KEY_HERE__
Content-Type: application/json
{
  "name": "Example Corp. East Warehouse",
  "origin_address": {
    "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"
  },
  "return_address": {
    "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"
  }
}

Example Response

CLICK TO OPEN: Table with 200 Response Schema (properties, type, description) when you Create a Warehouse. For samples of a full request, see the EXAMPLE RESPONSE section below.

NOTE: The symbol --> in this table means that property is part of an object.

Property Name	Required	Type	Description
`warehouse_id`	✔	string	`[ 1 .. 25 ] characters` A string that uniquely identifies the warehouse.
`is_default`		boolean	Nullable. Default: `false` Designates which single warehouse is the default on the account. NOTE: The first warehouse created on the account automatically becomes the default. Should you want to delete this warehouse, you must create another warehouse, make the new one the default, and then you can remove the first one.
`name`	✔	string	`non-empty` Name of the warehouse.
`created_at`	✔	string	`<date-time>` `non-empty` Timestamp that indicates when the warehouse was created.
`origin_address`	✔	object	The origin address of the warehouse
--> `name`	✔	string	`non-empty` The name of a contact person at this address. This field may be set instead of, or in addition to, the `company_name` field.
--> `phone`	✔	string	`non-empty` The phone number of a contact person at this address. The format of this phone number varies depending on the country.
--> `email`		string	Nullable Email for the address owner.
--> `company_name`		string	Nullable `non-empty` If this is a business address, then specify the company name here.
--> `address_line1`	✔	string	`non-empty` The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
--> `address_line2`		string	Nullable `non-empty` The second line of the street address. For some addresses, this line may not be needed.
--> `address_line3`		string	Nullable `non-empty` The third line of the street address. For some addresses, this line may not be needed.
--> `city_locality`	✔	string	`non-empty` The name of the city or locality.
--> `state_province`	✔	string	`non-empty` The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
--> `postal_code`	✔	string	`non-empty` postal code
--> `country_code`	✔	string	2 characters The two-letter ISO 3166-1 country code
--> `address_residential_indicator`	✔	string	Default: `"unknown"` Enum: `"unknown"` `"yes"` `"no"` Indicates whether or not this is a residential address.
`return_address`		object	The return address of the warehouse.
--> `name`	✔	string	`non-empty` The name of a contact person at this address. This field may be set instead of, or in addition to, the `company_name` field.
--> `phone`	✔	string	`non-empty` The phone number of a contact person at this address. The format of this phone number varies depending on the country.
--> `email`		string	Nullable Email for the address owner.
--> `company_name`		string	Nullable `non-empty` If this is a business address, then specify the company name here.
--> `address_line1`	✔	string	`non-empty` The first line of the street address. For some addresses, this may be the only line. Other addresses may require 2 or 3 lines.
--> `address_line2`		string	`non-empty` Nullable
--> `address_line3`		string	`non-empty` Nullable
--> `city_locality`	✔	string	`non-empty` The name of the city or locality.
--> `state_province`	✔	string	`non-empty` The state or province. For some countries (including the U.S.) only abbreviations are allowed. Other countries allow the full name or abbreviation.
--> `postal_code`	✔	string	`non-empty` postal code
--> `country_code`	✔	string	2 characters The two-letter ISO 3166-1 country code.
--> `address_residential_indicator`	✔	string	Default: `"unknown"` Enum: `"unknown"` `"yes"` `"no"` Indicates whether or not this is a residential address.

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
{
  "warehouse_id": "se-277331",
  "name": "Example Corp. East Warehouse",
  "created_at": "2018-02-12T23:48:15.387Z",
  "origin_address": {
    "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"
  },
  "return_address": {
    "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"
  }
}