Large Merchant Services

Large Merchant Services Users Guide

eBay's Large Merchant Services make it possible for a Seller's application to send very large amounts of inventory to the eBay site, and to download single and multiple line item order information. These services have been designed to make a large merchant's workflow more efficient by leveraging eBay infrastructure to use parallel execution and to automatically retry on errors.

Advantages of Using Large Merchant Services:

This document gives you an overview of eBay's Large Merchant Services, explains how the three core APIs interact, and describes how to use each API.

Table of Contents

Large Merchant Services Overview

The Large Merchant Services solution provides several APIs for inventory management and reporting. You may also use other APIs (such as the Trading API) to complete your overall large merchant solution.

This solution also introduces an option to identify each eBay listing by using the seller's own SKU instead of eBay's Item ID. See Inventory Tracking by SKU.

Large Merchant Services APIs

The Large Merchant Services solution consists of three main APIs:

Merchant Data API (data file)

This API defines the data and reports that can be passed to or retrieved from the eBay servers within data files. The Merchant Data API calls are defined on the Merchant Data API Reference page. You will notice that some of these calls are listed as 'Related' calls because they are used by both the Merchant Data and Trading APIs, and they are defined in the Trading API Reference.

When you make a Merchant Data call, you will create a data file that contains multiple instances of the same call within the file - each instance will have information about a specific item or product. Each data file can only contain one type of call. For instance, all AddFixedPriceItem calls can be in the same data file, but this file cannot contain both AddFixedPriceItem and ReviseFixedPriceItem calls.

This is the data about your listings (to upload, revise, and manage items in your inventory). The requests and responses are similar to those you may already be familiar with from the eBay Trading API. Most of the Merchant Data API calls cannot be used to make direct API calls (without a data file) to the eBay servers. However, you can use the 'Related' calls that are defined in the Trading API to make either direct Trading API calls (for single items) or to include within a data file to make Merchant Data API calls (for multiple items).

This API introduces the concept of 'reports' and describes the data that is returned when you request one of these pre-defined call responses. Reports provide inventory management information, such as a list of your sold items or active inventory.

Bulk Data Exchange API (API)

This API describes how to manage the Large Merchant workflow, such as starting, stopping, and checking the status of data processing. This API introduces the concept of a 'job', which is a unit of work that is processed asynchoronously. Because we are processing the data asynchronously (to accomodate large amounts of data) you must download responses when the processing is done.

File Transfer API (API)

This API service passes the data file to and from the eBay servers.

For more information about each of these APIs, see Large Merchant Services API References.

For details about making calls using supported methods and formats, see Making an API Call.

Service Interaction Overview

The following diagram illustrates how calls from these three APIs are used together in the context of the Large Merchant Services solution. The Merchant Data calls are specified within the uploaded and downloaded files, which are attached to File Transfer calls. Bulk Data Exchange calls interact with the eBay servers to manage the jobs (and the data processing for those jobs) that flow to and from the eBay servers. You may need to make calls to eBay's Trading API to determine which category ID is right for your item, or to revise the quantity or price of your eBay inventory. You can use eBay's existing Platform Notification API (a sub-section of the Trading API) if you want to receive email when job processing is complete.

This solution is designed to support merchants who need to manage thousands or tens of thousands (or possibly hundreds of thousands) of eBay listings at one time. This document will discuss how you can use the three APIs to build an application that meets your large merchant needs.

Use Cases

If you already have large quantities of listings on the eBay site, you might start using the Large Merchant Services solution with calls that revise items or inventory instead of adding all of your items in a massive bulk upload. Likewise, you might begin by downloading order reports and working on large order fulfillment before you begin to add or revise items. The following sections explain some of the most common use cases for the Large Merchant Services solution.

If you are trying to do something other than what's reflected in these use cases (like uploading 10 or 20 items at once), you may want to use a different eBay solution.

Large Merchants Who Are New to eBay

You work for an extremely large corporation, and the managers have just proposed that you put your company's inventory on the eBay site to increase your web visibility and online sales.

You have separate catalogs for clothing, hardware, housewares, and electronics. You have 150 separate types of items in your clothing catalog, such as shirts, dresses, and hats. Most of those items have 24 SKUs each: gold, blue, brown, and green in x-small, small, medium, large, 1X, and 2X. (Each color/size/type combination will have a different SKU number.)

