Multi-warehouse program | eBay Developers Program

When using the default warehouse inventory location type, eBay calculates and displays estimated delivery dates based on the inventory location provided on a listing. For sellers with multiple locations, however, this is not always accurate as they are able to deliver items faster than the estimated delivery date, which is calculated based on a single location.

By utilizing the fulfillment center location type and the location mapping methods of the Inventory API, sellers can map the location metadata for multiple inventory locations to a one or more SKUs within a listing, allowing them to see improved delivery estimates on their listings though the Multi-warehouse program.

Note: Estimated Delivery Date (EDD) is calculated based on the handling time specified during listing creation, as well as the estimated transit time calculated from the fulfillment center location.

Requirements

The flow for utilizing the improved EDD through the Multi-warehouse program is similar to regular inventory flow (see From inventory item to eBay marketplace offer), but has a few specific requirements. Note that the steps are the same for single-SKU and multi-SKU items, but the location mapping methods must be called for each individual SKU in a multi-SKU listing.

The steps are as follows:

Create a fulfillment center location
Create and publish a listing
Map fulfillment center locations to a listing

Important! While location mappings can be created for listings on any eBay marketplace, the improved delivery date estimate feature only considers US-based fulfillment centers shipping domestically.

Create a fulfillment center location

In order to integrate with these new methods to see improved EDD on listings, sellers must first create fulfillment center locations to map to SKUs within their listings. Fulfillment center locations can be created by using the createInventoryLocation method of the Inventory API.

The following information is required for the creation of a fulfillment center location:

A complete address (addressLine1, city, stateOrProvince, postalCode, and country)
The fulfillment center's shipping specifications (fulfillmentCenterSpecifications), including the following:
- weeklySchedule - Specifies the weekly schedule for shipping and handling cut-off times. A cutOffTime is required for each business day (specified through the DayOfWeekEnum) that the fulfillment center operates. Any orders made after the specified cut-off time on the specified day(s) of the week will be handled on the next day.
- overrides (optional) - Can be used to override the existing cut-off times specified in the weeklySchedule container for a specific date or date range.

In addition, the locationTypes container must have FULFILLMENT_CENTER as one of its location types.

Note: Warehouse locations can be updated to fulfillment locations using the updateInventoryLocation method if they adhere to the above requirements.

See the Create a fulfillment center location sample for examples of the required fields needed to create a fulfillment center location.

Create and publish a listing

As location mapping is an extra step after publishing an offer, and not part of the existing flow, a listing must be created and published before these methods can be used.

For more information on creating and publishing a listing through the Inventory API, see From inventory item to eBay marketplace offer in the Selling Integration Guide.

For more information on creating and publishing listings through the Trading API, see Create item listings in the Trading user guide.

Map fulfillment center locations to a listing

After creating fulfillment center locations and publishing a listing, sellers can use the createOrReplaceSkuLocationMapping method to map multiple locations to a specific SKU within a listing.

Note: Sellers using listings created through the Trading API can add SKU values to a single-SKU listing though the Item.SKU field during listing creation or by using the ReviseItem family of calls.

When using this method, the listingId and sku associated with the active listing must be provided as path parameters. The locations the seller wishes to associate with the SKU must then be provided in the locations container in the request body. These locations are specified through the merchantLocationKey field(s), which is defined during the createInventoryLocation process and can be retrieved through the getInventoryLocations method.

Important! This method will need to be used for each individual SKU that the seller wants to update.

SKU values can be updated by a seller at any time. If a seller updates a SKU value that is being used for location mapping, this change will not be reflected until the mapping is updated through the createOrReplaceSkuLocationMapping method.

CreateSkuLocationMapping example request payload

PUT https://api.ebay.com/sell/inventory/v1/listing/{listingId}/sku/{sku}/locations
			
			{
			"locations" : [
			{
			"merchantLocationKey" : "locationKey1"
			},
			{
			"merchantLocationKey" : "locationKey2"
			}
			]
			}

Note: Only the first 50 locations mapped to a listing will be considered when calculating estimated delivery dates. Sellers can set up more than 50 locations using these methods, but only the first 50 locations will be considered for calculating the estimates.

In the case of replacing/updating existing location mappings, the createOrReplaceSkuLocationMapping method will do a complete replacement of the location mappings associated with a SKU. This means that each existing location mappings that the seller wants to continue to associate with the SKU are required in the update call, regardless of if they are affected by the update.

Retrieving the fulfillment center locations mapped to a listing

The location(s) mapped to a SKU value can be retrieved using the getSkuLocationMapping method. The fulfillment center being retrieved can be identified with the listingId and sku path parameters associated with the mapping.

A successful call will return a response body listing the fulfillment center locations mapped to a SKU.

Removing fulfillment center locations mapped to a listing

If a seller wishes to disassociate locations mapped to a SKU within a listing, they can remove the location mapping from the SKU using the deleteSkuLocationMapping method. This method disassociates all locations mapped to the SKU. The location mapping being removed is identified with the listingId and sku path parameters associated with the mapping.

Important! If a seller wishes to disassociate location mappings for all SKUs within a multiple-SKU listing, this method must be used for each individual SKU in the listing.

A successful call removes and deletes all location mappings from a SKU.