eBay Post-Order APIVersion 2.7.7
 

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.

This method is not supported in the Sandbox environment.

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:
  • Create Return Request POST /post-order/v2/return
  • Issue Return Refund POST /post-order/v2/return/{returnId}/issue_refund
  • Mark Return Refund Sent POST /post-order/v2/return/{returnId}/mark_refund_sent
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).

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:

FAILED
This enumeration value indicates that the buyer refund transaction failed.
PENDING
This enumeration value indicates that the buyer refund is in the pending state.
REQUESTED
This enumeration value indicates that a refund has been requested by the buyer.
SUCCESS
This enumeration value indicates that the buyer refund was successful.
UNKNOWN
This enumeration value indicates that the result of the buyer refund transaction is unknown.

Code so that your app gracefully handles any future changes to this list.
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.

Sample: Basic Call

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
}



Change History

Change Date Description