Therefore, you will want to add approximately 3,600 listings, just for your clothing catalog. Each listing will have multiple items of the same size, color, and type. For instance, you may have 10 medium-size, gold shirts that you want to add to the eBay site. You would create this as a single listing for the medium/gold/shirt SKU, and set the quantity to 10.

If we expand this model to include all of your catalog items, you may have between 14,000 and 15,000 listings to add to the eBay site, and each of these listings is a multi-quantity listing.

In this case, you will want to begin by creating a data file with just a few SKUs (or the information for just a few listings) using the AddFixedPricedItem call format. Test this file using the eBay Developer Program Sandbox. Once it is working the way you want it to, expand the file to include all of the listings that you want to add to the site.

If you are adding items to eBay for the first time, it is important for you to become familiar with the eBay basics (like category and shipping requirements), as well as the eBay Trading API.

The majority of the work in the Large Merchant Services solution is the initial addition of large quantities of item data to the eBay site. If you are adding data for the first time, you have the benefit of the optimized bulk AddFixedPricedItem call.

See Data File Limits for information about the size and restrictions for your data file.

Large Merchants Who Already Have Lots of Inventory on the eBay Site

You work for the competitor of the Extremely Large Corporation, and you have had your catalog listings on eBay in Store Inventory Format for the past two years.

Every time you sell an item, you get notified by email from the eBay server, but the emails are stored in a large file that has to be read by an employee every afternoon. During the Christmas season, when many items are sold, you have to hire extra people in the shipping department, just to read the email file and enter orders into your computer. This also involves decrementing the stock number in your computer.

Then, at the end of each day, you have someone reconcile the stock on the shelves with the items you have sold in your store and online. When all of this is done, you sometimes revise your eBay listings or add new ones.

In this case, you will want to begin by creating a data file with revisions for a few SKUs (or the information for just a few listings) using the RevisedFixedPricedItem call format. Test this file using the eBay Developer Program Sandbox. Once it is working the way you want it to, expand the file to include all of the listings that you want to revise on the site.

In either of the cases above, you will need a way to keep track of a large numbers of sales on a daily basis. Retrieving the data for large quantities of orders, getting reports of your active eBay inventory, and checking the status of your bulk uploads and downloads. The Large Merchant Services solution will help you accomplish these eBay inventory management tasks.

If you already have most of your inventory on the eBay site, you can just upload revisions, additions, and changes periodically.

Order Management with Large Merchant Services

In either of the cases above, you will need a way to keep track of a large numbers of sales on a daily basis. Retrieving the data for large quantities of orders, getting reports of your active eBay inventory, and checking the status of your bulk uploads and downloads. The Large Merchant Services solution will help you accomplish these eBay inventory management tasks.

Making your day-to-day tasks faster and easier as you manage your eBay inventory is a key goal of the Large Merchant Services solution. Revising item price and quantity by SKU or Item ID, acknowledging orders, and retrieving shipping information, are just a few of the operations that you can perform in bulk.

See Managing Your Inventory Using Large Merchant Services for more information about on-going tasks.

Working with the Large Merchant Services Solution

Whether you represent a merchant who has many items on eBay, or whether you are uploading inventory for the first time, you will eventually need to upload item data, revise item data, and download status or reports about your listings. This section explains how to use the Large Merchant Services solution.

The sections that follow begin with a discussion of how to create a data file to upload items, and then explain how to setup a File Transfer call to get that data file onto the eBay web site. The Bulk Data Exchange Service, which enables you to manage all of your bulk data is discussed at the end of this section (even though you will need to send a Bulk Data Exchange Service call before you can perform a File Transfer call).

Preparing Your Data File

With the Large Merchant Services solution, you prepare each listing within a data file and then upload all of the listings at once. In this way, you can upload, modify, or delete inventory in bulk to the eBay site.

Prerequisites to Data File Creation

As with a single-request eBay Trading API call, you must have performed the following steps before you can create a bulk listing:

Data File Creation

