eBay Post-Order APIVersion 2

Issue Return Refund

POST /post-order/v2/return/{returnId}/issue_refund

The seller uses this call to issue a refund to the buyer.

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 identifier of the return. The returnId value is required to identify the return 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 */
    "itemizedRefundDetail": [
        { /* ItemizedRefundDetailType */
        "refundAmount":
            { /* Amount */
            "convertedFromCurrency": string,
            "convertedFromValue": number,
            "currency": string,
            "value": number
            },
        "refundFeeType": string,
        "restockingFeePercentage": string
        }
        /* More ItemizedRefundDetailType nodes here */
      ],
    "totalAmount":
        { /* Amount */
        "convertedFromCurrency": string,
        "convertedFromValue": number,
        "currency": string,
        "value": number
        }
    },
"relistItem": boolean
}

Request field descriptions



Input Container/Field Type Occurrence Meaning
comments Text Optional Optional container that allows the seller 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.

Applicable values are from LanguageEnum:See language.
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.

Applicable values are from LanguageEnum:See translatedFromLanguage.
refundDetail RefundDetailType Required This container is used to specify the total amount of the refund, as well as an itemizedRefundDetail container 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
  .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 call to issue a refund, or when using the POST /post-order/v2/return/{returnId}/mark_refund_sent call to mark a refund as sent. In the POST /post-order/v2/return and GET /post-order/v2/return/{returnId} calls, this container will be returned under the actualRefund container if a refund has occurred.
refundDetail
  .itemizedRefundDetail
  .refundAmount
Amount Required This dollar value is 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 call, or if marking a refund as sent with the POST /post-order/v2/return/{returnId}/mark_refund_sent call, the seller must use a separate itemizedRefundDetail container for each refund type, such as one for the purchase price, one for original shipping, and one for a restocking fee (if applicable).
refundDetail
  .itemizedRefundDetail
  .refundAmount
  .convertedFromCurrency
string Conditional This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
refundDetail
  .itemizedRefundDetail
  .refundAmount
  .convertedFromValue
number Conditional This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
refundDetail
  .itemizedRefundDetail
  .refundAmount.currency
string Conditional This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
refundDetail
  .itemizedRefundDetail
  .refundAmount.value
number Conditional The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
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 call, or if marking a refund as sent with the POST /post-order/v2/return/{returnId}/mark_refund_sent call, the seller must use a separate itemizedRefundDetail container for each refund type, such as one for the purchase price, one for original shipping, and one for a restocking fee (if applicable).

Applicable values are from RefundFeeTypeEnum:See refundFeeType.
refundDetail
  .itemizedRefundDetail
  .restockingFeePercentage
string Conditional Indicates the restocking fee (as a percentage of the purchase price) charged by the seller for returned items. In order to charge the buyer a restocking fee when an item is returned, a US seller must input a restocking fee value as part of the return policy.

To obtain the list of applicable values, call GeteBayDetails of the Trading API with the DetailName field value set to ReturnPolicyDetails. Then look for the list of restocking fee value options in the ReturnPolicyDetails.RestockingFeeValue container in the response.

This field is only applicable (and necessary to include in the request payload) if the refundFeeType value is RESTOCKING_FEE.
refundDetail.totalAmount Amount Required This value is 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 call to issue a refund, or when using the POST /post-order/v2/return/{returnId}/mark_refund_sent call to mark a refund as sent. In the POST /post-order/v2/return and GET /post-order/v2/return/{returnId} calls, this container will be returned under the actualRefund container if a refund has occurred.
refundDetail.totalAmount
  .convertedFromCurrency
string Conditional This field indicates the currency involved in a monetary transaction before a price conversion was performed. Generally, this is the currency used by the buyer. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.

Applicable values are from CurrencyCodeEnum:See convertedFromCurrency.
refundDetail.totalAmount
  .convertedFromValue
number Conditional This value is the dollar amount of the currency involved in a monetary transaction before a price conversion was performed. This field is only applicable if a price conversion was necessary, and a price conversion is generally necessary if the buyer and seller are using different forms of currency.
refundDetail.totalAmount
  .currency
string Conditional This field indicates the currency involved in a monetary transaction. Generally, this is the currency used by the listing site's country.

Applicable values are from CurrencyCodeEnum:See currency.
refundDetail.totalAmount.value number Conditional The dollar value of the currency specified in the currency field. The value of currency defaults to the standard currency used by the country of the listing site.
relistItem boolean Optional If set to true, the returned item will be relisted automatically when the refund 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": token
}

Response field descriptions



Output Container/Field Type Occurrence Meaning
refundStatus token Always The value in this field indicates whether or not the refund operation was successful. If the 'PENDING' value is returned, it indicates that the refund is happening outside of PayPal 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: See RefundStatusEnum



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/5000080362/issue_refund

{ 
"comments":
    { 
    "content": "Here is your refund for return request #5000080362. 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