Upload Return File

POST /post-order/v2/return/{returnId}/file/upload

This method may be used on behalf of a seller or buyer to upload files associated with a return request. These files may be shipping labels, pictures that illustrate the condition of an item, or perhaps images that show proof of a refund or other refund-related information.

If a seller is responsible for return shipping costs, and the seller will provide the buyer with their own return shipping label (instead of shipping label generated by eBay), this method may be used to upload the seller's return shipping label. Then, the seller will call the POST /post-order/v2/return/{returnId}/add_shipping_label method to generate and make this return shipping label available to the buyer.

This method is not supported in the Sandbox environment.

Input

Resource URI (production)

POST https://api.ebay.com/post-order/v2/return/{returnId}/file/upload

URI parameters

Parameter	Type	Required?	Meaning
returnId	string	Required	The unique eBay-assigned ID of the return request. The returnId value is required as part of the call URI to identify the return request for which files are being added.

HTTP request headers

All requests made to eBay REST operations require you to provide the authorization HTTP header for authentication.
See HTTP request headers for details.

Authorization

This call uses standard authorization tokens. See Making a Call for details.

Payload model

The following lists all fields that could be included in the request.

{ /* UploadFileRequest */
"data": string,
"fileName": string,
"filePurpose": string
}

Request field descriptions

Input Container/Field	Type	Occurrence	Meaning
data	string	Required	The input for this field is a base64-encoded binary representation of the file you are uploading. For images, the system accepts BMP, GIF, JPEG, and PNG files. For shipping labels, the system accepts either an image (BMP, GIF, JPEG, and PNG files) or a PDF file. Note: The data field supports single-time base64 encoding. For backward compatibility, the data field also presently supports double base64 encoding.
fileName	string	Required	This field is used to name the file that is being uploaded. Naming a file may make it easier for the buyer or seller to keep track of their files, instead of having to remember the fileId value (which is returned in the response) of each file.
filePurpose	string	Required	The enumeration value supplied in this required field indicates the purpose of the file that you're uploading. One of the values defined in the FilePurposeEnum type definition must be used in this field. Applicable values are from FilePurposeEnum: ITEM_RELATED This enumeration value indicates that the file is intended to provide more information about the item. For example, in a case where the buyer and seller are in disagreement over the condition of the item, the buyer or seller may provide a photo of the item that visually shows the condition of the item. LABEL_RELATED This enumeration value indicates that the file is intended to provide more information about a shipping label or shipment tracking information. For example, in a case where the buyer and seller are in disagreement over whether shipment tracking information has been provided or not, the buyer or seller may provide a photo of the shipping label itself, or they may provide a file that proves a package has been shipped or delivered. REFUND_RELATED This enumeration value indicates that the file is intended to provide more information about a buyer refund. For example, in a case where the buyer is saying that they have not recieved their refund, the seller may provide a file that proves that a refund has been issued. UNKNOWN This enumeration value should not be used in a Submit/Upload File request, but it is possible that this value may get returned in a response if the purpose of the file is not known.

Output

Payload model

Note: For information about the error fields and how to work with them, see Error Handling.

The following lists all fields that could be included in the response.

Supported response formats: application/json, application/xml

For more information:
- See UploadFileResponse for a description of the response structure
- See the following table for descriptions of each of the data elements returned
- See the Samples for an example of the response format

{ /* UploadFileResponse */
"compressedFileData": string,
"fileId": string
}

Response field descriptions

Output Container/Field	Type	Occurrence	Meaning
compressedFileData	string	Conditionally	This field is the base64-encoded binary representation of the compressed version of the file that was uploaded with the request. This field will be returned if the file was successfully associated to the return request or return request draft.
fileId	string	Conditionally	This is unique eBay-assigned ID of the file associated with a return request or return request draft. This field will be returned if the file was successfully associated to the return request or return request draft.

null

Samples

New to making API calls? Please see Making a Call.

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

Available samples:

Upload an Item Condition File ↓ - This sample attaches an image file (related to the condition of the item) to a return request.
Upload a Shipping Label File ↓ - This sample attaches a shipping label image file to a return request.

Sample: Upload an Item Condition File

This sample attaches an image file (related to the condition of the item) to a return request.

Description

In this sample, a buyer wants to upload an image that shows that the received item does not match the description in the item listing.

Input

The returnId path parameter identifies the return to which the image will be attached. Along with the image data, this call includes the name and extension of the file, which indicates the image format, and the filePurpose field, which identifies the type of information this image supports.

URL format. See also the non-wrapped version of this URL.

POST https://api.ebay.com/post-order/v2/return/5********1/file/upload
{
  "fileName" : "j******.jpeg",
  "data" : "S**************************************************************1",
  "filePurpose" : "ITEM_RELATED"
}

Output

The response payload includes an eBay-generated unique identifier for the image file and a compressed copy of the image data.

JSON format.
{
    "fileId": "5********2",
    "compressedFileData": "/9j/4***S...q**P/9k="
}

Back to list of samples

Sample: Upload a Shipping Label File

This sample attaches a shipping label image file to a return request.

Description

In this sample, a seller-generated shipping label is uploaded to the return request. Once a seller-generated shipping label is attached to the return request, the seller can make that shipping label available to the buyer by using the POST /post-order/v2/return/{returnId}/add_shipping_label call.

Input

URL format. See also the non-wrapped version of this URL.

POST https://api.ebay.com/post-order/v2/return/5********1/file/upload
{
  "fileName" : "5********1_s***********l.jpeg",
  "data" : "SGVyZSBpcyB5b3VyIHJld...YWNraW5nIG51bWJlciBpcyAxMjM0NTY3ODk4NzY1",
  "filePurpose" : "LABEL_RELATED"
}

Output

The response payload includes an eBay-generated unique identifier for the image file and a compressed copy of the image data. fileId value will actually be used in the POST /post-order/v2/return/{returnId}/add_shipping_label call that is used to make the shipping label available to the buyer.

JSON format.
{
    "fileId": "8******1",
    "compressedFileData": "/9j/4*********************D/7gAOQ ... G**************************P/2Q=="
}

Back to list of samples

Change History

Change Date	Description