Issue Return Refund
POST /post-order/v2/return/{returnId}/issue_refund
This method can be used on behalf of the seller to issue a refund to the buyer.
Important! Due to EU & UK Payments regulatory requirements, an additional security verification via Digital Signatures is required for certain API calls that are made on behalf of EU/UK sellers, including this method. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signature to be included in the HTTP payload.
Output Samples Change History |
Input
See also Samples.
Resource URI (production)
POST https://api.ebay.com/post-order/v2/return/{returnId}/issue_refund
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 a refund is being given. |
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.
{ /* IssueRefundRequest */ "comments": { /* Text */ "content": string, "language": string, "translatedFromContent": string, "translatedFromLanguage": string }, "refundDetail": { /* RefundDetailType */ "donationAmount": { /* Amount */ "convertedFromCurrency": string, "convertedFromValue": number, "currency": string, "exchangeRate": string, "value": number }, "feeCreditAmount": { /* Amount */ "convertedFromCurrency": string, "convertedFromValue": number, "currency": string, "exchangeRate": string, "value": number }, "itemizedRefundDetail": [ { /* ItemizedRefundDetailType */ "refundAmount": { /* Amount */ "convertedFromCurrency": string, "convertedFromValue": number, "currency": string, "exchangeRate": string, "value": number }, "refundFeeType": string, "restockingFeePercentage": string } /* More ItemizedRefundDetailType nodes here */ ], "totalAmount": { /* Amount */ "convertedFromCurrency": string, "convertedFromValue": number, "currency": string, "exchangeRate": string, "value": number } }, "relistItem": boolean }
Request field descriptions
Input Container/Field | Type | Occurrence | Meaning |
---|---|---|---|
comments | Text | Optional | This container is used if the seller wants to provide more information to the buyer about the refund that is being issued. |
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. |
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. The full list of language enumeration values are defined in the LanguageEnum type definition. Applicable values: See LanguageEnum |
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. |
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. The full list of language enumeration values are defined in the LanguageEnum type definition. Applicable values: See LanguageEnum |
refundDetail | RefundDetailType | Required | This container provides details on one or more refunds received by the buyer. An itemizedRefundDetail container is returned for each refund type (refund on purchase price, refund on original shipping, or any other costs paid by the buyer). The amount(s) in the itemizedRefundDetail.amount field(s) should equal the amount in the refundDetail.totalAmount field. |
refundDetail.donationAmount | Amount | Optional |
This container defines the refund amount for listings that included a charitable donation. This data includes the amount of the charitable donation refund, as well as currency conversion information when necessary including the current currency code, the value in the original currency, and the original currency's code. Note: This container is not applicable for the following methods:
|
refundDetail.donationAmount .convertedFromCurrency |
string | Optional |
The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail.donationAmount .convertedFromValue |
number | Optional |
The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated. |
refundDetail.donationAmount .currency |
string | Optional |
A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail.donationAmount .exchangeRate |
string | Optional | This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version. |
refundDetail.donationAmount .value |
number | Optional | The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type. |
refundDetail.feeCreditAmount | Amount | Optional | This container shows the total amount of fees credited towards this refund as per eBay policy. |
refundDetail.feeCreditAmount .convertedFromCurrency |
string | Optional |
The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail.feeCreditAmount .convertedFromValue |
number | Optional |
The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated. |
refundDetail.feeCreditAmount .currency |
string | Optional |
A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail.feeCreditAmount .exchangeRate |
string | Optional | This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version. |
refundDetail.feeCreditAmount .value |
number | Optional | The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type. |
refundDetail .itemizedRefundDetail |
array of ItemizedRefundDetailType | Required | This container is used to declare a refund that is being issued, or has been issued to the buyer. An itemizedRefundDetail container is required for each different refund type, such as purchase price and original shipping. This container is required when using the POST /post-order/v2/return/{returnId}/issue_refund method to issue a refund, or when using the POST /post-order/v2/return/{returnId}/mark_refund_sent method to mark a refund as sent. In the POST /post-order/v2/return and GET /post-order/v2/return/{returnId} methods, this container will be returned under the actualRefund container if a refund has occurred. |
refundDetail .itemizedRefundDetail .refundAmount |
Amount | Required | This container shows the amount of the refund for the particular refund type (specified in the refundFeeType field). When issuing a refund through the POST /post-order/v2/return/{returnId}/issue_refund method, or if marking a refund as sent with the POST /post-order/v2/return/{returnId}/mark_refund_sent method, the seller must use a separate itemizedRefundDetail container for each refund type, such as one for the purchase price, and one for original shipping. |
refundDetail .itemizedRefundDetail .refundAmount .convertedFromCurrency |
string | Optional |
The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail .itemizedRefundDetail .refundAmount .convertedFromValue |
number | Optional |
The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated. |
refundDetail .itemizedRefundDetail .refundAmount.currency |
string | Optional |
A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail .itemizedRefundDetail .refundAmount.exchangeRate |
string | Optional | This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version. |
refundDetail .itemizedRefundDetail .refundAmount.value |
number | Optional | The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type. |
refundDetail .itemizedRefundDetail .refundFeeType |
string | Required |
This enumerated value indicates the type of refund. When issuing a refund through the POST /post-order/v2/return/{returnId}/issue_refund method, or if marking a refund as sent with the POST /post-order/v2/return/{returnId}/mark_refund_sent method, the seller must use a separate itemizedRefundDetail container for each refund type, such as one for the purchase price, and one for original shipping. The supported enumeration values representing refund fee types are defined in the RefundFeeTypeEnum type definition. Applicable values: See RefundFeeTypeEnum |
refundDetail .itemizedRefundDetail .restockingFeePercentage |
string | Optional | THIS FIELD IS DEPRECATED. DO NOT USE. |
refundDetail.totalAmount | Amount | Required | This container shows the total cumulative amount of the refund issued to the buyer. This value should equal the sum of the values in the itemizedRefundDetail.refundAmount field(s). This container is required when using the POST /post-order/v2/return/{returnId}/issue_refund method to issue a refund, or when using the POST /post-order/v2/return/{returnId}/mark_refund_sent method to mark a refund as sent. In the POST /post-order/v2/return and GET /post-order/v2/return/{returnId} methods, this container will be returned under the actualRefund container if a refund has occurred. |
refundDetail.totalAmount .convertedFromCurrency |
string | Optional |
The three-letter ISO 4217 code representing the currency of the amount in the convertedFromValue field. This value is the pre-conversion currency. If no conversion occurs, this should not be populated. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail.totalAmount .convertedFromValue |
number | Optional |
The monetary amount before any conversion is performed, in the currency specified by the convertedFromCurrency field. This value is the pre-conversion amount. The value field contains the converted amount of this value, in the currency specified by the currency field. If no conversion occurs, this should not be populated. |
refundDetail.totalAmount .currency |
string | Optional |
A three-letter ISO 4217 code that indicates the currency of the amount in the value field. This field is always returned with any container using Amount type. The list of three-digit currency codes that may be returned in this field are defined in the CurrencyCodeEnum type definition. Applicable values: See CurrencyCodeEnum |
refundDetail.totalAmount .exchangeRate |
string | Optional | This field shows the exchange rate used to convert the amount in the convertedFromValue field to amount in the value field. This field is only returned when eBay does a currency version. |
refundDetail.totalAmount.value | number | Optional | The monetary amount, in the currency specified by the currency field. This field is always returned with any container using Amount type. |
relistItem | boolean | Optional |
This field should be included and set to true if the seller wants to relist/restock the returned item automatically after the refund operation succeeds. Sellers can check the eligibility for an item to be relisted by calling Get Return. In the response, check the itemDetail.relistStatus field for eligibility. This field will also show the status of a relist request as either SUCCESS (the relist succeeded) or FAILED (the relist request did not succeed). If the relist request succeeds, call Get Return and check the itemDetail.relistedItemId to get the listing ID of the newly relisted item (the ID should match the ID of the original item listing). |
Input Samples Change History |
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 IssueRefundResponse 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
{ /* IssueRefundResponse */ "refundStatus": string }
Response field descriptions
Output Container/Field | Type | Occurrence | Meaning |
---|---|---|---|
refundStatus | string | Always |
The value in this field indicates whether or not the refund operation was successful. If the PENDING value is returned, it may indicate that the refund is happening outside of eBay's system and there is no way for eBay to check the status of the refund. In this scenario, the seller should call POST /post-order/v2/return/{returnId}/mark_refund_sent to mark the refund as sent and/or the buyer should call POST /post-order/v2/return/{returnId}/mark_refund_received to mark the refund as received.
Applicable values are from Refund_MoneyMovementStatusEnum: Code so that your app gracefully handles any future changes to this list. |
Input Output Change History |
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.
Issuing a full refund for a return.
Description
A buyer has returned an item, the seller has received the return item, and now the seller is using this call to issue a full refund to the buyer.
Input
The seller passes in the return request ID as a path parameter in the URI. In the request payload, the seller includes the itemized list of refund types in the refundDetail.itemizedRefundDetail container. For this particular return request, the seller is refunding the buyer for the purchase price, original shipping costs, and return shipping costs. Although the container is optional, the seller also included a comment describing the refund action.
URL format. See also the non-wrapped version of this URL. POST https://api.ebay.com/post-order/v2/return/5********2/issue_refund { "comments": { "content": "Here is your refund for return request #5********2. I have refunded your purchase price, <br/> your original shipping costs, and your return shipping costs." }, "refundDetail": { "itemizedRefundDetail": [ { "refundAmount": { "value": 19.95, "currency": USD }, "refundFeeType": PURCHASE_PRICE }, { "refundAmount": { "value": 4.25, "currency": USD }, "refundFeeType": ORIGINAL_SHIPPING }, { "refundAmount": { "value": 4.25, "currency": USD }, "refundFeeType": RETURN_SHIPPING } ], "totalAmount": { "value": 28.45, "currency": USD } } }
Output
The refundStatus field indicates that the refund was successful.
JSON format.
{
"refundStatus": SUCCESS
}
Input Output Samples |
Change History
Change Date | Description |
---|