Now you are ready to create your data file:

  1. Create an XML file, including the XML declaration.
  2. Add opening and closing tags for the BulkDataExchangeRequests root element.
  3. Within the BulkDataExchangeRequests root element, create a header (Header) with the site ID (SiteID) and the version (Version) of the eBay Merchant Data API.

    Refer to the Merchant Data API Release Notes for version information. Version must still be specified in individual requests included in the payload, such as AddFixedPriceItem requests.
    For a list of valid site names and their corresponding IDs, call GeteBayDetails or see the SiteCodeType documentation.

  4. After the header, enter the API requests and the information about listings you want to add or modify on the eBay site.
    Important: Data files have a single line length limit of 20,000 characters. If the data file has any lines that exceed this limit, the uploadFile request will fail. The submission of multiple requests as a single line of XML is the common cause for lines extending beyond the limit, but a long item description can cause the failure, as well.

    For best results, add line breaks in between each individual request in the data file and add line breaks to split up any long text/string values. There are many utilities or code libraries that support pretty-printing XML. Pretty-printing is one way of inserting the necessary line breaks to prevent excessive line lengths. Once the needed line breaks have been added, a failed uploadFile request can be resubmitted.

The Merchant Data API calls that you can perform are listed in the Merchant Data API Reference. You can only use one type of call for each file you upload. For instance, you cannot use the same file to add some items (e.g., AddFixedPriceItem) and revise others (e.g., ReviseFixedPriceItem). The following code snippet shows the format of a request to revise inventory using a data file.

Example Data File Call

Input XML will be in the following format:

<?xml version="1.0" encoding="UTF-8"?>
<BulkDataExchangeRequests>
  <Header>
    <SiteID>0</SiteID>
    <Version>739</Version>
  </Header>
  <ReviseInventoryStatusRequest xmlns="urn:ebay:apis:eBLBaseComponents">
    <Version>739</Version>
    <InventoryStatus>
      <ItemID>330001291447</ItemID>
      <StartPrice>190.00</StartPrice>
      <Quantity>15</Quantity>
    </InventoryStatus>
  </ReviseInventoryStatusRequest>
  <!-- ... More ReviseInventoryStatusRequest nodes here ... -->
</BulkDataExchangeRequests>

Refer to the Merchant Data API Reference for a list of API calls and the associated inputs and outputs for each. Note that the calls listed as 'Related' can be included in your data files.

You can use the Merchant Data XSD file as an aid in validating your data file payloads.

Inventory Tracking by SKU

When you create a fixed-price listing, you can include a SKU for your own reference. If the SKU is unique across all of your active eBay listings, you can use it as the listing's identifer. This means you can pass your SKU instead of the item ID in subsequent Merchant Data API requests, such as ReviseFixedPriceItem, and in several Trading API calls. However, you must make this choice when you first create the listing.

The Merchant Data API defines two requests for creating listings: AddFixedPriceItem and RelistFixedPriceItem. When you create a listing, use the InventoryTrackingMethod field to choose whether you prefer to identify the listing by item ID or by SKU. (In either case, you still have the ability to use the item ID as needed.)

When you choose to track a listing by SKU, you cannot create and track new listings by the same SKU while the existing listing is active (that is, until the existing listing with that SKU has ended). In other words, the Item.SKU value must be unique across all of your active listings that have Item.InventoryTrackingMethod set to SKU. (SKU does not need to be unique across listings that are tracked by item ID.)

If you need to add more inventory for a given SKU, you can use ReviseInventoryStatus to update the quantity of the existing listing as needed.

Note: The eBay Web site UI cannot identify listings by SKU. For example, My eBay pages and Search pages all identify listings by item ID. When a buyer contacts you via eBay's messaging functionality, eBay uses the item ID as the identifier. Buyer-focused APIs (like the Shopping API) also do not support SKU as an identifier.

AddItem and RelistItem calls do not support inventory management by SKU. Only AddFixedPriceItem and RelistFixedPriceItem offer this preference.

Using the Trading API to Complete Your Selling Solution

You may need to use Trading API calls while preparing your data file. For instance, you may need to use the Trading GetCategories call to determine the category ids of items you are adding using a bulk data file.

The eBay Trading API offers authenticated access to private eBay data to enable automation and innovation in the areas of listing items, retrieving seller sales status, managing post-transaction fulfillment, and accessing private user information such as My eBay and Feedback details.

