Skip to main content

GET/location

This call retrieves all defined details for every inventory location associated with the seller's account. There are no required parameters for this call and no request payload. However, there are two optional query parameters, limit and offset. The limit query parameter sets the maximum number of inventory locations returned on one page of data, and the offset query parameter specifies the page of data to return. These query parameters are discussed more in the URI parameters table below.

The authorization HTTP header is the only required request header for this call.

A successful call will return an HTTP status value of 200 OK.

Input

Resource URI

GET https://api.ebay.com/sell/inventory/v1/location?

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

ParameterTypeDescription
offsetintegerSpecifies the number of locations to skip in the result set before returning the first location in the paginated response.

Combine offset with the limit query parameter to control the items returned in the response. For example, if you supply an offset of 0 and a limit of 10, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If offset is 10 and limit is 20, the first page of the response contains items 11-30 from the complete result set.

Default: 0

Occurrence: Optional

limitintegerThe value passed in this query parameter sets the maximum number of records to return per page of data. Although this field is a string, the value passed in this field should be a positive integer value. If this query parameter is not set, up to 100 records will be returned on each page of results.

Min: 1

Occurrence: Optional

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

All other standard RESTful request headers are optional. For more information on standard RESTful request headers, see the HTTP request headers- opens rest request components page table.

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.readonly

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

See OAuth access tokens for more information.

Request payload

This call has no payload.

Request fields

This call has no field definitions.

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
hrefstring

The URI of the current page of results from the result set.

Occurrence: Conditional

limitinteger

The number of items returned on a single page from the result set.

Occurrence: Conditional

nextstring

The URI for the following page of results. This value is returned only if there is an additional page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

offsetinteger

The number of results skipped in the result set before listing the first returned result. This value is set in the request with the offset query parameter.

Note: The items in a paginated result set use a zero-based list where the first item in the list has an offset of 0.

Occurrence: Conditional

prevstring

The URI for the preceding page of results. This value is returned only if there is a previous page of results to display from the result set.

Max length: 2048

Occurrence: Conditional

totalinteger

The total number of items retrieved in the result set.

If no items are found, this field is returned with a value of 0.

Occurrence: Conditional

locationsarray of InventoryLocationResponse

An array of one or more of the merchant's inventory locations.

Occurrence: Conditional

locations.locationLocation

This container provides location details of an inventory location. The address container will always be returned, but it will not always have a complete street address. 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. The geoCoordinates container will only be returned if the merchant provided geographical coordinates. The locationId field is always returned, but this value is only used internally by eBay.

Occurrence: Always

locations.location.addressAddress

The address container is always returned in getInventoryLocation/getInventoryLocations calls. 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: Always

locations.location.address.addressLine1string

The 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

locations.location.address.addressLine2string

The 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

locations.location.address.citystring

The 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

locations.location.address.countryCountryCodeEnum

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

Occurrence: Always

locations.location.address.countystring

The county in which the address resides.

This field is returned if defined for an inventory location.

Occurrence: Conditional

locations.location.address.postalCodestring

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 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

locations.location.address.stateOrProvincestring

The 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: Always

locations.location.geoCoordinatesGeoCoordinates

This container displays the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location. This container is only returned if the geo-coordinates are set for an inventory location.

Occurrence: Conditional

locations.location.geoCoordinates.latitudenumber

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

For In-Store Pickup inventory, geographical coordinates are required.

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

Occurrence: Conditional

locations.location.geoCoordinates.longitudenumber

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

For In-Store Pickup inventory, geographical coordinates are required.

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

Occurrence: Conditional

locations.location.locationIdstring

A unique eBay-assigned ID for the location.

Note: This field should not be confused with the seller-defined merchantLocationKey value. It is the merchantLocationKey value which is used to identify an inventory location when working with inventory location API calls. The locationId value is only used internally by eBay.

Occurrence: Always

locations.locationAdditionalInformationstring

This text field provides additional information about an inventory location. This field is returned if it is set for the inventory location.

Max length: 256

Occurrence: Conditional

locations.locationInstructionsstring

This text field is used by the merchant to provide special pickup instructions for the store location. This field can help create a pleasant and easy pickup experience for In-Store Pickup and Click and Collect orders. If this field was not set up through a createInventoryLocation or a updateInventoryLocation call, eBay will use the default pickup instructions contained in the merchant's profile.

Max length: 1000

Occurrence: Conditional

locations.locationTypesarray of StoreTypeEnum

This container defines 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.

For In-Store Pickup inventory set StoreTypeEnum to STORE.

The location type of an inventory location defaults to WAREHOUSE if a location type is not specified when a merchant creates an inventory location.

Occurrence: Always

locations.locationWebUrlstring

This text field shows the Website address (URL) associated with the inventory location. This field is returned if defined for the inventory location.

Max length: 512

Occurrence: Conditional

locations.merchantLocationKeystring

The unique identifier of the inventory location. This identifier is set up by the merchant when the inventory location is first created with the createInventoryLocation call. Once this value is set for an inventory location, it cannot be modified.

Max length: 36

Occurrence: Always

locations.merchantLocationStatusStatusEnum

This field indicates whether the inventory location is enabled (inventory can be loaded to location) or disabled (inventory can not be loaded to location). The merchant can use the enableInventoryLocation call to enable an inventory location in disabled status, or the disableInventoryLocation call to disable an inventory location in enabled status.

Occurrence: Always

locations.namestring

The 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. For store inventory locations, this field is not required for the createInventoryLocation call, but a store inventory location must have a defined name value before an In-Store Pickup and Click and Collect enabled offer is published. So, if the seller omits this field in the createInventoryLocation call, it will have to be added later through a updateInventoryLocation call.

Max length: 1000

Occurrence: Conditional

locations.operatingHoursarray of OperatingHours

This container shows the regular operating hours for a store location during the days of the week. A dayOfWeekEnum field and an intervals container is shown for each day of the week that the store location is open.

Occurrence: Conditional

locations.operatingHours.dayOfWeekEnumDayOfWeekEnum

A 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: Conditional

locations.operatingHours.intervalsarray of Interval

This 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: Conditional

locations.operatingHours.intervals.closestring

The 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: Conditional

locations.operatingHours.intervals.openstring

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: 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: Conditional

locations.phonestring

The phone number for an inventory location. This field will typically only be set and returned for store locations.

Max length: 36

Occurrence: Always

locations.specialHoursarray of SpecialHours

This container shows the special operating hours for a store location on a specific date or dates.

Occurrence: Conditional

locations.specialHours.datestring

A date value is required for each specific date that the store location has special operating hours.

The timestamp is formatted as an ISO 8601 string, which is based on the 24-hour Coordinated Universal Time (UTC) clock.

Format: [YYYY]-[MM]-[DD]T[hh]:[mm]:[ss].[sss]Z
Example: 2018-08-04T07:09:00.000Z

This field is returned if set for the store location.

Occurrence: Conditional

locations.specialHours.intervalsarray of Interval

This 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: Conditional

locations.specialHours.intervals.closestring

The 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: Conditional

locations.specialHours.intervals.openstring

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: 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: Conditional

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
200Success
400Bad Request
500Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONSystem 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: Get all Fulfillment Policies

Sellers can create one or more inventory locations. This call returns all the locations that have been set up by the seller.

Input

This call does not use a request payload.

GEThttps://api.ebay.com/sell/inventory/v1/location

Output

If the call is successful, eBay returns an HTTP status code of 200 OK and a list of the seller locations.