Skip to main content

Managing videos

eBay now allows sellers to upload videos and associate these videos with their listings. To enable this capability, the Media API was created. The Media API has methods to create, upload, and get videos, and the add/revise/relist calls of the Trading API have been updated with a new VideoDetails.VideoID field that allows sellers to associate a video with a listing.

This topic covers the complete process of uploading videos to your listings. The subsections are highlighted below:

Creating and uploading a video with Media API

The first step in uploading a video to eBay is to first create the video resource using the createVideo method of the Media API.

Tip: See Adding a video to your listing in the eBay Seller Center for details about video formatting requirements and restrictions, or visit the relevant eBay site help pages for the region in which the listings will be posted.

The request payload of the createVideo method has the following fields:

Field

Description

Required?

title Title of the video. This should be text only, and markup tags are not supported.

Yes

size The size of the video in bytes. This value must be accurate or the seller may be blocked from uploading the video. The maximum allowed size for a video is 150MB, or 157,286,400 bytes

Yes

classification The seller passes in a value of ITEMin this field, which indicates that the video will be associated with an item listing.

Yes

description This is the user-defined description of the video. Like the title, this should be text only, and markup tags are not supported.

No

If a createVideo method is successful, a 201 Created HTTP status code is returned along with a newly-created video ID value in the Location response header. This video ID value should be stored/kept by the seller, as it will be needed for the uploadVideo method, the getVideo method, and will also be used when it's time to upload the video with an Add/Revise/Relist call in the Trading API.

The next step is to upload this video using the uploadVideo method. The video ID returned in the createVideo method is passed in as part of the URI, as shown below:

POST https://api.ebay.com/commerce/media/v1/video/{video_id}/upload

The uploadVideo method has no request payload, but you are uploading a video file in binary format to the endpoint. To accommodate the upload of this binary file, the content-type request header is required, and its value should be set to application/octet-stream.

Note: The size of the uploaded video must exactly match the size that was stated for the file in the createVideo method. If the sizes do not match, the video will not upload successfully.

A successful uploadVideo method will return a 200 OK HTTP status code.

After a successful uploadVideo method, the processing of the file begins. The "happy" status flow of a video upload is PENDING_UPLOAD > PROCESSING > LIVE. If there is an issue with processing, the status may turn to PROCESSING_FAILED, or BLOCKED.

There may be issues uploading the video file, leading to a status of PROCESSING_FAILED. If processing fails, it could be because the file is corrupted, is too large, or its size doesn’t match what was provided in the metadata. Refer to the error messages to determine the cause of the video’s failure to upload.

This API supports resumable upload. In case of an error during upload, the upload may be resumed starting from the bytes received using appropriate Content-Range and Content-Length headers. For partially uploaded content, an attempt to re-upload will result in an error with the correct Content-Range and Content-Length values for resuming the upload from the correct byte position.

The seller can track the upload status of the video file, and get additional metadata on the uploaded video by using the getVideo method, which is described in the next section.

Retrieving video details with Media API

Sellers can use the getVideo method of the Media API to retrieve details on a specific video that has been uploaded with the Media API. The data that is returned in the response payload will vary based on the processing status. A video in the LIVE state will have more details than a video still in the PROCESSING state.

There is no request payload for the getVideo method, but the video ID of the video must be passed into the call URI, as shown below:

GET https://api.ebay.com/commerce/media/v1/video/{video_id}

The fields returned in the response payload are briefly described below, but please see getVideo reference documentation for more details.

Field

Description

Always Returned?

classification The value returned in this field indicates the classification of the video. For example, the ITEM indicates that the video will be associated with an item listing.

Yes

description

The user-defined description of the video. This field is only returned if the seller has provided a description of the video.

No

expirationDate This timestamp indicates the expiration date of the video. Videos are currently set to expire one year (365 days) after they are uploaded.

Yes

playlists This container is returned for videos in the LIVE state, and it shows the URLs of the videos. The supported video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming).

No

size The size of the video file in bytes.

Yes

status

The current status of the video.

Yes

statusMessage

This text field will provide more details about the video's status.

No

thumbnail.imageUrl

The URL to the video thumbnail image. This will be a generic thumbnail image created by eBay. Custom thumbnail images are not currently supported.

No

title

The title of the video.

Yes

videoId

Unique identifier of the video.

Yes

Adding videos to listings with Trading API

A video created with the Media API can be added to an eBay listing using the Add/Revise/Relist calls of the Trading API.

Although a video can be attached to a listing before it is in the LIVE state, the video will not be available for viewing in the listing until it is in the LIVE state. The getVideo method of the Media API can be used to retrieve the status of the video. The status is shown in the status response field.

Note: Currently, videos can only be viewed through the native apps (iOS and Android).

The following eBay marketplaces support adding a video to a listing:

  • EBAY_GB
  • EBAY_MOTORS_US
  • EBAY_US

The following Trading API calls support adding a video to a listing:

Note: Large Merchant Services APIs can also be used to add videos to listings in bulk. At this time, the Inventory API does not support this video uploading capability.

For all calls above, the following field will be used to add a video to a listing: Item.VideoDetails.VideoID. Below is an example of what this will look like:

<Item>
	...
	<VideoDetails>
	<VideoID>f******************************a</VideoID>
	</VideoDetails>
	...
</Item>

The video should be successfully attached to the listing as long as the VideoID value is valid and belongs to the seller.

A GetItem call can be used by the seller to verify if the video was added to the listing. If the video was successfully added to the listing, the same Item.VideoDetails.VideoID field will be returned in the response. This field will only be returned if the seller of the listing is making the GetItem call.

Replacing or removing videos with Trading API

It is possible to replace or remove videos from listings using the Revise or Relist calls.

To replace a video already attached to the listing, the seller could make a Revise call and just send in another VideoID value. The video specified would replace the existing video.

<Item>
	...
	<VideoDetails>
	<VideoID>h******************************t</VideoID>
	</VideoDetails>
	...
</Item>

To remove a video from the listing using the Revise or Relist calls, the seller can include a DeletedField tag in the request and set its value to Item.VideoDetails.VideoID. So, it will look like the following in a ReviseItem request payload:

<?xml version="1.0" encoding="utf-8"?>
	<ReviseItemRequest xmlns="urn:ebay:apis:eBLBaseComponents">
	<DeletedField>Item.VideoDetails.VideoID</DeletedField>
	...
	</ReviseItemRequest>

If the Revise call is successful, the video will be removed from the listing.

Similar to the Add use case, the seller could call GetItem to verify if a video was removed from the listing, or to verify if the existing video was replace by the newly-specified video. If a video was successfully removed, the Item.VideoDetails.VideoID field will not be returned at all in the GetItem response. To verify if a video was successfully replaced, the seller would want to verify the VideoID value returned in the Item.VideoDetails.VideoID field.