The examples below describe some of the ways that Sellers use the Trading API with the Large Merchant Services solution.

Uploading Externally Hosted Pictures

The Trading API's UploadSiteHostedPictures call uploads a picture to EPS (eBay Picture Services) when you supply a URL in the ExternalPictureURL field (the location of the picture on an external web server).

You can upload multiple instances of the UploadSiteHostedPictures call (with different picture URLs) in the same Merchant Data file. Uploading many picture URLs at once will allow the pictures to be available in the EPS before you upload the data for the corresponding listing using an AddFixedPriceItem data file.

Use the URL from the UploadSiteHostedPicturesResponse.SiteHostedPictureDetails.FullURL field as input for the AddFixedPriceItemRequest.Item.PictureDetails.PictureURL field to designate which (already uploaded) picture should be associated with each listing in your AddFixedPriceItem data file.

The UploadSiteHostedPictures response data file will return the expiration time for each picture (that is, the date and time for the last day that the picture will be kept on the eBay server) in the UseByDate field.

GetCategories and GetCategory2CS

When creating your data file, you may need to use the Trading API to look up information about the categories for your new listings. The GetCategories call will return all of the categories that exist for a specific site ID. The GetCategory2CS call retrieves characteristics associated with each category.

GeteCategorySpecifics and the File Transfer Service

You can use the File Transfer service's downloadFile command to retrieve a report that contains recommendations for custom Item Specifics. This is a very large data set that can't be retrieved through the more traditional synchronous calls.

First, you need to call GetCategorySpecifics in the Trading API to obtain the task and file reference IDs. Then pass them into the downloadFile call to retrieve the recommendations report file.

See GetCategorySpecifics for details.

GeteBayDetails

Retrieves eBay IDs and codes (e.g., site IDs and shipping service codes), enumerated data (e.g., payment methods), and other common eBay meta-data. This call enables you to keep certain data up to date in your applications without referring to the schema, the documentation, or the eBay online help.

AddItem Call Family

Since AddFixedPriceItem, ReviseFixedPriceItem, and RelistFixedPriceItem requests are based on the eBay Trading API's AddItem, ReviseItem, and RelistItem requests, you may want to make some of these Trading API calls using the API Test Tool on the eBay Developer Program website to get more familiar with the request and response data for the Add, Revise, and Relist calls. You cannot use the test tool to make Merchant Data test calls.

Important: If problems, such as an "Internal Error to the Application" error or a network issue are encountered when uploaded data files are processed, Large Merchant Services will automatically retry requests. In rare cases, this can cause duplicate listings if an original request succeeded. To prevent listing the same item more than once, eBay recommends the use of universally unique identifiers (UUIDs) when submitting requests to create listings.

Use Item.UUID in the following calls to ensure a particular item is not listed more than once:

  • AddFixedPriceItem
  • RelistFixedPriceItem
  • AddItem
  • RelistItem

When an item is successfully listed or relisted with Item.UUID in the request, any subsequent attempt to submit the request results in an error (code 488). The error information includes the item ID of the item previously listed with the same UUID and a Boolean value indicating whether the duplicate UUID was sent by the same application.

For more information, refer to Specifying Unique Identifiers (UUID) for Write Calls in the Trading API Guide.

ReviseInventoryStatus

This call allows you to adjust the price and quantity on your listings efficiently. The ReviseInventoryStatus call is defined in the Trading API, and it is also available as a Bulk Data Exchange job. Therefore, you can include the ReviseInventoryStatus request in your data file to make bulk changes, or you can use it to make direct Trading API calls.

Using Platform Notifications with Large Merchant Services

You can subscribe to get notification of Bulk Data Exchange job completion by subscribing to the BulkDataExchangeJobCompleted event in the SetNotificationPreferences Trading API call. In the notification, the caller receives a response of getJobStatus for his job. Here is a sample SetNotificationPreferences call:

