eBay Post-Order APIVersion 2

Upload Return File

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

Use this call to upload files associated with a return request. These files will either be return shipping labels (or related to return shipping) or they may be pictures that illustrate the condition of an item.

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 call must be used to upload the seller's return shipping label. Then, the seller will run the POST /post-order/v2/return/{returnId}/add_shipping_label to generate and make this return shipping label available to the buyer.

Input

See also Samples.

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 identifier of the return. The returnId value is required to identify the return 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
    /* More string nodes here */
  ],
"fileName": string,
"filePurpose": token
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
data array of string Required This field is the base64-encoded binary representation of the file identified in the fileName field. In certain programming languages such as PHP, the file should be base64 encoded twice.
fileName string Optional This field is used to name the file that is being uploaded. This field is optional, but 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 call response) of each file.
filePurpose token Required This value is used to indicate if the file is being used to provide more information about the condition of the item or intended to provide more information about shipment tracking or the shipping label. See the FilePurposeEnum type for supported values for this field.

Applicable values: See FilePurposeEnum

Output

See also Samples.

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 file identified in the fileName field. This field will only be returned if the file was successfully associated to the return request or draft.
fileId string Conditionally This is unique identifier of the file associated with a return request or draft. This field will only be returned if the file was successfully associated to the return request or draft. This value will be needed if the seller is going to use the POST /post-order/v2/return/{returnId}/add_shipping_label call to provide a non-eBay generated return shipping label to the buyer.
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:

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/5000124931/file/upload
{
  "fileName" : "jasmine.jpeg",
  "data" : "SGVyZSBpcyB5b3VyIHJld...YWNraW5nIG51bWJlciBpcyAxMjM0NTY3ODk4NzY1",
  "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": "5000013622",
    "compressedFileData": "/9j/4AAQS...q7DP/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

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 indicates that the image is a shipping label.

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

POST https://api.ebay.com/post-order/v2/return/5000124931/file/upload
{
  "fileName" : "5000124931_shippinglabel.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": "80034841",
    "compressedFileData": "/9j/4AAQSkZJRgABAgEAYABgAAD/7gAOQ ... GBtPT2oqjDGhU5X+I0Vi+a+jOpRP/2Q=="
}


Back to list of samples



Change History

Change Date Description
1.0
2015-06-30
  • Call (added): New call.