eBay Post-Order APIVersion 2

Create Return Draft

POST /post-order/v2/return/draft

Use this call to create a return draft. This call is very similar to the POST /post-order/v2/return call except a live return request is not actually created. The PUT /post-order/v2/return/draft/{draftId} call is used to update a return draft, and the POST /post-order/v2/return call is used to convert the draft into an actual request, with the added requirement of passing in the draftId value in the request payload of that call.

Input

See also Samples.

Resource URI (production)

POST https://api.ebay.com/post-order/v2/return/draft

This call has no path or query parameters.


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.

{ /* SetReturnCreationSessionRequest */
"returnRequest":
    { /* ReturnRequestType */
    "carrier": token,
    "comments":
        { /* Text */
        "content": string,
        "language": string,
        "translatedFromContent": string,
        "translatedFromLanguage": string
        },
    "itemId": string,
    "reason": string,
    "requestType": token,
    "returnQuantity": integer,
    "transactionId": string,
    "type": string
    }
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
returnRequest ReturnRequestType Required This container is used in the POST /post-order/v2/return/draft and PUT /post-order/v2/return/draft/{draftId} calls to provide details about the buyer's return request, including the order line item (and quantity) that is being returned, the reason for the return, and the buyer's preference to either get money back for item or to get a replacement item from the seller. If an existing return draft is being updated with the PUT /post-order/v2/return/draft/{draftId} call, all fields of the returnRequest must be included in the call, not just the fields whose values are changing.
returnRequest.carrier token Optional Indicates the shipping carrier that will be used to ship the return item. ShippingCarrierEnum contains some popular shipping carriers for the US, UK, Germany, Canada, and Australia, but it is not a complete list.

Applicable values: See ShippingCarrierEnum
returnRequest.comments Text Optional This optional container allows the buyer to provide more information to the seller about why the item is being returned.
returnRequest.comments.content string Conditional This field displays the actual textual content in the language specified in the language field. This field is always used for containers using the Text type.
returnRequest.comments
  .language
string Conditional This two-letter code indicates the language used to display the content in the content field. The language will default to the language used on the eBay site if a specific language is not specified through the Accept-Language HTTP header. This field is always used for containers using the Text type.

Applicable values are from LanguageEnum:See language.
returnRequest.comments
  .translatedFromContent
string Conditional If language translation/localization is required, this field displays the actual textual content in the language specified in the translatedFromLanguage field. If language translation was not required, this field is not applicable.
returnRequest.comments
  .translatedFromLanguage
string Conditional If language translation/localization is required, this two-letter code indicates the language used to display the content in the translatedFromContent field. If language translation was not required, this field is not applicable.

Applicable values are from LanguageEnum:See translatedFromLanguage.
returnRequest.itemId string Required The unique identifier of a listing. The itemID and transactionId fields are required to identify the order line item for which a return (or return draft) is being requested by the buyer.
returnRequest.reason string Optional This enumerated value indicates the buyer's reason for creating a return request or draft.

Applicable values are from ReturnReasonEnum:See reason.
returnRequest.requestType token Required This enumeration value indicates if the return request is an actual return request or a return draft.

Applicable values: See RequestTypeEnum
returnRequest.returnQuantity integer Optional This integer value indicates the quantity of the line item being returned. This number is generally '1', unless the buyer bought multiple quantity of the item in a multiple-quantity, fixed-price listing. This value defaults to '1' if this field is omitted when a return is created.
returnRequest.transactionId string Required The unique identifier of a transaction. The itemID and transactionId fields are required to identify the order line item for which a return (or return draft) is being requested by the buyer.
returnRequest.type string Optional This enumeration value indicates the buyer's desired outcome - money back for the order or a replacement item (in the case of a SNAD item). MONEY_BACK is the default value.

Applicable values are from ReturnTypeEnum:

CANCEL
This value is passed into the type field of the request when the buyer wants to cancel a return request (or draft).
MONEY_BACK
This value is passed into the type field of the request when the buyer is creating a return request (or draft), and wants a full refund after returning the item.
REPLACEMENT
This value is passed into the type field of the request when the buyer is creating a return request (or draft), but wants a replacement item instead of a refund.
UNKNOWN
This is the default value if the return type is not known.

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 SetReturnCreationSessionResponse 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

{ /* SetReturnCreationSessionResponse */
"draftId": integer
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
draftId integer Conditionally The unique identifier of a new return draft that was created with the POST /post-order/v2/return/draft call, or an existing draft that was updated with the PUT /post-order/v2/return/draft/{draftId} call.



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.

Sample: Create a return

This operation creates a return draft.

Description

This buyer-facing call creates a return draft. Return drafts are converted to return requests using the POST /post-order/v2/return call.

Input

Use the itemId and transactionId fields to specify the order line item to be returned. Specify a reason as well as the action (the returnRequest.type) to inform the seller of the details of the return.

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

POST https://api.ebay.com/post-order/v2/return/draft

{ 
"returnRequest":
    { 
    "itemId": "330005959274",
    "transactionId": "8905715014",
    "returnQuantity": "1",
    "reason": "NO_LONGER_NEED_ITEM",
    "type": "MONEY_BACK",
    "carrier": "USPS",
    "comments":
        { 
        "content": "I accidentally purchased the same product twice"
        }
    }
}

Output

The call returns a draftId that you use to reference the return draft in other calls.

JSON format.
{
  "draftId": "500877800"
}



Change History

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