<?xml version="1.0" encoding="utf-8"?>
<SetNotificationPreferencesRequest xmlns="urn:ebay:apis:eBLBaseComponents">
  <RequesterCredentials>
	<eBayAuthToken>AgAAAA**AQAAAA**... </eBayAuthToken>
  </RequesterCredentials>
  <Version>605</Version>
  <WarningLevel>High</WarningLevel>
  <UserDeliveryPreferenceArray>
  <NotificationEnable>
	<EventType>BulkDataExchangeJobCompleted</EventType>
    <EventEnable>Enable</EventEnable>
  </NotificationEnable>
  </UserDeliveryPreferenceArray>
</SetNotificationPreferencesRequest>

How Are the Large Merchant Services APIs Different from Other eBay APIs?

The Large Merchant Services APIs work similarly to other eBay APIs. For example, the Bulk Data Exchange API, and the File Transfer API use the same authentication as the Trading API. You can use the same AppID for these APIs as well.

However, like the Merchandising API, the Large Merchant Services APIs are built on eBay's Services Oriented Architecture (SOA) framework. As a result, there are some changes to the API conventions and how you route requests.

Another difference is that the Large Merchant Services API uses the File Transfer Service to upload or download data files as attachments.

See Making an API Call for information about how to construct a Bulk Data Exchange API or File Transfer API call.

Refer to the API References for details about the API structure and logic.

Refer to the eBay Merchant Data API Call Reference for a list of API calls and the associated inputs and outputs for each.

Using the File Transfer API

The File Transfer Service uploads your data file to (and downloads data from) the eBay Servers. Responses that you receive from the File Transfer Service are only acknowledgements of a successful file upload. They do not indicate whether your merchant data file has formatting, size, or content errors. The file transfer response contains no information about the state of the file processing.

After you upload your file, you will need to make a StartJobUpload Bulk Data Exchange Service call to start the processing for this data.

To upload a file using the File Transfer Service:

  1. Pass the job id and reference id that you received from the Bulk Data Exchange Service to your SOAP call
  2. Specify the zipped data file you want to upload and use SOAP 1.1 or 1.2 with MTOM encoding or XML over HTTP to include the file.
  3. Send the FTS call.

To download a file using the File Transfer Service:

  1. Pass in the job id and reference id that you received from the Bulk Data Exchange Service.
  2. Convert the downloaded Base 64 binary attachment to a zip file.
  3. Extract the .zip file to reveal the XML data.

Example File Transfer Call

Setting up a correct File Transfer Call is the key to getting your bulk data up on the eBay site. While the format looks simple, as shown in the following example, your Base 64 binary file encoding and data inclusion must be specified correctly for a successful result.

Basic Request Format:
<?xml version="1.0" encoding="UTF-8"?>
<uploadFileRequest xmlns="http://www.ebay.com/marketplace/services">
  <taskReferenceId>5000003614</taskReferenceId>
  <fileReferenceId>5000028204</fileReferenceId>
  <fileFormat>gzip</fileFormat>
  <fileAttachment>
    <Data>
      <xop:Include href="cid:1.urn:uuid:FFAFEBBA9E369E19151224106591198@apache.org"
      xmlns:xop="http://www.w3.org/2004/08/xop/include"/>
    </Data>
  </fileAttachment>
</uploadFileRequest>
Actual Request Sent:
POST /FileTransferService HTTP/1.1
Content-Type: multipart/related; boundary=MIMEBoundaryurn_uuid_FFAFEBBA9E369E19151224106591181; type="application/xop+xml";
start="<0.urn:uuid:FFAFEBBA9E369E19151224106591182>"; start-info="tet/xml"
X-EBAY-SOA-OPERATION-NAME: uploadFile
X-EBAY-SOA-SECURITY-TOKEN: YourTokenHere
X-EBAY-SOA-SERVICE-NAME: FileTransferService
X-EBAY-SOA-REQUEST-DATA-FORMAT: XML
X-EBAY-SOA-RESPONSE-DATA-FORMAT: XML
User-Agent: Jakarta Commons-HttpClient/3.1
Host: localhost:8082
Content-Length: 44155

--MIMEBoundaryurn_uuid_FFAFEBBA9E369E19151224106591181
Content-Type: application/xop+xml; charset=UTF-8; type="text/xml"
Content-Transfer-Encoding: binary
Content-ID: <0.urn:uuid:FFAFEBBA9E369E19151224106591182>

