Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
title: eBay Inventory Location API
description: The Inventory API is used to create and manage inventory, and then to publish and manage this inventory on an eBay marketplace. There are also methods in this API that will convert eligible, active eBay listings into the Inventory API model.
contact:
name: eBay Inc,
license:
name: eBay API License Agreement
url: https://go.developer.ebay.com/api-license-agreement
version: 1.17.4
servers:
- url: https://api.ebay.com{basePath}
description: Production
variables:
basePath:
default: /sell/inventory/v1
tags:
- name: Location
paths:
/location/{merchantLocationKey}:
get:
tags:
- Location
description: This call retrieves all defined details of the inventory location that is specified by the <b>merchantLocationKey</b> path parameter. <p>The <code>authorization</code> HTTP header is the only required request header for this call. </p><p>A successful call will return an HTTP status value of <i>200 OK</i>.</p>
operationId: getInventoryLocation
parameters:
- name: merchantLocationKey
in: path
description: 'This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is being retrieved. <br><br>Use the <a href="/api-docs/sell/inventory/resources/location/methods/getInventoryLocations">getInventoryLocations</a> method to retrieve merchant location keys. <br><br><b>Max length</b>: 36'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/InventoryLocationResponse'
'400':
description: Bad Request
x-response-codes:
errors:
'25804':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25805':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} Not Found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
- https://api.ebay.com/oauth/api_scope/sell.inventory
post:
tags:
- Location
description: <p>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.</p><p>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 (<i>merchantLocationKey</i>) is passed in at the end of the call URI. This <i>merchantLocationKey</i> value will be used in other Inventory Location calls to identify the inventory location to perform an action against.</p><p>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. </p><p>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 <code>DISABLED</code> in the <strong>merchantLocationStatus</strong> 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.</p><p>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 <i>204 No Content</i>.</p>
operationId: createInventoryLocation
parameters:
- name: merchantLocationKey
in: path
description: 'This path parameter specifies the unique, seller-defined key (ID) for an inventory location.<br><br><b>Max length</b>: 36'
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: Inventory Location details
content:
application/json:
schema:
description: Inventory Location details
$ref: '#/components/schemas/InventoryLocationFull'
required: true
responses:
'204':
description: No Content
'400':
description: Bad Request
x-response-codes:
errors:
'25800':
domain: API_INVENTORY
category: REQUEST
description: Invalid {fieldName}.
'25801':
domain: API_INVENTORY
category: REQUEST
description: Missing field {fieldName}.
'25802':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25803':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} already exists.'
'25804':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'409':
description: Location Already Exists
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
delete:
tags:
- Location
description: <p>This call deletes the inventory location that is specified in the <code>merchantLocationKey</code> path parameter. Note that deleting a location will not affect any active eBay listings associated with the deleted location, but the seller will not be able modify the offers associated with the inventory location once it is deleted.</p><p>The <code>authorization</code> HTTP header is the only required request header for this call. </p><p>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 <i>200 OK</i>.</p>
operationId: deleteInventoryLocation
parameters:
- name: merchantLocationKey
in: path
description: 'This path parameter specifies the unique merchant-defined key (ID) for the inventory location that is to be deleted.<br><br>Use the <a href="/api-docs/sell/inventory/resources/location/methods/getInventoryLocations">getInventoryLocations</a> method to retrieve merchant location keys.<br><br><b>Max length</b>: 36'
required: true
schema:
type: string
responses:
'204':
description: Success
'400':
description: Bad Request
x-response-codes:
errors:
'25802':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25804':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25805':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} Not Found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/location/{merchantLocationKey}/disable:
post:
tags:
- Location
description: <p>This call disables the inventory location that is specified in the <code>merchantLocationKey</code> path parameter. Sellers can not load/modify inventory to disabled inventory locations. Note that disabling an inventory location will not affect any active eBay listings associated with the disabled location, but the seller will not be able modify the offers associated with a disabled inventory location.</p><p>A successful call will return an HTTP status value of <i>200 OK</i>.</p>
operationId: disableInventoryLocation
parameters:
- name: merchantLocationKey
in: path
description: 'This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is to be disabled. <br><br>Use the <a href="/api-docs/sell/inventory/resources/location/methods/getInventoryLocations">getInventoryLocations</a> method to retrieve merchant location keys.<br><br><b>Max length</b>: 36'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'400':
description: Bad Request
x-response-codes:
errors:
'25802':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25804':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25805':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} Not Found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/location/{merchantLocationKey}/enable:
post:
tags:
- Location
description: <p>This call enables a disabled inventory location that is specified in the <code>merchantLocationKey</code> path parameter. Once a disabled inventory location is enabled, sellers can start loading/modifying inventory to that inventory location. </p><p>A successful call will return an HTTP status value of <i>200 OK</i>.</p>
operationId: enableInventoryLocation
parameters:
- name: merchantLocationKey
in: path
description: 'This path parameter specifies unique merchant-defined key (ID) for a <code>disabled</code> inventory location that is to be enabled.<br><br>Use the <a href="/api-docs/sell/inventory/resources/location/methods/getInventoryLocations">getInventoryLocations</a> method to retrieve merchant location keys.<br><br><b>Max length</b>: 36'
required: true
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
type: object
'400':
description: Bad Request
x-response-codes:
errors:
'25802':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25804':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25805':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} Not Found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
/location:
get:
tags:
- Location
description: 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, <strong>limit</strong> and <strong>offset</strong>. The <strong>limit</strong> query parameter sets the maximum number of inventory locations returned on one page of data, and the <strong>offset</strong> query parameter specifies the page of data to return. These query parameters are discussed more in the <strong>URI parameters</strong> table below. <p>The <code>authorization</code> HTTP header is the only required request header for this call. </p><p>A successful call will return an HTTP status value of <i>200 OK</i>.</p>
operationId: getInventoryLocations
parameters:
- name: limit
in: query
description: 'The 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. <br><br> <strong>Min</strong>: 1'
required: false
schema:
type: string
- name: offset
in: query
description: Specifies the number of locations to skip in the result set before returning the first location in the paginated response. <p>Combine <b>offset</b> with the <b>limit</b> query parameter to control the items returned in the response. For example, if you supply an <b>offset</b> of <code>0</code> and a <b>limit</b> of <code>10</code>, the first page of the response contains the first 10 items from the complete list of items retrieved by the call. If <b>offset</b> is <code>10</code> and <b>limit</b> is <code>20</code>, the first page of the response contains items 11-30 from the complete result set.</p> <p><b>Default:</b> 0</p>
required: false
schema:
type: string
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/LocationResponse'
'400':
description: Bad Request
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory.readonly
- https://api.ebay.com/oauth/api_scope/sell.inventory
/location/{merchantLocationKey}/update_location_details:
post:
tags:
- Location
description: '<p>Use this call to update non-physical location details for an existing inventory location. Specify the inventory location you want to update using the <b>merchantLocationKey</b> path parameter. <br><br>You can update the following text-based fields: <strong>name</strong>, <strong>phone</strong>, <strong>locationWebUrl</strong>, <strong>locationInstructions</strong> and <strong>locationAdditionalInformation</strong>. Whatever text is passed in for these fields in an <strong>updateInventoryLocation</strong> call will replace the current text strings defined for these fields. For store inventory locations, the operating hours and/or the special hours can also be updated. <br><br> The merchant location key, the physical location of the store, and its geo-location coordinates can not be updated with an <strong>updateInventoryLocation</strong> call </p><p>Unless one or more errors and/or warnings occurs with the call, there is no response payload for this call. A successful call will return an HTTP status value of <i>204 No Content</i>.</p>'
operationId: updateInventoryLocation
parameters:
- name: merchantLocationKey
in: path
description: 'This path parameter specifies the unique merchant-defined key (ID) for an inventory location that is to be updated. <br><br>Use the <a href="/api-docs/sell/inventory/resources/location/methods/getInventoryLocations">getInventoryLocations</a> method to retrieve merchant location keys. <br><br><b>Max length</b>: 36'
required: true
schema:
type: string
- name: Content-Type
in: header
description: This header indicates the format of the request body provided by the client. Its value should be set to <b>application/json</b>. <br><br> For more information, refer to <a href="/api-docs/static/rest-request-components.html#HTTP" target="_blank ">HTTP request headers</a>.
required: true
schema:
type: string
requestBody:
description: The inventory location details to be updated (other than the address and geo co-ordinates).
content:
application/json:
schema:
description: The inventory location details to be updated (other than the address and geo co-ordinates).
$ref: '#/components/schemas/InventoryLocation'
required: true
responses:
'204':
description: Success
'400':
description: Bad Request
x-response-codes:
errors:
'25800':
domain: API_INVENTORY
category: REQUEST
description: Invalid {fieldName}.
'25801':
domain: API_INVENTORY
category: REQUEST
description: Missing field {fieldName}.
'25802':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25804':
domain: API_INVENTORY
category: REQUEST
description: Input error. {additionalInfo}
'25805':
domain: API_INVENTORY
category: REQUEST
description: '{fieldName} Not Found.'
'404':
description: Not Found
'500':
description: Internal Server Error
x-response-codes:
errors:
'25001':
domain: API_INVENTORY
category: APPLICATION
description: System error. {additionalInfo}
security:
- api_auth:
- https://api.ebay.com/oauth/api_scope/sell.inventory
components:
schemas:
GeoCoordinates:
type: object
properties:
latitude:
type: number
description: The latitude (North-South) component of the geographic coordinate. This field is required if a <strong>geoCoordinates</strong> container is used. <br><br>For In-Store Pickup inventory, geographical coordinates are required.<br><br>This field is returned if geographical coordinates are set for the inventory location.
longitude:
type: number
description: The longitude (East-West) component of the geographic coordinate. This field is required if a <strong>geoCoordinates</strong> container is used. <br><br>For In-Store Pickup inventory, geographical coordinates are required.<br><br>This field is returned if geographical coordinates are set for the inventory location.
description: This type is used to express the Global Positioning System (GPS) latitude and longitude coordinates of an inventory location.
Address:
type: object
properties:
addressLine1:
type: string
description: '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.<br><br>This field will be returned if defined for an inventory location. <br><br><b>Max length</b>: 128'
addressLine2:
type: string
description: '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.<br><br>This field will be returned if defined for an inventory location. <br><br><b>Max length</b>: 128'
city:
type: string
description: '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 <strong>postalCode</strong> can be used instead of <strong>city</strong>/<strong>stateOrProvince</strong> pair, and then the city is just derived from this postal/zip code.<br><br>This field is returned if defined for an inventory location. <br><br><b>Max length</b>: 128'
country:
type: string
description: The country in which the address resides, represented as two-letter <a href="https://www.iso.org/iso-3166-country-codes.html " title="https://www.iso.org " target="_blank">ISO 3166</a> country code. For example, <code>US</code> represents the United States, and <code>DE</code> represents Germany. For implementation help, refer to <a href='https://developer.ebay.com/api-docs/sell/inventory/types/ba:CountryCodeEnum'>eBay API documentation</a>
county:
type: string
description: The county in which the address resides.<br><br>This field is returned if defined for an inventory location.
postalCode:
type: string
description: '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 <strong>city</strong>/<strong>stateOrProvince</strong> pair can be used instead of a <strong>postalCode</strong> value, and then the postal code is just derived from the city and state/province.<br><br>This field is returned if defined for an inventory location. <br><br><b>Max length</b>: 16'
stateOrProvince:
type: string
description: '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 <strong>postalCode</strong> can be used instead of <strong>city</strong>/<strong>stateOrProvince</strong> pair, and then the state or province is just derived from this postal/zip code. <br><br><b>Max length</b>: 128'
description: This type is used to define the physical address of an inventory location.
LocationResponse:
type: object
properties:
href:
type: string
description: The URI of the current page of results from the result set.
limit:
type: integer
description: The number of items returned on a single page from the result set.
format: int32
next:
type: string
description: '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. <br><br><b>Max length</b>: 2048'
offset:
type: integer
description: 'The number of results skipped in the result set before listing the first returned result. This value is set in the request with the <b>offset</b> query parameter. <p class="tablenote"><strong>Note: </strong>The items in a paginated result set use a zero-based list where the first item in the list has an offset of <code>0</code>.</p>'
format: int32
prev:
type: string
description: '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. <br><br><b>Max length</b>: 2048'
total:
type: integer
description: The total number of items retrieved in the result set. <br><br>If no items are found, this field is returned with a value of <code>0</code>.
format: int32
locations:
type: array
description: An array of one or more of the merchant's inventory locations.
items:
$ref: '#/components/schemas/InventoryLocationResponse'
description: This type is used by the base response payload for the <strong>getInventoryLocations</strong> call.
InventoryLocation:
type: object
properties:
locationAdditionalInformation:
type: string
description: 'This text field is used by the merchant to provide/update additional information about an inventory location. Whatever text is passed in this field will replace the current text string defined for this field. If the text will not change, the same text should be passed in once again. <br><br><b>Max length</b>: 256'
locationInstructions:
type: string
description: 'This text field is generally used by the merchant to provide/update 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). Whatever text is passed in this field will replace the current text string defined for this field. If the text will not change, the same text should be passed in once again. <br><br><b>Max length</b>: 1000'
locationWebUrl:
type: string
description: 'This text field is used by the merchant to provide/update the Website address (URL) associated with the inventory location. The URL that is passed in this field will replace any other URL that may be defined for this field. <br><br><b>Max length</b>: 512'
name:
type: string
description: This text field is used by the merchant to update the name of the inventory location. This name should be a human-friendly name as it will be 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 omitted this field in the <strong>createInventoryLocation</strong> call, it is required for an <strong>updateInventoryLocation</strong> call. The name that is passed in this field will replace any other name that may be defined for this field.
operatingHours:
type: array
description: This container is used to provide/update the regular operating hours for a store location during the days of the week. A <strong>dayOfWeekEnum</strong> field and an <strong>intervals</strong> container will be needed for each day of the week that the store location is open. Note that if operating hours are already set for an inventory location for a specific day of the week, whatever is set through an <strong>updateInventoryLocation</strong> call will override those existing hours.
items:
$ref: '#/components/schemas/OperatingHours'
phone:
type: string
description: 'This text field is used by the merchant to provide/update the phone number for the inventory location. The phone number that is passed in this field will replace any other phone number that may be defined for this field. <br><br><b>Max length</b>: 36'
specialHours:
type: array
description: This container is used to provide/update the special operating hours for a store 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. If special hours have already been set up for an inventory location, specifying special hours through an <strong>updateInventoryLocation</strong> call will only add to the list, unless the date(s) used are the same special date(s) already set up, in which case, the special hours set up through the <strong>updateInventoryLocation</strong> call will override the existing special hours.
items:
$ref: '#/components/schemas/SpecialHours'
description: This type is used by the <strong>updateInventoryLocation</strong> call to update operating hours, special hours, phone number, and other minor details of an inventory location.
LocationDetails:
type: object
properties:
address:
description: The <b>address</b> container is required for a <b>createInventoryLocation</b> 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.
$ref: '#/components/schemas/Address'
geoCoordinates:
description: This container is used to set the Global Positioning System (GPS) latitude and longitude coordinates for the inventory location.<br><br>Geographical coordinates are required for the location of In-Store Pickup inventory.
$ref: '#/components/schemas/GeoCoordinates'
description: This type is used by the <b>createInventoryLocation</b> call to provide an full or partial address of an inventory location.
Location:
type: object
properties:
address:
description: The <strong>address</strong> container is always returned in <strong>getInventoryLocation</strong>/<strong>getInventoryLocations</strong> 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.
$ref: '#/components/schemas/Address'
geoCoordinates:
description: 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.
$ref: '#/components/schemas/GeoCoordinates'
locationId:
type: string
description: A unique eBay-assigned ID for the location. <br><br> <span class="tablenote"> <strong>Note:</strong> This field should not be confused with the seller-defined <b>merchantLocationKey</b> value. It is the <b>merchantLocationKey</b> value which is used to identify an inventory location when working with inventory location API calls. The <strong>locationId</strong> value is only used internally by eBay.</span>
description: A complex type that is used to provide the physical address of a location, and it geo-coordinates.
InventoryLocationResponse:
type: object
properties:
location:
description: This container provides location details of an inventory location. The <strong>address</strong> container will always be returned, but it will not always have a complete street address. Exc
# --- truncated at 32 KB (47 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/ebay/refs/heads/main/openapi/ebay-location-api-openapi.yml