eBay Feed API Technical Scope

The purpose of this document is to give good understanding how to migrate from LMS to the new Feed API which is the same feature but based on REST API.

The LMS is Large Merchant Services which allow us to send very large amounts of inventory to the eBay site, more specifically for product updates and product create. With the standard API we are able to send 120 product per request while with the LMS we can push up to 80k products for update at a time.

In terms of logs we will change the way we store the lms files. We will have a folder for each date containing each started lms for the day in a separate folder with the actual xml and response. For Example - 16_01_2022 > 563149 > request.xml / response.xml

Also we will need to change the way LMS and trading API updates are working and incorporate them into a single cron. If we have more than 1000 products for create or update on pending per eBay account we use the LMs to push the products to eBay and mark them as sent. With less than 1000 products we use our standard Trading API cron. Basically we will have a flow where we are checking each active eBay account in Hemi and depend on the number of products on pending we will either pick them with the LMS or the Trading API. If we have a LMS in progress we will have to wait to be completed before the next one of the same type can start again. Meanwhile if we have less than 1000 products the trading API will be picking them.

The Feed API LMS flow will look like:

Basically the first step is to create a task with the relevant feed type which returns an ID. The task ID is used to upload the file which are with the same structure as we currently have for the LMS. Then we have to periodically check the task status until we have COMPLETED or COMPLETED_WITH_ERROR. If there are any error we need to get the report which will specify which products are with error.

Authorization

The Feed API accepts OAuth tokens. See Using eBay RESTful APIs for more information on working with eBay REST APIs.

Create Tasks

API Call: POST https://api.ebay.com/sell/feed/v1/task

API Docs: https://developer.ebay.com/api-docs/sell/feed/resources/task/methods/createTask

This method creates an upload task. When using this method, specify the feedType and the feed file schemaVersion. The feed type specified sets the task as a download or an upload task. We need to check which is our current Schema Version and hardcode it.

Example Call:

{
    "schemaVersion": "1149",
    "feedType": "LMS_ADD_FIXED_PRICE_ITEM"
}

The feed Types which we will be using are:

Once we make a successful create task request we need to create a new record in eBay LMS Job table.

Call Mapping:

Example Response:

The output is an HTTP status. If the call is successful, the task ID is returned in the Location response header. This method has no response payload.

If we receive any errors at this step we will need to return them in the log file because only if we have success response we will create a new record in eBay LMS Job.

Upload File

API Call: POST https://api.ebay.com/sell/feed/v1/task/{task_id}/upload_file

API Docs: https://developer.ebay.com/api-docs/sell/feed/resources/task/methods/uploadFile

This method associates the specified file with the specified task ID and uploads the input file. After the file has been uploaded, the processing of the file begins. Note: You must use a Content-Type header with its value set to "multipart/form-data".

Example Call:

This call does not have a Request payload.

Form data
{
/* FormDataContentDisposition */
"creationDate" : "string",
"fileName" : "string",
"modificationDate" : "string",
"name" : "string",
"parameters" : "object",
"readDate" : "string",
"size" : "integer",
"type" : "string"
}

Call Mapping:

Example Response:

A successful call returns an HTTP status code of 200 OK. This method has no response payload.

If we successfully (200) upload we need to set:

Also we need to store all items from the file as LMS Job objects with its ID.

The file formats are the same as with the current LMS integration so we just change the flows.

If we receive any errors at this step we will need to set

Also we will need to set all products on Error included in the file.

Task Status

API Call: GET https://api.ebay.com/sell/feed/v1/task/{task_id}

API Docs: https://developer.ebay.com/api-docs/sell/feed/resources/task/methods/getTask

This method retrieves the details and status of the specified task. The input is task_id.

Example Call:

This call has no payload.

Example Response:

{
    "taskId": "task-10-3********1",
    "status": "COMPLETED",
    "feedType": "LMS_ORDER_ACK",
    "creationDate": "2020-07-06T03:00:23.000Z",
    "completionDate": "2020-07-06T03:00:34.000Z",
    "schemaVersion": "1.0",
    "detailHref": "https://api.qa.ebay.com/sell/feed/v1/task/task-10-3********1"
}

Statuses:

When we receive FAILED or PARTIALLY_PROCESSED statuses we also set Ebay LMS Job > In Progress set as false and delete all LMS Job objects for the particular task

Get Report

API Call: GET https://api.ebay.com/sell/feed/v1/task/{task_id}/download_result_file

API Docs: https://developer.ebay.com/api-docs/sell/feed/resources/task/methods/getResultFile

This method retrieves the generated file that is associated with the specified task ID. The response of this call is a compressed or uncompressed CSV, XML, or JSON file, with the applicable file extension (for example: csv.gz). Note: The status of the task to retrieve must be in the COMPLETED or COMPLETED_WITH_ERROR state before this method can retrieve the file. You can use the getTask or getTasks method to retrieve the status of the task.

Once we successfully get the report from a LMS with status COMPLETED or COMPLETED_WITH_ERROR we set Ebay LMS Job > In Progress set as false and delete all LMS Job objects for the particular task

We will be using the report file to obtain all errors of unsuccessful updated/created products which we will need to read and update accordingly on item account. Update the product status to error and store the relevant error message.

Example Call:

This call has no payload.

Call Mapping:

Example Response:

The response of this call is a compressed or uncompressed CSV, XML, or JSON file.
This call has no payload.

Not able to get the report and check the format to finish the mapping.

Additional Information:

Here I am outlining the major differences from the current LMS flow and the new Feed API LMS.

At the moment we are picking all products on “pending“ and mark them as “sent” in order to collect and generate the xml files (that will be converted to zip file before sending) for the LMS (Upload File Step) then because of the limit of 14megabytes (In the new flow nowhere is mentioned file limit) we may add only the half of the picked products which will remain on sent but the other half will be reverted back on pending. This is necessary because both trading API and LMS are working at the same time thus we are changing this logic and incorporate both flows into single cron.

The upload file cron will work in background and there will be running separate crons for every lms. And the updating in the database will work in chunks for 1000 for performance.

Create Upload Job

What's Changed:

1. LMS works through SOAP API while Feed API takes in REST API. In the Feed API, the OAuth Token (AuthorizationToken) follows the term Bearer (Bearer + UserToken).
2. TaskId in Feed API response is equivalent to jobId in LMS API processing.
3. SchemaVersion and SiteID values are provided through input Headers in Feed API. In LMS, these values were provided inside the inputFile. The value of <version> in the input files should match the SchemaVersion header value.
4. In the Feed API, the MarketPlaceId value is provided through X-EBAY-C-MARKETPLACE-ID header. In LMS, this value was provided by SiteID.
5. With the Feed API, sellers can create multiple jobs at a time. They are queued and only one is processed at any time. In LMS, sellers were blocked to create jobs as well.
6. In the Feed API, the possible values for schemaVersion, X-EBAY-C-MARKETPLACE-ID, and feedType are described in Version details / Schema version and Supported MarketPlaceIds
7. The taskId is used in the uploadfile call.

Upload Input File

What's Changed:

1. In LMS, the seller can either attach file as input or place its base64 encoded value in the request body. File input can only be a zipped xml formatted file for uploadJob.
2. For the Feeds API, the input can be an xml file and zipped or in regular format (both formats are allowed). The input can be a file or InputStream type (Inputstream can be used while uploading file programmatically).
3. Use the Feed API getInputFile method to download the file previously uploaded usinguploadFile.

Start Upload Job

1. In the Feed API, the task is automatically moved to Queued Status, waiting for processing and will be picked up by the system.
2. The QUEUED status in the Feed API corresponds to the SCHEDULED state in LMS.

AbortJob