inventory APIv1.6.0

createInventoryLocation

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 inventory location, as every offer must be associated with a location.

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 inventory location to perform an action against.

At this time, location types are either warehouse or store. Warehouse locations are used for traditional shipping, and store locations are generally used by US merchants selling products through the In-Store Pickup program, or used by UK, Australian, and German merchants selling products through the Click and Collect program. A full address is required for store inventory locations. However, for warehouse inventory locations, a full street address is not needed, but the city, state/province, and country of the location must be provided.

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.

In addition to the authorization header, which is required for all eBay REST API calls, the following table includes another request header that is mandatory for the createInventoryLocation call, and two other request headers that are optional:


Header Description Required? Applicable Values
Accept Describes the response encoding, as required by the caller. Currently, the interfaces require payloads formatted in JSON, and JSON is the default. No application/json
Content-Language Use this header to control the language that is used for any returned errors or warnings in the call response. No en-US
Content-Type The MIME type of the body of the request. Must be JSON. Yes application/json


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 (production)

POST https://api.ebay.com/sell/inventory/v1/location/{merchantLocationKey}

URI parameters

ParameterTypeDescription
merchantLocationKeystringA unique, merchant-defined key (ID) for an inventory location. This unique identifier, or key, is used in other Inventory API calls to identify 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.

OAuth scope

This request requires an access token created with the authorization code grant flow, using one scope from the following list:

https://api.ebay.com/oauth/api_scope/sell.inventory

eBayUser

See OAuth access tokens for more information.

Input container/fieldTypeDescription
locationLocationDetailsThis required container is used to set the physical address and geographical coordinates (optional) of a warehouse or store inventory location. A warehouse inventory location only requires the 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. The physical location/address for an inventory location cannot be modified once set with a createInventoryLocation call. All other details of an inventory location (e.g. phone or operating hours) can be changed with an updateInventoryLocation call.

Occurrence: Required

location.addressAddressThe address container is required for a createInventoryLocation call. Except in the case of an inventory location that supports In-Store Pickup inventory, a full address is not a requirement when setting up an inventory location.

Occurrence: Required

location.address.addressLine1stringThe first line of a street address. This field is required for store inventory locations that will be holding In-Store Pickup inventory. A street address is not required if the inventory location is not holding In-Store Pickup Inventory. This field will be returned if defined for an inventory location.

Max length: 128

Occurrence: Conditional

location.address.addressLine2stringThe second line of a street address. This field can be used for additional address information, such as a suite or apartment number. A street address is not required if the inventory location is not holding In-Store Pickup Inventory. This field will be returned if defined for an inventory location.

Max length: 128

Occurrence: Conditional

location.address.citystringThe city in which the inventory location resides. This field is required for store inventory locations that will be holding In-Store Pickup inventory. For warehouse locations, this field is technically optional, as a postalCode can be used instead of city/stateOrProvince pair, and then the city is just derived from this postal/zip code. This field is returned if defined for an inventory location.

Max length: 128

Occurrence: Conditional

location.address.countryCountryCodeEnumThe country in which the address resides, represented as two-letter ISO 3166-1 Alpha-2 country code. For example, US represents the United States, and DE represents Germany.

Max length: 2

Occurrence: Required

location.address.countystringThe county in which the address resides. This field is returned if defined for an inventory location.

Occurrence: Optional

location.address.postalCodestringThe 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 user postal codes (origin and destination) to estimate shipping costs when the seller uses calculated shipping. A city/stateOrProvince pair can be used instead of a postalCode value, and then the postal code is just derived from the city and state/province. This field is returned if defined for an inventory location.

Max length: 16

Occurrence: Conditional

location.address.stateOrProvincestringThe state/province in which the inventory location resides. This field is required for store inventory locations that will be holding In-Store Pickup inventory. For warehouse locations, this field is technically optional, as a postalCode can be used instead of city/stateOrProvince pair, and then the state or province is just derived from this postal/zip code.

Max length: 128

Occurrence: Conditional

location.geoCoordinatesGeoCoordinatesThis container is used to set the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location.

Occurrence: Optional

location.geoCoordinates.latitudenumberThe latitude (North-South) component of the geographic coordinate. This field is required if a geoCoordinates container is used.