<?xml version='1.0' encoding='UTF-8'?><uploadFileRequest
xmlns="http://www.ebay.com/marketplace/services"><taskReferenceId>50000000419</taskReferenceId><fileReferenceId&g
t;50000000619</fileReferenceId><fileFormat>gzip</fileFormat><fileAttachment><Data><xop:Include
href="cid:1.urn:uuid:FFAFEBBA9E369E19151224106591198" /></Data></fileAttachment></uploadFileRequest>
--MIMEBoundaryurn_uuid_FFAFEBBA9E369E19151224106591181
Content-Type: application/octet-stream
Content-Transfer-Encoding: binary
Content-ID: <1.urn:uuid:FFAFEBBA9E369E19151224106591198>
Basic Response Format:
<?xml version='1.0' encoding='utf-8'?>
<uploadFileResponse  xmlns="http://www.ebay.com/marketplace/services">
  <ack>Success</ack>
  <version>1.0.0</version>
  <timestamp>2008-10-15T21:36:32.191Z</timestamp>
</uploadFileResponse>
Actual Response Returned:
HTTP/1.1 200 OK
Server: Apache-Coyote/1.1
X-EBAY-SOA-SERVICE-NAME: {http://www.ebay.com/marketplace/services}FileTransferService
X-EBAY-SOA-OPERATION-NAME: uploadFile
X-EBAY-SOA-MESSAGE-PROTOCOL: NONE
X-EBAY-SOA-RESPONSE-DATA-FORMAT: XML
X-EBAY-SOA-SERVICE-VERSION: 1.0.0
X-EBAY-SOA-REQUEST-GUID: 11d02704-7030-a08a-de32-a962fffffd17
Content-Type: application/xop+xml;charset=UTF-8
Transfer-Encoding: chunked
Date: Wed, 15 Oct 2008 21:36:32 GMT

19f
<?xml version='1.0' encoding='utf-8'?>
<uploadFileResponse  xmlns="http://www.ebay.com/marketplace/services">
<ack>Success</ack>
<version>1.0.0</version>
<timestamp>2008-10-15T21:36:32.191Z</timestamp>
</uploadFileResponse>
0

Click this link to see a sample Java Code for File Transfer API calls.

Data File Limits

A data file includes the information that a seller wants to pass to or retrieve from the eBay servers. Each file requires an associated Bulk Data Exchange call (to get job ID and refernce ID) with a seller token (unique combination of AppID and UserID).

If you are an eBay Certified Provider and you are creating data files for many different sellers, note that you can not combine the data for several different sellers in a single upload file. Each data file needs to contain data for a single seller, but can contain the data for many listings for that seller. The rate limits in the table below are for the Bulk Data Exchange job type (for each seller token) associated with each data file.

Each data file can contain thousands of calls of the same type. For instance, an AddFixedPriceItem data file can contain the data to add thousands of listings to the eBay site for a specific seller.

Each eBay user starts out with a default request limit of 5,000 calls per day per seller token. You can increase your request limit by applying for a Compatible Application Check. We expect that most large merchant developers will request an increased limit.

All data files have a maximum size limit of 15 MB, no matter how many requests they contain.

The frequency that each seller can upload or download files varies depending on the call type within the associated data file. See the table below for the rate limits for each type of file.

Job-Type Rate Limit
Inventory Maintenance
AddItem (Upload) 4 data files every 24 hours
AddFixedPriceItem (Upload) 4 data files every 24 hours
RelistItem (Upload) 2 data files every 24 hours
RelistFixedPriceItem (Upload) 2 data files every 24 hours
ReviseItem (Upload) 4 data files every 24 hours
ReviseFixedPriceItem (Upload) 4 data files every 24 hours
EndItem (Upload) 96 data files every 24 hours
EndFixedPriceItem (Upload) 96 data files every 24 hours
VerifyAddItem (Upload) 96 data files every 24 hours
VerifyAddFixedPriceItem (Upload) 96 data files every 24 hours
UploadSiteHostedPictures (Upload) 4 data files every 24 hours
ReviseInventoryStatus (Upload) 96 data files every 24 hours
SetShipmentTrackingInfo (Upload) 24 data files every 24 hours
ActiveInventoryReport (Download) 1 data file every 24 hours
Order Fulfillment
SoldReport (Download) 48 data files every 24 hours
OrderReport (Download) 48 data files every 24 hours
OrderAck (Upload) 48 data files every 24 hours
Account Management
FeeSettlementReport (Download) 1 data file every 24 hours (NOTE: This report is only generated once per month, according to the seller's billing cycle. You can download it every 24 hours, but the data will only change once a month.)
NOTE: If you have not received a Compatible App Check (to increase the daily call limit for your Seller ID), you will be limited to the default call maximum of 5,000 calls per day. This means that if your Seller ID has a call limit of 5,000 calls per day, you can send a total of 5,000 calls per day in your data files. As another example, if you want to add fixed price items twice a day, you could send 2,500 calls in the first file and 2,500 calls in a second file, or 3,000 calls in the first file and 2,000 calls in the second, etc..

Refer to the eBay File Transfer API API Reference for a list of API calls and the associated inputs and outputs for each.

Using the Bulk Data Exchange API

The Bulk Data Exchange API manages your large data uploads and report downloads. Before you can upload data or download reports, you must create a job (and receive a job id and a reference id from the Bulk Data Exchange API. Through this service, you can request the status of a job, abort a job and make other job-related calls.

Responses that you receive from the Bulk Data Exchange API are indications of a successful job id assignment, the successful start of job processing, the successful start of report creation, the successful retrieval of job status, or the failure of any of the above. They do not indicate whether your data file has formatting, size, or content errors.

The job id and reference id that are returned by this service must be included in your File Transfer Request, as well as in any Bulk Data Exchange request call about this job.

Example Bulk Data Exchange Call

Request:
<?xml version='1.0' encoding='UTF-8'?>
<createUploadJobRequest xmlns="http://www.ebay.com/marketplace/services">
  <uploadJobType>AddFixedPriceItem</uploadJobType>
  <UUID>334c72f0-aa1b-11dd-ad8b-0800200c9a66</UUID>
  <fileType>gzip</fileType>
</createUploadJobRequest>
Response:
<?xml version='1.0' encoding='utf-8'?>
<createUploadJobResponse xmlns="http://www.ebay.com/marketplace/services">
  <ack>Success</ack>
  <version>1.0.0</version>
  timestamp>2008-11-04T02:51:55.926Z</timestamp>
  <jobId>50000002126</jobId>
  <fileReferenceId>50000002936</fileReferenceId>
  <maxFileSize>15</maxFileSize>
</createUploadJobResponse>

Refer to the eBay Bulk Data Exchange API API Reference for a list of API calls and the associated inputs and outputs for each.

Managing Your Inventory Using Large Merchant Services

This section describes ongoing or day-to-day best practices for managing your eBay listings.

Checking Job Status

It is important to check your job's status periodically, so that you will know when a job's results are available. When your job has finished processing, you can download the results for each call. For example, if your data file contained ReviseInventoryStatus calls, you would get a Success acknowledgement or an error message for each call in your file.

Revising Inventory Status

The ReviseInventoryStatus call is only valid for use with fixed-price items. The ReviseItem call should be used with auction items.

Use the ReviseInventoryStatus call if you only want to change the price and quantity of the fixed-price items in your listings. With the ReviseInventoryStatus call, you can adjust the price and quantity without including all of the other fields required in a ReviseFixedPriceItem call. ReviseInventoryStatus can be used as a job type within a Large Merchant Services data file, or it can be used as a single item call within the Trading API.

Acknowledging Sales - OrderAck, SoldReport, and OrderReport

The Large Merchant Services solution provides a pair of download calls and one upload call that allows you to retrieve all orders through OrderReport or SoldReport and then acknowledge that you received those orders through OrderAck.

If a buyer purchased multiple variations of an item from a single multi-variation listing, the sale will result in a single Order ID for the total purchase with a separate Line Item ID for each of the purchased item variations. SoldReport and OrderReport retrieves the data for all orders created within the last 30 days.

The Bulk Data Exchange Service will continue sending all order data when you request either of these reports until you upload an OrderAckRequest that verifies that you have received and are processing/fulfilling the order. After you send an OrderAckRequest, only the unacknowledged orders will show up in the next instance of the SoldReport or OrderReport.

Note: The data in OrderReport response is identical to the order data returned under the OrderArray container returned in the GetOrders response of the Trading API. SoldReport is currently in the deprecation process. No new features and/or fields will be added to SoldReport from here on out, and it will no longer be supported at all beginning in early 2015. Due to this fact, it is recommended that large sellers and developers migrate to OrderReport.

Retrieving an Active Inventory Report

The ActiveInventoryReportRequest allows you to download a description of all of your active listings by SKU. The SKU details include ItemID, Price, Quantity, SKU, and SiteID.

For information about how to include additional fields in your report, such as BidCount and ReserveMet, please see Active Inventory Report Filter.

Using Recurring Jobs

After you have listings on the eBay site, you can use a Bulk Data Exchange Service recurring job to retrieve reports periodically. Set the frequency (in minutes) and the job type when you create the recurring job.

See the Bulk Data Exchange API Reference for the list of recurring job options.

Testing and Troubleshooting

This section discusses ways to test your application calls and data files before using them in a production environment. The eBay Developer testing environment is called the Sandbox.

Note: we strongly recommend using the eBay Developer Sandbox environment to test data files and application behavior before putting a Large Merchant Services application into production.

Best Practices for Testing

In order to improve your testing efficiency, we have included the following steps that we have found to be best practices:

  1. Create a sample data file that includes data that will represent 'real' items that you want to upload to the eBay site.
  2. Download the LMSSample.zip file and run it in Eclipse (or other IDE) to test your data file.
  3. Use a WSDL-reader tool (such as WSDL2Java or SOAPUI) to automatically generate the Bulk Data Exchange and File Transfer calls.
  4. Test each call in the Sandbox to verify that you understand the call sequences.
  5. Note that you will need to use Base 64 binary encoding with the File Transfer calls. Use the File Transfer samples in this document as a guide when troubleshooting.
  6. Build your own application to upload and download data to the Sandbox.
  7. When your application is working well, modify it to use a Production token and Production endpoints.

Sandbox Limits

The call limits for the Sandbox environment are higher than the limits in the Production environment. Therefore, you can make more calls in the testing phase of your development than you can in production. This is because you may need to make a call, get an error, revise your call and iterate through this process several times before you have your calls working the way you want them.

The Sandbox gives you enough calls to do extensive testing while still protecting eBay assets. File a service request with eBay's Developer Technical Support team if you encounter a sandbox limit impeding development.

Troubleshooting

As with most API calls, the Large Merchant Services calls will return errors that you can use to troublshoot your code. Before you call eBay's Developer Technical Support team for assistance, check for the following issues. (Note: There is a fee for Developer Technical Support services.)

The following tables lists some of the errors (and remedies for those errors) that beginners may receive:

Issue Check
Invalid authorization token Make sure you are using the correct endpoint for the auth token (Sandbox or Production)
UUID is requred (but there is a UUID in the request) Make sure you have SOAP11 or SOAP12 specified as the MESSAGE PROTOCOL in your header.
UUID is not unique You will see a message like this if you try to make the same call twice. Modify the UUIDs and SKUs if you want to test uploading the same data file more than once.
UUID is not valid Try using a UUID generator to get a unique number. Enter the number just as it was generated - including the dashes. The UUID can contain both numbers and the letters a-f. It cannot be more than 33 characters long.
Maximum of one job per job-type in non-terminated state is allowed Wait until job processing is completed before uploading or downloading another job of the same type. Use the abortJob or getJobStatus job types as needed.

References for Error Messages

Each eBay API error is either an Application Error, a System Error or a Request Error. The error type is indicated in error result sets by the value returned in the errorMessage.error.category return field. The error type indicates what sort of action the application, the developer, or the end-user needs to take in response to the error.

Click one of the following links to find descriptions of the error messages for each Large Merchant Services library: Merchant Data Call Errors Bulk Data Exchange API Errors File Transfer API Errors

API References

Refer to the API References for a list of calls in the Bulk Data Exchange API, the File Transfer API, and the Merchant Data API. Each API Reference includes the following information:

Additional Resources

You can get more information about the Large Merchant Services solution at these locations:

Back to top

User-Contributed Notes

   
 
 
 





Copyright © 2008–2014 eBay, Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.