Skip to main content

POST/bulk_migrate_listing

This call is used to convert existing eBay Listings to the corresponding Inventory API objects. If an eBay listing is successfully migrated to the Inventory API model, new Inventory Location, Inventory Item, and Offer objects are created. For a multiple-variation listing that is successfully migrated, in addition to the three new Inventory API objects just mentioned, an Inventory Item Group object will also be created. If the eBay listing is a motor vehicle part or accessory listing with a compatible vehicle list (ItemCompatibilityList container in Trading API's Add/Revise/Relist/Verify calls), a Product Compatibility object will be created.

Migration Requirements


To be eligible for migration, the active eBay listings must meet the following requirements:
  • Listing type is Fixed-Price

    Note: Auction listings are supported by the Inventory API, but the bulkMigrateListing method cannot be used to migrate auction listings.

  • The item(s) in the listings must have seller-defined SKU values associated with them, and in the case of a multiple-variation listing, each product variation must also have its own SKU value
  • Business Polices (Payment, Return Policy, and Shipping) must be used on the listing, as legacy payment, return policy, and shipping fields will not be accepted. With the Payment Policy associated with a listing, the immediate payment requirement must be enabled.
  • The postal/zip code (PostalCode field in Trading's ItemType) or city (Location field in Trading's ItemType) must be set in the listing; the country is also needed, but this value is required in Trading API, so it will always be set for every listing

Unsupported Listing Features


The following features are not yet available to be set or modified through the Inventory API, but they will remain on the active eBay listing, even after a successful migration to the Inventory model. The downside to this is that the seller will be completely blocked (in APIs or My eBay) from revising these features/settings once the migration takes place:
  • Any listing-level Buyer Requirements
  • Listing enhancements like a bold listing title or Gallery Plus

Making the Call


In the request payload of the bulkMigrateListings call, the seller will pass in an array of one to five eBay listing IDs (aka Item IDs). To save time and hassle, that seller should do a pre-check on each listing to make sure those listings meet the requirements to be migrated to the new Inventory model. This method also requires the Content-Type request header. See the HTTP request headers for more information. There are no path or query parameters for this call.

Call Response


If an eBay listing is migrated successfully to the new Inventory model, the following will occur:
  • An Inventory Item object will be created for the item(s) in the listing, and this object will be accessible through the Inventory API
  • An Offer object will be created for the listing, and this object will be accessible through the Inventory API
  • An Inventory Location object will be created and associated with the Offer object, as an Inventory Location must be associated with a published Offer
The response payload of the Bulk Migrate Listings call will show the results of each listing migration. These results include an HTTP status code to indicate the success or failure of each listing migration, the SKU value associated with each item, and if the migration is successful, an Offer ID value. The SKU value will be used in the Inventory API to manage the Inventory Item object, and the Offer ID value will be used in the Inventory API to manage the Offer object. Errors and/or warnings containers will be returned for each listing where an error and/or warning occurred with the attempted migration.

If a multiple-variation listing is successfully migrated, along with the Offer and Inventory Location objects, an Inventory Item object will be created for each product variation within the listing, and an Inventory Item Group object will also be created, grouping those variations together in the Inventory API platform. For a motor vehicle part or accessory listing that has a specified list of compatible vehicles, in addition to the Inventory Item, Inventory Location, and Offer objects that are created, a Product Compatibility object will also be created in the Inventory API platform.

Input

Resource URI

POST https://api.ebay.com/sell/inventory/v1/bulk_migrate_listing

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

This method has no URI parameters.

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.

HeaderTypeDescription
Content-TypestringThis 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 clipboard

Request fields

Input container/fieldTypeDescription
requestsarray of MigrateListing

This is the base container of the bulkMigrateListings request payload. One to five eBay listings will be included under this container.

Occurrence: Required

requests.listingIdstring

The unique identifier of the eBay listing to migrate to the new Inventory model. In the Trading API, this field is known as the ItemID.

Up to five unique eBay listings may be specified here in separate listingId fields. The seller should make sure that each of these listings meet the requirements that are stated at the top of this Call Reference page.

Occurrence: Required

Output

HTTP response headers

This call has no response headers.

Response payload

Response fields

Output container/fieldTypeDescription
responsesarray of MigrateListingResponse

This is the base container of the response payload of the bulkMigrateListings call. The results of each attempted listing migration is captured under this container.

Occurrence: Always

responses.errorsarray of ErrorDetailV3

If one or more errors occur with the attempt to migrate the listing, this container will be returned with detailed information on each error.

Occurrence: Conditional

responses.errors.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

responses.errors.domainstring

The name of the domain in which the error or warning occurred.

Occurrence: Conditional

responses.errors.errorIdinteger

A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

responses.errors.inputRefIdsarray of string

An array of one or more reference IDs which identify the specific request element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

responses.errors.longMessagestring

A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

responses.errors.messagestring

A description of the condition that caused the error or warning.

Occurrence: Conditional

responses.errors.outputRefIdsarray of string

An array of one or more reference IDs which identify the specific response element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

responses.errors.parametersarray of ErrorParameterV3

Various warning and error messages return one or more variables that contain contextual information about the error or waring. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

responses.errors.parameters.namestring

This type contains the name and value of an input parameter that contributed to a specific error or warning condition.

Occurrence: Conditional

responses.errors.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

responses.errors.subdomainstring

The name of the subdomain in which the error or warning occurred.

Occurrence: Conditional

responses.inventoryItemGroupKeystring

This field will only be returned for a multiple-variation listing that the seller attempted to migrate. Its value is auto-generated by eBay. For a multiple-variation listing that is successfully migrated to the new Inventory model, eBay automatically creates an inventory item group object for the listing, and the seller will be able to retrieve and manage that new inventory item group object by using the value in this field.

Occurrence: Conditional

responses.inventoryItemsarray of InventoryItemListing

This container exists of an array of SKU values and offer IDs. For single-variation listings, this will only be one SKU value and one offer ID (if listing was successfully migrated), but multiple SKU values and offer IDs will be returned for multiple-variation listings.

Occurrence: Always

responses.inventoryItems.offerIdstring

Upon a successful migration of a listing, eBay auto-generates this unique identifier, and this offer ID value will be used to retrieve and manage the newly-created offer object. This value will only be generated and returned if the eBay listing is migrated successfully.

Occurrence: Conditional

responses.inventoryItems.skustring

This is the seller-defined SKU value associated with the item(s) in a listing. This same SKU value will be used to retrieve and manage the newly-created inventory item object if the listing migration is successful. This SKU value will get returned even if the migration is not successful.

Occurrence: Always

responses.listingIdstring

The unique identifier of the eBay listing that the seller attempted to migrate.

Occurrence: Always

responses.marketplaceIdMarketplaceEnum

This is the unique identifier of the eBay Marketplace where the listing resides. The value fo the eBay US site will be EBAY_US.

Occurrence: Always

responses.statusCodeinteger

This field is returned for each listing that the seller attempted to migrate. See the HTTP status codes table to see which each status code indicates.

Occurrence: Always

responses.warningsarray of ErrorDetailV3

If one or more warnings occur with the attempt to migrate the listing, this container will be returned with detailed information on each warning. It is possible that a listing can be successfully migrated even if a warning occurs.

Occurrence: Conditional

responses.warnings.categorystring

This string value indicates the error category. There are three categories of errors: request errors, application errors, and system errors.

Occurrence: Conditional

responses.warnings.domainstring

The name of the domain in which the error or warning occurred.

Occurrence: Conditional

responses.warnings.errorIdinteger

A unique code that identifies the particular error or warning that occurred. Your application can use error codes as identifiers in your customized error-handling algorithms.

Occurrence: Conditional

responses.warnings.inputRefIdsarray of string

An array of one or more reference IDs which identify the specific request element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

responses.warnings.longMessagestring

A detailed description of the condition that caused the error or warning, and information on what to do to correct the problem.

Occurrence: Conditional

responses.warnings.messagestring

A description of the condition that caused the error or warning.

Occurrence: Conditional

responses.warnings.outputRefIdsarray of string

An array of one or more reference IDs which identify the specific response element(s) most closely associated to the error or warning, if any.

Occurrence: Conditional

responses.warnings.parametersarray of ErrorParameterV3

Various warning and error messages return one or more variables that contain contextual information about the error or waring. This is often the field or value that triggered the error or warning.

Occurrence: Conditional

responses.warnings.parameters.namestring

This type contains the name and value of an input parameter that contributed to a specific error or warning condition.

Occurrence: Conditional

responses.warnings.parameters.valuestring

This is the actual value that was passed in for the element specified in the name field.

Occurrence: Conditional

responses.warnings.subdomainstring

The name of the subdomain in which the error or warning occurred.

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
207Multi-Status
400Bad Request
500Internal Server Error

Error codes

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

CodeDomainCategoryMeaning
25001API_INVENTORYAPPLICATIONAny System error. {additionalInfo}
25718API_INVENTORYREQUESTCannot migrate listing. {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: Bulk Migrate Listings

This call will migrate three active eBay listings to the new Inventory model. The eBay listings will remain active, and new objects will be created in the Inventory API so the items and associated offers can be managed with the Inventory API.

Input

This call will attempt to update three active listings on the eBay US site. There are no URL or query parameters for this call, and the eBay listing IDs (also known as Item IDs) are passed in under the requests container in the request payload.

POSThttps://api.ebay.com/sell/inventory/v1/bulk_migrate_listing

Output

As you can see in the output, there were three different results for the three eBay listing IDs that were passed into the request payload.

The 1**********1 listing is actually a multiple-variation listing, and based on the statusCode value of 200 and the absence of any error or warning messages, all four product variations were successfully migrated to the new Inventory model. An Inventory Item object was created for each of the four SKUs, and these four Inventory Item objects will all be identified with their SKU values. An Offer object was also created for each of the four variations, and these four Offer objects will all be identified with their offerId values. Finally, one Inventory Item Group object was created for this group of variations, and this object will be identified with its inventoryItemGroupKey value - dress_shirt_3.

The 1**********2 listing is a single-variation listing, and based on the statusCode value of 200 and the absence of any error or warning messages, this listing was also successfully migrated to the new Inventory model. An Inventory Item object was created for this SKU, and this Inventory Item object will be identified with its SKU value. An Offer object was also created for this listing, and this Offer object will be identified with the offerId value.

The attempted migration of the 1**********3 listing failed, as indicated by the statusCode value of 400, which indiates a Bad Request. The message field under the errors container indicates the migration failed because the eBay listing did not have a defined SKU value. To resolve this problem, the seller would have to make a ReviseFixedPriceItem call (Trading API) to add a SKU value to the listing, and then the seller could attempt the migration once more.