This field is returned if geographical coordinates are set for the inventory location.

Occurrence: Conditional

location.geoCoordinates.longitudenumberThe longitude (East-West) component of the geographic coordinate. This field is required if a geoCoordinates container is used.

This field is returned if geographical coordinates are set for the inventory location.

Occurrence: Conditional

locationAdditionalInformationstringThis text field is used by the merchant to provide additional information about an inventory location.

Max length: 256

Occurrence: Optional

locationInstructionsstringThis 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

locationTypesarray of StoreTypeEnumThis container is used to define the function of the inventory location. Typically, an inventory location will serve as a store or a warehouse, but in some cases, an inventory location may be both.

If this container is omitted, the location type of the inventory location will default to WAREHOUSE. See StoreTypeEnum for the supported values.

Default: WAREHOUSE

Occurrence: Optional

locationWebUrlstringThis text field is used by the merchant to provide the Website address (URL) associated with the inventory location.

Max length: 512

Occurrence: Optional

merchantLocationStatusStatusEnumThis 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 inventory location. A merchant may want to create a new inventory location but leave it as disabled if the inventory location is not yet ready for active inventory. Once the inventory location is ready, the merchant can use the enableInventoryLocation call to enable an inventory location that is in a disabled state. See StatusEnum for the supported values.

Default: ENABLED

Occurrence: Optional

namestringThe 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 inventory locations. For store inventory 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.

Max length: 1000

Occurrence: Conditional

operatingHoursarray of OperatingHoursAlthough not technically required, this container is highly recommended to be used to specify operating hours for a store inventory location. 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.dayOfWeekEnumDayOfWeekEnumA dayOfWeekEnum value is required for each day of the week that the store location has regular operating hours.

This field is returned if operating hours are defined for the store location.

Occurrence: Required

operatingHours.intervalsarray of IntervalThis container is used to define the opening and closing times of a store'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

This container is returned if operating hours are defined for the store location.

Occurrence: Required

operatingHours.intervals.closestringThe close value is actually the time that the store 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: 20:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.

This field is returned if set for the store location.

Occurrence: Required

operatingHours.intervals.openstringThe 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: 09:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.

This field is returned if set for the store location.

Occurrence: Required

phonestringAlthough not technically required, this field is highly recommended to be used to specify the phone number for a store inventory location.

Max length: 36

Occurrence: Optional

specialHoursarray of SpecialHoursThis 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.datestringA date value is required for each specific date that the store location has special operating hours. The date is actually expressed as a time stamp specified in ISO 8601 format, which uses the 24-hour Coordinated Universal Time (UTC) clock. The following examples show (1) the format of the time-stamp, and (2) an example time value in ISO 8601 format:

Format: yyyy-MM-ddThh:mm:ssZ
Example: 2016-10-19T00:09:00Z

This field is returned if set for the store location.

Occurrence: Conditional

specialHours.intervalsarray of IntervalThis container is used to define the opening and closing times of a store 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.

This container is returned if set for the store location.

Occurrence: Required

specialHours.intervals.closestringThe close value is actually the time that the store 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: 20:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.

This field is returned if set for the store location.

Occurrence: Required

specialHours.intervals.openstringThe 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: 09:00:00. This field is conditionally required if the intervals container is used to specify working hours or special hours for a store.

This field is returned if set for the store location.

Occurrence: Required

Output

HTTP response headers

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.

StatusMeaning
204No Content
400Bad Request
409Location Already Exists
500Internal Server Error

Error codes

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONSystem error. {additionalInfo}
25800API_INVENTORYREQUESTInvalid {fieldName}.
25801API_INVENTORYREQUESTMissing field {fieldName}.
25802API_INVENTORYREQUESTInput error. {additionalInfo}
25803API_INVENTORYREQUEST{fieldName} already exists.
25804API_INVENTORYREQUESTInput error. {additionalInfo}

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 location

Use this operation to configure warehouse and store locations that sellers can use to track the storage of the items in their inventory.

Input

Suppy a unique seller-defined merchantLocationKey as a path parameter in this call.
POST
https://api.ebay.com/sell/inventory/v1/location/warehouse-1

Output

There is no response body for this call.