Large Merchant Services

Making a Large Merchant Services API Call

Large Merchant Services consists of three separate APIs. The Bulk Data Exchange API and File Transfer API are for services that use eBay's SOA framework. The Merchant Data API (and select calls from the Trading API) is for building and parsing the uploaded and downloaded data files.

Note: The Merchant Data API does not contain calls that can be invoked directly. The requests and responses described in the Merchant Data API Reference are for constructing data files to be uploaded and parsing downloaded data files only.

This information is provided for the three APIs of the Large Merchant Services solution:

This document provides the details necessary to make calls with the APIs of the Large Merchant Services solution. The following sections contain the following information for making calls:

Bulk Data Exchange API

The Bulk Data Exchange API supports a subset of call formats supported by the eBay SOA framework.

Supported Protocols and Request and Response Formats

The Bulk Data Exchange service supports HTTP POST requests and responses in SOAP and XML format only.

Endpoints

All Bulk Data Exchange API requests must be sent to either the eBay Sandbox or Production API Gateway. This authenticated service uses secure endpoints.

Sandbox Gateway URL (endpoint):

https://webservices.sandbox.ebay.com/BulkDataExchangeService

Production Gateway URL (endpoint):

https://webservices.ebay.com/BulkDataExchangeService

HTTP Headers and URL Parameters

The Bulk Data Exchange service supports the following HTTP headers.

Header Value Required? Description
CONTENT-TYPE No If you use this header, you must specify the content format exactly as shown, or your call may fail. The allowable values are:


XML text/xml
SOAP12 application/soap+xml
SOAP11 text/xml (together with SOAPAction header being sent - value can be anything)
X-EBAY-SOA-MESSAGE-PROTOCOL Conditionally Required for SOAP requests. Use this header to specify the protocol you are using. Allowable values are "SOAP11" for SOAP Version 1.1 and "SOAP12" for SOAP Version 1.2.
X-EBAY-SOA-OPERATION-NAME Yes The name of the call you are using (for example, getJobs).
X-EBAY-SOA-SERVICE-NAME No The name of the eBay API you are using. For example, specify "BulkDataExchangeService" for Bulk Data Exchange API calls.
X-EBAY-SOA-SECURITY-TOKEN Yes For authenticated services, this provides the Auth Token for the user upon whose behalf the call is made.
X-EBAY-SOA-SERVICE-VERSION No The API version your application supports (e.g., 1.0.0).

Schema Location

Use the following link to download the latest WSDL for the Bulk Data Exchange API:

   http://developer.ebay.com/webservices/bulk-data-exchange/latest/BulkDataExchangeService.wsdl

Alternatively, you can retrieve a particular version of the WSDL using a URL with the following format, where VERSION is the version identifier of the release (for example, 1.0.0):

   http://developer.ebay.com/webservices/bulk-data-exchange/VERSION/BulkDataExchangeService.wsdl

For example, you can access version 1.0.0 of the WSDL version of the schema at the following URL:

   http://developer.ebay.com/webservices/bulk-data-exchange/1.0.0/BulkDataExchangeService.wsdl

Refer to the Bulk Data Exchange API Release Notes for information about the API changes associated with each release.

Testing Overview

Large Merchant Services is an integrated solution. To test your ability to add, revise, relist, or end item listings, you must use all three APIs together. That is, you cannot test the File Transfer API for uploading a file without first creating an upload job with the Bulk Data Exchange API and building a valid data file with the Merchant Data API or Trading API.

All three APIs are supported in the Sandbox environment, which should be used for testing. In the Sandbox environment, an application can perform the same operations it would in the Production environment, except that the users, items, and payments are just test data. The test data cannot be accessed from, or used in, the Production environment.

Refer to the Testing and Troubleshooting section in the Large Merchant Services Users Guide for call restrictions for testing best practices, call limits, and troubleshooting information.

File Transfer Call Details

The File Transfer API supports a subset of call formats supported by the eBay SOA framework.

Supported Protocols and Request and Response Formats

The File Transfer service supports SOAP and XML calls only.

Endpoints

All File Transfer API requests must be sent to either the eBay Sandbox or Production API Gateway. This authenticated service uses secure endpoints.

Sandbox Gateway URL (endpoint):

https://storage.sandbox.ebay.com/FileTransferService

Production Gateway URL (endpoint):

https://storage.ebay.com/FileTransferService

HTTP Headers and URL Parameters

The File Transfer service supports the following HTTP headers.

