All images must comply with eBay's picture requirements, such as dimension and file size restrictions. For more information, see Picture policy. The image formats supported are JPG, GIF, PNG, BMP, TIFF, AVIF, HEIC, and WEBP. For more information, see Image requirements.
Note: Animated GIF, and multi-page PNG/TIFF files, are not supported. Any animation effect of supported formats will be lost upon upload.
This call does not have a JSON Request payload but uploads the file as form-data. For example:
image: "sample_picture.jpg"See Samples for information.
Note: You must use a Content-Type header with its value set to 'multipart/form-data'.
When an EPS image is successfully created, the method returns the HTTP Status Code 201 Created. The method also returns the getImage URI in the Location response header.
Important! Make sure to capture the image ID URI returned in the response location header provided in the following format:
https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}
You can capture the entire URI, or just save the {image_id} only. Pass the {image_id} as a path parameter in the getImage method to return the value needed to associate an image to a listing using the Trading and Inventory APIs.
See Managing images for additional details.
Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
https://apim.ebay.com/commerce/media/v1_beta/image/{image_id} All images must comply with eBay’s picture requirements, such as dimension and file size restrictions. For more information, see Picture policy. The image formats supported are JPG, GIF, PNG, BMP, TIFF, AVIF, HEIC, and WEBP. In addition, the provided URL must be secured using HTTPS (HTTP is not permitted). For more information, see Image requirements.
Note: Animated GIF, and multi-page PNG/TIFF files, are not supported. Any animation effect of supported formats will be lost upon upload.
When an EPS image is successfully created, the method returns the HTTP Status Code 201 Created. The method also returns the getImage URI in the Location response header.
Important! Make sure to capture the image ID URI returned in the response location header provided in the following format:
https://apim.ebay.com/commerce/media/v1_beta/image/{image_id}
You can capture the entire URI, or just save the {image_id} only. Pass the {image_id} as a path parameter in the getImage method to return the value needed to associate an image to a listing using the Trading and Inventory APIs.
See Managing images for additional details.
Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
https://apim.ebay.com/commerce/media/v1_beta/image/{image_id} 201 Created.The method also returns the location response header containing the video ID, which you can use to retrieve the video.Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
The video's title, size, classification, and description are set using the createVideo method.
The video's playList contains two URLs that link to instances of the streaming video based on the supported protocol.
The status field contains the current status of the video. After a video upload is successfully completed, the video's status will show as PROCESSING until the video reaches one of the terminal states of LIVE, BLOCKED or PROCESSING_FAILED.
If a video's 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.
The status message will indicate why a video was blocked from uploading.
If a video is not being used on an active listing, its expiration date is automatically set to 30 days after the video's initial upload.
The video's thumbnail image is automatically generated when the video is created.",
"operationId": "getVideo",
"parameters": [
{
"name": "video_id",
"in": "path",
"description": "The unique identifier of the video to be retrieved.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/Video"
}
}
}
},
"400": {
"description": "Bad Request"
},
"403": {
"description": "Forbidden",
"x-response-codes": {
"errors": {
"190013": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "Unauthorized access."
}
}
}
},
"404": {
"description": "Not Found",
"x-response-codes": {
"errors": {
"190001": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The specified video_Id does not exist."
}
}
}
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"190000": {
"domain": "API_MEDIA",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory"
]
}
]
}
},
"/video/{video_id}/upload": {
"post": {
"tags": [
"video"
],
"description": "This method associates the specified file with the specified video ID and uploads the input file. After the file has been uploaded the processing of the file begins.
Note: The size of the video to be uploaded must exactly match the size of the video's input stream that was set in the createVideo method. If the sizes do not match, the video will not upload successfully.
When a video is successfully uploaded, it returns the HTTP Status Code 200 OK.
The status flow is PENDING_UPLOAD > PROCESSING > LIVE, PROCESSING_FAILED, or BLOCKED. After a video upload is successfully completed, the status will show as PROCESSING until the video reaches one of the terminal states of LIVE, BLOCKED, or PROCESSING_FAILED. If the size information (in bytes) provided is incorrect, the API will throw an error.
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.
To retrieve an uploaded video, use the getVideo method.
Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
application/octet-stream.",
"required": true,
"schema": {
"type": "string"
}
},
{
"name": "video_id",
"in": "path",
"description": "The unique identifier of the video to be uploaded.",
"required": true,
"schema": {
"type": "string"
}
}
],
"responses": {
"200": {
"description": "OK"
},
"400": {
"description": "Bad Request",
"x-response-codes": {
"errors": {
"190007": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The content length does not match the content size specified."
},
"190010": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The video's Content-Range is invalid. The Content-Range should be of the following bytes ((?:[0-9]+-[0-9]+)|\\\\\\\\*)/([0-9]+|\\\\\\\\*) pattern."
},
"190012": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The content length of the video is invalid."
},
"190015": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The uploaded content must match the video size."
}
}
}
},
"403": {
"description": "Forbidden",
"x-response-codes": {
"errors": {
"190013": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "Unauthorized access."
}
}
}
},
"404": {
"description": "Not Found",
"x-response-codes": {
"errors": {
"190001": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The specified video_Id does not exist."
}
}
}
},
"409": {
"description": "Conflict",
"x-response-codes": {
"errors": {
"190011": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The video is already uploaded."
}
}
}
},
"411": {
"description": "Content Length Required",
"x-response-codes": {
"errors": {
"190008": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The content length is required."
}
}
}
},
"416": {
"description": "Range Not Satisfiable",
"x-response-codes": {
"errors": {
"190009": {
"domain": "API_MEDIA",
"category": "REQUEST",
"description": "The Content-Range specified is incorrect. Use Content-Range: bytes {1}}-{2}/{3} and Content-Length:{4} headers."
}
}
}
},
"500": {
"description": "Internal Server Error",
"x-response-codes": {
"errors": {
"190000": {
"domain": "API_MEDIA",
"category": "APPLICATION",
"description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance."
}
}
}
}
},
"security": [
{
"api_auth": [
"https://api.ebay.com/oauth/api_scope/sell.inventory"
]
}
]
}
},
"/document": {
"post": {
"tags": [
"document"
],
"description": "This method stages a document to be uploaded, and requires the type of document to be uploaded, and the language(s) that the document contains. A successful call returns a documentId value that is then used as a path parameter in an uploadDocument call.When a document is successfully created, the method returns the HTTP Status Code 201 Created. The method returns documentId in the response payload, which you can use to retrieve the document resource. This ID is also returned in the location header, for convenience.
Important! Make sure to capture the document ID value returned in the response payload. This value is required to use the other methods in the document resource, and also needed to associate a document to a listing using the Trading and Inventory APIs.
To upload a created document, use the document ID returned from this method's response with the uploadDocument method. See Managing documents for information on creating, uploading, and adding documents to listings.
Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
201 Created. The method returns documentId in the response payload, which you can use to retrieve the document resource. This ID is also returned in the location header, for convenience.Important! Make sure to capture the document ID value returned in the response payload. This value is required to use the other methods in the document resource, and also needed to associate a document to a listing using the Trading and Inventory APIs.
ACCEPTED. Only documents with this status can be added to a listing. See Managing documents for more information on creating, uploading, and adding documents to listings.Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
Important! The document ID value returned in the response payload of the createDocument method is a required input path parameter for this method.
See Managing documents for additional information.
", "operationId": "getDocument", "parameters": [ { "name": "document_id", "in": "path", "description": "The unique identifier of the document for which status and metadata is being retrieved.200 OK.See Managing documents for additional information.
Note: You must use a Content-Type header with its value set to multipart/form-data.This call does not have a JSON Request payload but uploads the file as form-data. For example:file: @"/C:/Users/.../drone_user_warranty.pdf"See Samples for information.
Important!All POST methods in the Media API, including this method, are subject to short-duration rate limits at the user level: 50 requests per 5 seconds.
Note: After a document is uploaded (but not yet published), its status is SUBMITTED. Once its identifier is linked to a post‑order entity through an eBay GraphQL mutation, the status changes to PUBLISHED. A post-order entity is part of eBay's order management for activities after purchase (such as returns).
Important! The document must be in the SUBMITTED or PUBLISHED state to be downloadable. All documents (published or submitted) expire and become inaccessible after their expiration date.
Note: After a document is uploaded (but not yet published), its status is SUBMITTED. When its identifier is associated with a post‑order entity through an eBay GraphQL mutation, the status changes to PUBLISHED. A post-order entity is part of eBay's order management for activities after purchase (such as returns).
Important! All documents, whether submitted or published, expire and become inaccessible after their expiration date.
Supported file types include .PDF, .JPEG/.JPG, .BMP, .GIF and .PNG, with a maximum file size of 5 MB (5,242,880 bytes).
Note: Animated and multi-page PNG files are not currently supported. For multi-page content, use PDF. The maximum number of pages allowed varies by the documentUsageType.
Send a multipart/form‑data request with:
key: file)RETURN_SHIPPING_LABELRETURNSA successful call returns the HTTP Status Code 201 Created with the document ID in the Location header (no response body is returned). The document’s initial state is SUBMITTED. When its identifier is associated with a post-order entity through an eBay GraphQL mutation, the state changes to PUBLISHED.
Note: A post-order entity is part of eBay's order management for activities after purchase (such as returns).
Important!
https://apiz.ebay.com/commerce/media/v1_beta/post_order/document/{documentId}Clients can extract the documentId from this URI to perform subsequent operations such as downloadDocument or removeDocument (using this resource), or to associate this document with a post-order entity (such as through an eBay GraphQL mutation).
" } } }, "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "description": "Bad Request", "x-response-codes": { "errors": { "190303": { "domain": "API_MEDIA", "category": "REQUEST", "description": "Invalid post-order entity type supplied in the request." }, "190304": { "domain": "API_MEDIA", "category": "REQUEST", "description": "Invalid document usage type supplied in the request." }, "190305": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The post-order entity type is missing from the request." }, "190306": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The post-order entity identifier is missing from the request." }, "190307": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The document usage type is missing from the request." }, "190309": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The uploaded file format is not supported. Supported formats are: jpeg, png, bmp, gif, jpg, and pdf." }, "190310": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The uploaded PDF exceeds the maximum allowed number of pages." }, "190311": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The post-order entity state does not allow new documents for the specified usage type." }, "190312": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The maximum number of documents for the specified post-order entity has been reached." }, "190313": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The uploaded file could not be processed. Please upload a valid file." }, "190314": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The uploaded file exceeds the maximum allowed size of 5 MB." }, "190315": { "domain": "API_MEDIA", "category": "REQUEST", "description": "The file is missing from the request. Please upload a valid file." } } } }, "401": { "description": "Unauthorized", "x-response-codes": { "errors": { "190013": { "domain": "API_MEDIA", "category": "REQUEST", "description": "Unauthorized access." } } } }, "404": { "description": "Not Found", "x-response-codes": { "errors": { "190300": { "domain": "API_MEDIA", "category": "REQUEST", "description": "Invalid or unknown post-order entity identifier supplied in the request." } } } }, "500": { "description": "Internal Server Error", "x-response-codes": { "errors": { "190000": { "domain": "API_MEDIA", "category": "APPLICATION", "description": "There was a problem with an eBay internal system or process. Contact eBay developer support for assistance." } } } } }, "security": [ { "api_auth": [ "https://api.ebay.com/oauth/api_scope/commerce.post_order.document" ] } ] }, "servers": [ { "url": "https://apiz.ebay.com{basePath}", "description": "Production", "variables": { "basePath": { "default": "/commerce/media/v1_beta" } } } ] } }, "components": { "schemas": { "CreateDocumentFromUrlRequest": { "type": "object", "properties": { "documentType": { "type": "string", "description": "The type of the document being created. For example, aUSER_GUIDE_OR_MANUAL or a SAFETY_DATA_SHEET. For implementation help, refer to eBay API documentation"
},
"documentUrl": {
"type": "string",
"description": "The URL of the document being created.USER_GUIDE_OR_MANUAL or a SAFETY_DATA_SHEET. For implementation help, refer to eBay API documentation"
},
"languages": {
"type": "array",
"description": "This array shows the language(s) used in the document.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
}
},
"description": "This type contains the metadata used to create the document ID."
},
"CreateDocumentResponse": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"description": "The unique identifier of the document to be uploaded.PENDING_UPLOAD is the initial state when the reference to the document has been created using the createDocument method. When creating a document using the createDocumentFromUrl method, the initial state will be SUBMITTED. For implementation help, refer to eBay API documentation"
},
"documentType": {
"type": "string",
"description": "The type of the document uploaded. For example, USER_GUIDE_OR_MANUAL. For implementation help, refer to eBay API documentation"
},
"languages": {
"type": "array",
"description": "This array shows the language(s) used in the document.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
}
},
"description": "This type provides information about the created document ID."
},
"CreateImageFromUrlRequest": {
"type": "object",
"properties": {
"imageUrl": {
"type": "string",
"description": "The image URL of the self-hosted picture to upload to eBay Picture Services (EPS). In addition to the picture requirements in Picture policy, the provided URL must be secured using HTTPS (HTTP is not permitted). For more information, see Image requirements."
}
},
"description": "A type that provides the location of the image."
},
"CreateVideoRequest": {
"type": "object",
"properties": {
"classification": {
"type": "array",
"description": "The intended use for this video content. Currently, videos can only be added and associated with eBay listings, so the only supported value is ITEM.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"description": {
"type": "string",
"description": "The description of the video."
},
"size": {
"type": "integer",
"description": "The size, in bytes, of the video content. drone_user_warranty.pdf)."
},
"fileSize": {
"type": "string",
"description": "The size, in bytes, of the document content."
},
"fileType": {
"type": "string",
"description": "The type of the file uploaded. Supported file types include the following: pdf, jpeg, jpg, and png."
}
},
"description": "This type provides information about the documentId."
},
"DocumentResponse": {
"type": "object",
"properties": {
"documentId": {
"type": "string",
"description": "The unique ID of the document."
},
"documentMetadata": {
"description": "This container provides the name, size, and type of the specified file.",
"$ref": "#/components/schemas/DocumentMetadata"
},
"documentStatus": {
"type": "string",
"description": "The status of the document resource.SUBMITTED. The document will then either be accepted or rejected. Only documents with the status of ACCEPTED are available to be added to a listing. For implementation help, refer to eBay API documentation"
},
"documentType": {
"type": "string",
"description": "The type of the document uploaded. For example, USER_GUIDE_OR_MANUAL. For implementation help, refer to eBay API documentation"
},
"languages": {
"type": "array",
"description": "This array shows the language(s) used in the document.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
}
},
"description": "This type provides information returned about a created document ID, which may or may not have been uploaded."
},
"Error": {
"type": "object",
"properties": {
"category": {
"type": "string",
"description": "Identifies the type of erro."
},
"domain": {
"type": "string",
"description": "Name for the primary system where the error occurred. This is relevant for application errors."
},
"errorId": {
"type": "integer",
"description": "A unique number to identify the error.",
"format": "int32"
},
"inputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"longMessage": {
"type": "string",
"description": "A more detailed explanation of the error."
},
"message": {
"type": "string",
"description": "Information on how to correct the problem, in the end user's terms and language where applicable."
},
"outputRefIds": {
"type": "array",
"description": "An array of request elements most closely associated to the error.",
"items": {
"type": "string"
}
},
"parameters": {
"type": "array",
"description": "An array of name/value pairs that describe details the error condition. These are useful when multiple errors are returned.",
"items": {
"$ref": "#/components/schemas/ErrorParameter"
}
},
"subdomain": {
"type": "string",
"description": "Further helps indicate which subsystem the error is coming from. System subcategories include: Initialization, Serialization, Security, Monitoring, Rate Limiting, etc."
}
},
"description": "This type defines the fields that can be returned in an error."
},
"ErrorParameter": {
"type": "object",
"properties": {
"name": {
"type": "string",
"description": "The object of the error."
},
"value": {
"type": "string",
"description": "The value of the object."
}
}
},
"Image": {
"type": "object",
"properties": {
"imageUrl": {
"type": "string",
"description": "The URL of the image's location."
}
},
"description": "A type that provides the location of the image."
},
"ImageResponse": {
"type": "object",
"properties": {
"expirationDate": {
"type": "string",
"description": "The date and time when an unused EPS image will expire and be removed from the EPS server, in Coordinated Universal Time (UTC). As long as an EPS image is being used in an active listing, that image will remain on the EPS server and be accessible."
},
"imageUrl": {
"type": "string",
"description": "The EPS URL to access the uploaded image. This URL will be used in listing calls to add the image to a listing."
},
"maxDimensionImageUrl": {
"type": "string",
"description": "The EPS URL to access the maximum dimension version of the uploaded image."
}
},
"description": "A type that provides an image's details including its URL and expiration."
},
"Moderation": {
"type": "object",
"properties": {
"rejectReasons": {
"type": "array",
"description": "The reason(s) why the specified video was blocked by moderators.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
}
},
"description": "A container that provides video moderation information when calling the getVideo method.LIVE. The supported streaming video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming)."
},
"Video": {
"type": "object",
"properties": {
"classification": {
"type": "array",
"description": "The intended use for this video content. Currently, videos can only be added and associated with eBay listings, so the only supported value is ITEM.",
"items": {
"type": "string",
"description": " For implementation help, refer to eBay API documentation"
}
},
"description": {
"type": "string",
"description": "The description of the video. The video description is an optional field that can be set using the createVideo method."
},
"expirationDate": {
"type": "string",
"description": "The date and time when an unused video will expire and be removed from the eBay Video Services server, in Coordinated Universal Time (UTC).BLOCKED, ensure that the video complies with eBay's video formatting and content guidelines. Afterwards, begin the video creation and upload procedure anew using the createVideo and uploadVideo methods.",
"$ref": "#/components/schemas/Moderation"
},
"playLists": {
"type": "array",
"description": "The playlist created for the uploaded video, which provides the streaming video URLs to play the video. The supported streaming video protocols are DASH (Dynamic Adaptive Streaming over HTTP) and HLS (HTTP Live Streaming). The playlist will only be generated if a video is successfully uploaded with a status of LIVE.",
"items": {
"$ref": "#/components/schemas/Play"
}
},
"size": {
"type": "integer",
"description": "The size, in bytes, of the video content.",
"format": "int32"
},
"status": {
"type": "string",
"description": "The status of the current video resource. For implementation help, refer to eBay API documentation"
},
"statusMessage": {
"type": "string",
"description": "The statusMessage field contains additional information on the status. For example, information on why processing might have failed or if the video was blocked."
},
"thumbnail": {
"description": "The URL of the thumbnail image of the video. The thumbnail image's URL must be an eBayPictureURL (EPS URL).",
"$ref": "#/components/schemas/Image"
},
"title": {
"type": "string",
"description": "The title of the video."
},
"videoId": {
"type": "string",
"description": "The unique ID of the video."
}
},
"description": "A response field that retrieves all the metadata for the video, including its title, classification, size, description, status, status message (if any), and expiration date."
}
},
"securitySchemes": {
"api_auth": {
"type": "oauth2",
"description": "The security definitions for this API. Please check individual operations for applicable scopes.",
"flows": {
"authorizationCode": {
"authorizationUrl": "https://auth.ebay.com/oauth2/authorize",
"tokenUrl": "https://api.ebay.com/identity/v1/oauth2/token",
"scopes": {
"https://api.ebay.com/oauth/api_scope/sell.inventory": "View and manage your inventory and offers"
}
}
}
}
}
}
}