POST/location/{merchantLocationKey}
Use this call to create a new inventory location. In order to create and publish an offer (and create an eBay listing), a seller must have at least one location, as every offer must be associated with at least one location.
Important!Publish offer note: Fields may be optional or conditionally required when calling this method, but become required when publishing the offer to create an active listing. For this method, see Location fields for a list of fields required to publish an offer.
Upon first creating an inventory location, only a seller-defined location identifier and a physical location is required, and once set, these values can not be changed. The unique identifier value (merchantLocationKey) is passed in at the end of the call URI. This merchantLocationKey value will be used in other Inventory Location calls to identify the location to perform an action against.
When creating an inventory location, the locationTypes can be specified to define the function of a location. At this time, the following locationTypes are supported:
- Fulfillment center locations are used by sellers selling products through the Multi-warehouse program to get improved estimated delivery dates on their listings. A full address is required when creating a fulfillment center location, as well as the fulfillmentCenterSpecifications of the location. For more information on using the fulfillment center location type to get improved delivery dates, see Multi-warehouse program.
- Warehouse locations are used for traditional shipping. A full street address is not needed, but the postalCode and country OR city, stateOrProvince, and country of the location must be provided.
- Store locations are generally used by merchants selling product through the In-Store Pickup program. A full address is required when creating a store location.
Note that all inventory locations are "enabled" by default when they are created, and you must specifically disable them (by passing in a value of DISABLED
in the merchantLocationStatus field) if you want them to be set to the disabled state. The seller's inventory cannot be loaded to inventory locations in the disabled state.
Unless one or more errors and/or warnings occur with the call, there is no response payload for this call. A successful call will return an HTTP status value of 204 No Content.
Input
Resource URI
This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com
root URI with api.sandbox.ebay.com
URI parameters
Parameter | Type | Description |
---|---|---|
merchantLocationKey | string | This path parameter specifies the unique, seller-defined key (ID) for an inventory location. Max length: 36 Occurrence: Required |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization
HTTP header for authentication authorization.
The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.
Header | Type | Description |
---|---|---|
Content-Type | string | This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required |
OAuth scope
This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):
https://api.ebay.com/oauth/api_scope/sell.inventory
See OAuth access tokens for more information.
Request payload
Copy complete valid JSON to clipboardRequest fields
Input container/field | Type | Description |
---|---|---|
location | LocationDetails | This required container is used to set the physical address and geographical coordinates of a warehouse, store, or fulfillment center inventory location. A warehouse location only requires the postal code and country OR city, province/state, and country, and does not require a full street address. However, the seller may still supply a full street address for a warehouse location. A complete address (addressLine1, city, stateOrProvince, postalCode, and country) is required for store and fulfillment center locations. Occurrence: Required |
location.address | Address | This required container sets the physical address of an inventory location. Except in the case store or fulfillment center location, a full address is not a requirement when setting up a location. For warehouse locations, the fields required in this container are either of the following sets:
Occurrence: Required |
location.address.addressLine1 | string | The first line of a street address. This field is required for store and fulfillment center locations. A street address is not required for warehouse locations. Occurrence: Conditional |
location.address.addressLine2 | string | The second line of a street address. This field can be used for additional address information, such as a suite or apartment number. Occurrence: Conditional |
location.address.city | string | The city in which the inventory location resides. This field is required for store and fulfillment center locations. For warehouse locations, this field is conditionally required as part of a city and stateOrProvince pair if a postalCode is not provided. If a postalCode is provided, the city is derived from the provided postal code and this field is technically optional. Occurrence: Conditional |
location.address.country | CountryCodeEnum | The country in which the address resides, represented as two-letter ISO 3166 country code. For example, Occurrence: Required |
location.address.county | string | The county in which the address resides. Occurrence: Optional |
location.address.postalCode | string | The postal/zip code of the address. eBay uses postal codes to surface In-Store Pickup items within the vicinity of a buyer's location, and it also uses postal codes (origin and destination) to estimate shipping costs when the seller uses calculated shipping. This field is required for store and fulfillment center locations. Occurrence: Conditional |
location.address.stateOrProvince | string | The state/province in which the inventory location resides. This field is required for store and fulfillment center locations. For warehouse locations, this field is conditionally required as part of a city and stateOrProvince pair if a postalCode is not provided. If a postalCode is provided, the state or province is derived from the provided zip code and this field is technically optional. Occurrence: Conditional |
location.geoCoordinates | GeoCoordinates | This container is used to set the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location. Occurrence: Conditional |
location.geoCoordinates.latitude | number | The latitude (North-South) component of the geographic coordinate. This field is required if a geoCoordinates container is used. Occurrence: Conditional |
location.geoCoordinates.longitude | number | The longitude (East-West) component of the geographic coordinate. This field is required if a geoCoordinates container is used. Occurrence: Conditional |
locationAdditionalInformation | string | This text field is used by the merchant to provide additional information about an inventory location. Occurrence: Optional |
locationInstructions | string | This text field is generally used by the merchant to provide special pickup instructions for a store inventory location. Although this field is optional, it is recommended that merchants provide this field to create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field is not included in the call request payload, eBay will use the default pickup instructions contained in the merchant's profile (if available). Occurrence: Optional |
locationTypes | array of StoreTypeEnum | This container is used to define the function of the inventory location. Typically, an inventory location will serve as a store, warehouse, or fulfillment center, but in some cases, an inventory location may be more than one type. Occurrence: Conditional |
locationWebUrl | string | This text field is used by the merchant to provide the Website address (URL) associated with the inventory location. Occurrence: Optional |
merchantLocationStatus | StatusEnum | This field is used to indicate whether the inventory location will be enabled (inventory can be loaded to location) or disabled (inventory can not be loaded to location). If this field is omitted, a successful createInventoryLocation call will automatically enable the location. A merchant may want to create a new location but leave it as disabled if the location is not yet ready for active inventory. Once the location is ready, the merchant can use the enableInventoryLocation call to enable a location that is in a disabled state. Occurrence: Optional |
name | string | The seller-defined name of the inventory location. This name should be a human-friendly name as it will be displayed in In-Store Pickup and Click and Collect listings. A name is not required for warehouse locations. For store locations, this field is not immediately required, but will be required before an offer enabled with the In-Store Pickup or Click and Collect capability can be published. So, if the seller omits this field in a createInventoryLocation call, it becomes required for an updateInventoryLocation call. Occurrence: Conditional |
operatingHours | array of OperatingHours | This container is used to express the regular operating hours for a store location during each day of the week. A dayOfWeekEnum field and an intervals container will be needed for each day of the week that the store location is open. Occurrence: Optional |
operatingHours.dayOfWeekEnum | DayOfWeekEnum | A dayOfWeekEnum value is required for each day of the week that the store location has regular operating hours. Occurrence: Conditional |
operatingHours.intervals | array of Interval | This container is used to define the opening and closing times of a store location's working day (defined in the dayOfWeekEnum field). An intervals container is needed for each day of the week that the store location is open. If a store location closes for lunch (or any other period during the day) and then reopens, multiple open and close pairs are needed Occurrence: Conditional |
operatingHours.intervals.close | string | The close value is actually the time that the store location closes. Local time (in Military format) is used. So, if a store closed at 8 PM local time, the close time would look like the following: Occurrence: Conditional |
operatingHours.intervals.open | string | The open value is actually the time that the store opens. Local time (in Military format) is used. So, if a store opens at 9 AM local time, the close time would look like the following: Occurrence: Conditional |
phone | string | This field is used to specify the phone number for an inventory location. Occurrence: Required |
specialHours | array of SpecialHours | This container is used to express the special operating hours for a store inventory location on a specific date, such as a holiday. The special hours specified for the specific date will override the normal operating hours for that particular day of the week. Occurrence: Optional |
specialHours.date | string | A date value is required for each specific date that the store location has special operating hours. Occurrence: Conditional |
specialHours.intervals | array of Interval | This container is used to define the opening and closing times of a store location on a specific date (defined in the date field). An intervals container is needed for each specific date that the store has special operating hours. These special operating hours on the specific date override the normal operating hours for the specific day of the week. If a store location closes for lunch (or any other period during the day) and then reopens, multiple open and close pairs are needed. Occurrence: Conditional |
specialHours.intervals.close | string | The close value is actually the time that the store location closes. Local time (in Military format) is used. So, if a store closed at 8 PM local time, the close time would look like the following: Occurrence: Conditional |
specialHours.intervals.open | string | The open value is actually the time that the store opens. Local time (in Military format) is used. So, if a store opens at 9 AM local time, the close time would look like the following: Occurrence: Conditional |
timeZoneId | string | This field specifies the time zone of the inventory location being created. This value should be in Olson format (for example Occurrence: Optional |
fulfillmentCenterSpecifications | FulfillmentCenterSpecifications | This container is used to specify information about a fulfillment center's shipping specifications, such as the weekly cut-off time schedule for order handling and any cut-off time overrides. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes | SameDayShippingCutOffTimes | Note: This container only applies to listings with same-day handling. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.overrides | array of Overrides | This container can be used to override the existing cut-off time(s), specified in the weeklySchedule container, for a specific date or date range. Occurrence: Optional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.overrides.cutOffTime | string | This field is used to override the cut-off time(s) specified in the weeklySchedule container. If an order is placed after this time in the specified date or date range, it will be handled by the seller on the following day. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.overrides.endDate | string | The end date of the cut-off time override in ISO 8601 format, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.overrides.startDate | string | The start date of the cut-off time override in ISO 8601 format, which is based on the 24-hour Coordinated Universal Time (UTC) clock. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.weeklySchedule | array of WeeklySchedule | This container is used to specify the weekly schedule for shipping and handling cut-off times. A cut-off time is required for each business day that the fulfillment center operates. Any orders made after the specified cutOffTime on the specified day(s) of the week will be handled on the next day. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.weeklySchedule.cutOffTime | string | This field specifies the cut-off times (in 24-hour format) for the business day(s) specified in the dayOfWeekEnum array. Occurrence: Conditional |
fulfillmentCenterSpecifications.sameDayShippingCutOffTimes.weeklySchedule.dayOfWeekEnum | array of DayOfWeekEnum | This comma-separated array defines the days of week for which the specified cutOffTime is used. Occurrence: Conditional |
Output
HTTP response headers
This call has no response headers.
Response payload
This call has no payload.
Response fields
This call has no field definitions.
HTTP status codes
This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.
Status | Meaning |
---|---|
204 | No Content |
400 | Bad Request |
409 | Location Already Exists |
500 | Internal Server Error |
Error codes
For more on errors, plus the codes of other common errors, see Handling errors.
Code | Domain | Category | Meaning |
---|---|---|---|
25001 | API_INVENTORY | APPLICATION | System error. {additionalInfo} |
25800 | API_INVENTORY | REQUEST | Invalid {fieldName}. |
25801 | API_INVENTORY | REQUEST | Missing field {fieldName}. |
25802 | API_INVENTORY | REQUEST | Input error. {additionalInfo} |
25803 | API_INVENTORY | REQUEST | {fieldName} already exists. |
25804 | API_INVENTORY | REQUEST | Input error. {additionalInfo} |
Warnings
This call has no warnings.
Samples
New to making API calls? Please see Making a Call.
Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.
Sample 1: Create a warehouse location
Use this operation to create and configure a warehouse location that sellers can use to track the storage of the items in their inventory.
Input
A unique seller-defined merchantLocationKey is required as a path parameter in this call.
When creating a warehouse location, a full street address is not required, but the postalCode and country OR city, state/province, and country fields must be provided. In this sample, the city, state, and country have been provided.
The locationTypes array must also be set to WAREHOUSE
.
POSThttps://api.ebay.com/sell/inventory/v1/location/"W********1"
Output
A successful call returns the HTTP status code 204 No content. This method has no response payload.
Sample 2: Create a store location
Use this operation to create and configure a store location that sellers can use for In-Store Pickup listings.
Input
A unique seller-defined merchantLocationKey is required as a path parameter in this call.
When creating a store location, a full street address is required, as well as the store's operating hours.
The locationTypes array must also be set to STORE
.
POSThttps://api.ebay.com/sell/inventory/v1/location/"W********1"
Output
A successful call returns the HTTP status code 204 No content. This method has no response payload.
Sample 3: Create a fulfillment center location
Use this operation to create and configure a fulfillment center location that sellers can use for multi-warehouse program for improved estimated delivery dates on listings.
Input
A unique seller-defined merchantLocationKey is required as a path parameter in this call.
When creating a fulfillment location, a full street address is required, as well as the fulfillmentCenterSpecifications of the location. The fulfillmentCenterSpecifications container includes the weekly schedule of the location, as well as any cut-off time overrides.
The locationTypes array must also be set to FULFILLMENT_CENTER
.
POSThttps://api.ebay.com/sell/inventory/v1/location/"W********1"
Output
A successful call returns the HTTP status code 204 No content. This method has no response payload.
Sample 4: Create an inventory location with multiple location types
Use this operation to create and configure an inventory location that is a warehouse, store, and fulfillment center.
Input
A unique seller-defined merchantLocationKey is required as a path parameter in this call.
When creating a combined-type location, the locationTypes array must include each location type associated for the location. In this sample, this array should include WAREHOUSE
, STORE
, and FULFILLMENT_CENTER
.
When creating a combined-type location, all required fields for each location type must be input in the request. In this sample, a full address is required (as it is required for store and fulfillment center locations). In addition, operatingHours and fulfillmentCenterSpecifications containers must also be included.
POSThttps://api.ebay.com/sell/inventory/v1/location/"W********1"
Output
A successful call returns the HTTP status code 204 No content. This method has no response payload.