Header Value Required? Description
CONTENT-TYPE No If you use this header, you must specify the content format exactly as shown, or your call may fail. The allowable values are:
Header: CONTENT-TYPE
(Use only one of the following):
Payload Type: XML Value: text/xml Payload Type: SOAP12 Value: application/soap+xml Payload Type: SOAP11 Value: text/xml (in conjunction with SOAPAction header you are sending - SOAPAction value can be anything)
.
X-EBAY-SOA-MESSAGE-PROTOCOL Conditionally Required for SOAP requests. Use this header to specify the protocol you are using. Allowable values are "SOAP11" for SOAP Version 1.1 and "SOAP12" for SOAP Version 1.2.
X-EBAY-SOA-OPERATION-NAME Yes The name of the call you are using (for example, uploadFile).
X-EBAY-SOA-SECURITY-TOKEN Yes For authenticated services, this provides the Auth Token for the user upon whose behalf the call is made.
X-EBAY-SOA-SERVICE-NAME No The name of the eBay API you are using. For example, specify "FileTransferService" for File Transfer API calls.
X-EBAY-SOA-SERVICE-VERSION No The API version your application supports (e.g., 1.0.0).

Schema Location

Use the following link to download the latest WSDL for the File Transfer API:

   http://developer.ebay.com/webservices/file-transfer/latest/FileTransferService.wsdl

Alternatively, you can retrieve a particular version of the WSDL using a URL with the following format, where VERSION is the version identifier of the release (for example, 1.0.0):

   http://developer.ebay.com/webservices/file-transfer/VERSION/FileTransferService.wsdl

For example, you can access version 1.0.0 of the WSDL version of the schema at the following URL:

   http://developer.ebay.com/webservices/file-transfer/1.0.0/FileTransferService.wsdl

Refer to the File Transfer API Release Notes for information about the API changes associated with each release.

Testing Information

Large Merchant Services is an integrated solution. To test your ability to add, revise, relist, or end item listings, you must use all three APIs together. That is, you cannot test the File Transfer API for uploading a file without first creating an upload job with the Bulk Data Exchange API and building a valid data file with the Merchant Data API or Trading API.

All three APIs are supported in the Sandbox environment, which should be used for testing. In the Sandbox environment, an application can perform the same operations it would in the Production environment, except that the users, items, and payments are just test data. The test data cannot be accessed from, or used in, the Production environment.

Refer to the Testing and Troubleshooting section in the Large Merchant Services Users Guide for call restrictions for testing best practices, call limits, and troubleshooting information.

Merchant Data Call Details

The Merchant Data API cannot be invoked on its own. The requests and responses described in the Merchant Data API Reference are for constructing data files to be uploaded and parsing downloaded data files only. Refer to the Merchant Data API Reference for more information.

Note: SOAP is not a supported format for Merchant Data calls.

Data File Structure

The data files contain the seller's requests to eBay (e.g., AddFixedPriceItemRequest, ReviseInventoryStatusRequest, or OrderAckRequest) and eBay's responses and reports (e.g., AddFixedPriceItemResponse or OrderReport).

Each data file has a consistent structure, made up of the following parts:

Data File Structure

XML Declaration

The data files uploaded and downloaded with the File Transfer service are XML, so require an XML declaration. The encoding attribute must be set to UTF-8.

Requests and Responses Containers

When a data file is uploaded, the individual requests must be within a BulkDataExchangeRequests container. The payload of downloaded data files are contained within a BulkDataExchangeResponses container. (The response container also includes a namespace declaration.) A data file contains only one BulkDataExchangeRequests container or one BulkDataExchangeResponses container.

Data File Header

When you are uploading files, you must include a Header in the BulkDataExchangeRequests container. The Header contains the following two fields:

Data File Payload

The data file payload consists of one or more requests, responses, or reports. The Merchant Data API Reference describes the input fields for requests and the output fields for responses and reports. The request types submitted in a payload must be homogeneous. That is, you cannot mix AddFixedPriceItem requests with ReviseFixedPriceItem requests within a given data file.

Refer to Preparing Your Data File in the Large Merchant Services Users Guide for more information about how data files are used.

Schema Location

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

Refer to the Merchant Data API Release Notes for information about the API changes associated with each release.

Testing Information

Large Merchant Services is an integrated solution. To test your ability to add, revise, relist, or end item listings, you must use all three APIs together. That is, you cannot test the File Transfer API for uploading a file without first creating an upload job with the Bulk Data Exchange API and building a valid data file with the Merchant Data API or Trading API.

All three APIs are supported in the Sandbox environment, which should be used for testing. In the Sandbox environment, an application can perform the same operations it would in the Production environment, except that the users, items, and payments are just test data. The test data cannot be accessed from, or used in, the Production environment.

Refer to the Testing and Troubleshooting section in the Large Merchant Services Users Guide for call restrictions for testing best practices, call limits, and troubleshooting information.



Copyright © 2008–2015 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.