issueRefund: eBay Fulfillment API | eBay Developers Program

POST/order/{order_id}/issue_refund

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 issueRefund. Please refer to Digital Signatures for APIs to learn more on the impacted APIs and the process to create signatures to be included in the HTTP payload.

This method allows a seller to issue a full or partial refund to a buyer for an order. Full or partial refunds can be issued at the order level or line item level.

The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response.

Input

Resource URI

POST https://api.ebay.com/sell/fulfillment/v1/order/{order_id}/issue_refund

This method is supported in Sandbox environment. To access the endpoint, just replace the api.ebay.com root URI with api.sandbox.ebay.com

URI parameters

Parameter	Type	Description
order_id	string	This path parameter is used to specify the unique identifier of the order associated with a refund. Use the getOrders method to retrieve order IDs. Occurrence: Required

HTTP request headers

All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.

The table below shows additional HTTP request headers that are either required, conditionally required, or strongly recommended for this method. Other standard HTTP request headers- opens rest request components page (not in this table) can also be used, but they are optional.

Header	Type	Description
Content-Type	string	This header indicates the format of the request body provided by the client. Its value should be set to application/json. For more information, refer to HTTP request headers. Occurrence: Required

Header

Type

Description

Content-Type

string

This header indicates the format of the request body provided by the client. Its value should be set to application/json.

For more information, refer to HTTP request headers.

Occurrence: Required

OAuth scope

This request requires an access token created with the authorization code grant flow, using one or more scopes from the following list (please check your Application Keys page for a list of OAuth scopes available to your application):

https://api.ebay.com/oauth/api_scope/sell.finances

See OAuth access tokens for more information.

Request payload

Copy complete valid JSON to clipboard

{ /* IssueRefundRequest */

"reasonForRefund" : "ReasonForRefundEnum : [BUYER_CANCEL,SELLER_CANCEL,ITEM_NOT_RECEIVED...]",

"comment" : "string",

"refundItems" : [

{ /* RefundItem */

"refundAmount" :

{ /* SimpleAmount */

"currency" : "CurrencyCodeEnum",

"value" : "string"

"lineItemId" : "string",

"legacyReference" :

{ /* LegacyReference */

"legacyItemId" : "string",

"legacyTransactionId" : "string"

}

"orderLevelRefundAmount" :

{ /* SimpleAmount */

"currency" : "CurrencyCodeEnum",

"value" : "string"

}

Request fields

Input container/field	Type	Description
reasonForRefund	ReasonForRefundEnum	The enumeration value passed into this field indicates the reason for the refund. One of the defined enumeration values in the ReasonForRefundEnum type must be used. This field is required, and it is highly recommended that sellers use the correct refund reason, especially in the case of a buyer-requested cancellation or 'buyer remorse' return to indicate that there was nothing wrong with the item(s) or with the shipment of the order. Note: If issuing refunds for more than one order line item, keep in mind that the refund reason must be the same for each of the order line items. If the refund reason is different for one or more order line items in an order, the seller would need to make separate issueRefund calls, one for each refund reason. Occurrence: Required
comment	string	This free-text field allows the seller to clarify why the refund is being issued to the buyer. Max Length: 100 Occurrence: Optional
refundItems	array of RefundItem	The refundItems array is only required if the seller is issuing a refund for one or more individual order line items in a multiple line item order. Otherwise, the seller just uses the orderLevelRefundAmount container to specify the amount of the refund for the entire order. Occurrence: Conditional
refundItems.refundAmount	SimpleAmount	This container is used to specify the amount of the refund for the corresponding order line item. If a seller wants to issue a refund for an entire order, the seller would use the orderLevelRefundAmount container instead. Occurrence: Conditional
refundItems.refundAmount.currency	CurrencyCodeEnum	A three-letter ISO 4217 code (such as `USD` for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are required when expressing the amount of the refund. Occurrence: Conditional
refundItems.refundAmount.value	string	The monetary amount of the refund. Only use a maximum of two digits to the right of the decimal point. Both the value and currency fields are required when expressing the amount of the refund. Occurrence: Conditional
refundItems.lineItemId	string	The unique identifier of an order line item. This identifier is created once a buyer purchases a 'Buy It Now' item or if an auction listing ends with a winning bidder. Either this field or the legacyReference container is needed to identify an individual order line item that will receive a refund. This value is returned using the getOrders method. Occurrence: Conditional
refundItems.legacyReference	LegacyReference	This container is needed if the seller is issuing a refund for an individual order line item, and wishes to use an item ID/transaction ID pair to identify the order line item. Either this container or the lineItemId field is needed to identify an individual order line item that will receive a refund. Note: This container should only be used if a seller is using the GetOrders method of the Trading API. Occurrence: Conditional
refundItems.legacyReference.legacyItemId	string	The unique identifier of a listing. This value can be found in the Transaction container in the response of the getOrder call of the Trading API. Note: Both legacyItemId and legacyTransactionId are needed to identify an order line item. Occurrence: Conditional
refundItems.legacyReference.legacyTransactionId	string	The unique identifier of a sale/transaction in legacy/Trading API format. A 'transaction ID' is created once a buyer purchases a 'Buy It Now' item or if an auction listing ends with a winning bidder. This value can be found in the Transaction container in the response of the getOrder call of the Trading API. Note: Both legacyItemId and legacyTransactionId are needed to identify an order line item. Occurrence: Conditional
orderLevelRefundAmount	SimpleAmount	This container is used to specify the amount of the refund for the entire order. If a seller wants to issue a refund for an individual line item within a multiple line item order, the seller would use the refundItems array instead. Occurrence: Conditional
orderLevelRefundAmount.currency	CurrencyCodeEnum	A three-letter ISO 4217 code (such as `USD` for US site) that indicates the currency of the amount in the value field. Both the value and currency fields are required when expressing the amount of the refund. Occurrence: Conditional
orderLevelRefundAmount.value	string	The monetary amount of the refund. Only use a maximum of two digits to the right of the decimal point. Both the value and currency fields are required when expressing the amount of the refund. Occurrence: Conditional

Output

HTTP response headers

This call has no response headers.

Response payload

Copy complete valid JSON to clipboard

{ /* Refund */

"refundId" : "string",

"refundStatus" : "RefundStatusEnum : [FAILED,PENDING,REFUNDED]"

}

Response fields

Output container/field Type Description

Output container/field	Type	Description
refundId	string	The unique identifier of the order refund. This value is returned unless the refund operation fails (refundStatus value shows `FAILED`). This identifier can be used to track the status of the refund through a getOrder or getOrders call. For order-level refunds, check the paymentSummary.refunds.refundId field in the getOrder/getOrders response, and for line item level refunds, check the lineItems.refunds.refundId field(s) in the getOrder/getOrders response. Occurrence: Conditional
refundStatus	RefundStatusEnum	The value returned in this field indicates the success or failure of the refund operation. A successful issueRefund operation should result in a value of `PENDING`. A failed issueRefund operation should result in a value of `FAILED`, and an HTTP status code and/or and API error code may also get returned to possibly indicate the issue. The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response. Occurrence: Always

refundId

string

The unique identifier of the order refund. This value is returned unless the refund operation fails (refundStatus value shows FAILED). This identifier can be used to track the status of the refund through a getOrder or getOrders call. For order-level refunds, check the paymentSummary.refunds.refundId field in the getOrder/getOrders response, and for line item level refunds, check the lineItems.refunds.refundId field(s) in the getOrder/getOrders response.

Occurrence: Conditional

refundStatus

RefundStatusEnum

The value returned in this field indicates the success or failure of the refund operation. A successful issueRefund operation should result in a value of PENDING. A failed issueRefund operation should result in a value of FAILED, and an HTTP status code and/or and API error code may also get returned to possibly indicate the issue.

The refunds issued through this method are processed asynchronously, so the refund will not show as 'Refunded' right away. A seller will have to make a subsequent getOrder call to check the status of the refund. The status of an order refund can be found in the paymentSummary.refunds.refundStatus field of the getOrder response.

Occurrence: Always

HTTP status codes

This call can return one of the following HTTP status codes. For an overview of the status codes, see HTTP status codes in Using eBay RESTful APIs.

Status	Meaning
200	OK
400	Bad Request
403	Access Forbidden
404	Resource Not found
409	Conflict
500	Internal Server Error

Error codes

For more on errors, plus the codes of other common errors, see Handling errors.

Code	Domain	Category	Meaning
34900	API_FULFILLMENT	APPLICATION	There was a problem with an eBay internal system or process. Contact eBay developer support for assistance.
34901	API_FULFILLMENT	REQUEST	Order id can't be null or empty.
34902	API_FULFILLMENT	REQUEST	Request can't be empty.
34903	API_FULFILLMENT	REQUEST	The refund reason must be specified.
34905	API_FULFILLMENT	REQUEST	Either orderLevelRefundAmount or refundItems must be specified.
34906	API_FULFILLMENT	REQUEST	The amount value must be specified.
34907	API_FULFILLMENT	REQUEST	The amount value must be positive and within two decimals.
34908	API_FULFILLMENT	REQUEST	The amount currency must be specified.
34909	API_FULFILLMENT	REQUEST	The amount currency isn't correct.
34910	API_FULFILLMENT	REQUEST	Either legacyReference or lineItemId must be specified for item level refund.
34911	API_FULFILLMENT	REQUEST	Legacy item id must be specified for item level refund if you use legacyReference.
34912	API_FULFILLMENT	REQUEST	Legacy transaction id must be specified for item level refund if you use legacyReference.
34913	API_FULFILLMENT	REQUEST	Can not find the order.
34914	API_FULFILLMENT	REQUEST	Can't find the item in the order.
34915	API_FULFILLMENT	REQUEST	The refund amount exceeds order amount.
34916	API_FULFILLMENT	BUSINESS	A post-transaction case exists on this order, seller refund can't be triggered.
34917	API_FULFILLMENT	BUSINESS	This order was already refunded.
34918	API_FULFILLMENT	BUSINESS	This is not an eBay managed payments order.
34919	API_FULFILLMENT	REQUEST	Unauthorized access.
34920	API_FULFILLMENT	BUSINESS	It's too late to issue a refund for this order.
34921	API_FULFILLMENT	REQUEST	The comment exceeds the length limit, please make sure it doesn't exceed 1000 characters.
34922	API_FULFILLMENT	REQUEST	Refund can't be issued while previous refund is processing.
34923	API_FULFILLMENT	REQUEST	Refund cannot be issued for this type of order.
34924	API_FULFILLMENT	BUSINESS	The item refund amount exceeds the item remaining amount.
34925	API_FULFILLMENT	BUSINESS	The refund operation could not be completed with any of the payment methods saved to the seller's account.
34926	API_FULFILLMENT	BUSINESS	A suitable payment method could not be found for the refund operation. Please resolve in Seller Hub.
34927	API_FULFILLMENT	BUSINESS	The selected payment method for the refund operation was invalid or declined.
34928	API_FULFILLMENT	BUSINESS	Your refund did not go through because we could not verify your payment option. Please change your payment option and try again.
34929	API_FULFILLMENT	REQUEST	You cannot refund this order yet since the buyer payment has not been processed. Please try again later.
34930	API_FULFILLMENT	REQUEST	Default payment method limit exceeded. Please use a different payment option or try again later.

Warnings

This call has no warnings.

Samples

New to making API calls? Please see Making a Call.

Note: Identifiers, such as order IDs or user IDs, and personal data in these samples might be anonymized or may no longer be active on eBay. If necessary, substitute current, relevant eBay data in your requests.

Sample 1: Order-Level Refund

Sample 2: Single Line Item-Level Refund Using lineItemId

Sample 3: Single Line Item-Level Refund Using legacyReference

Sample 1: Order-Level Refund

Seller issues order-level refund

Input

Seller issues an order-level refund to the buyer after the buyer requests cancellation of the order. The refund amount is $1.00.

POSThttps://api.ebay.com/sell/fulfillment/v1/order/2********2/issue_refund

Output

The response is successful and a unique identifier of the refund is returned. All successfully-initiated refunds through the issueRefund call will produce a refundStatus value of PENDING. Sellers can then use a getOrder call to track the progress of the refund.

Sample 2: Single Line Item-Level Refund Using lineItemId

Seller issues line item-level refund using lineItemId field

Input

Seller issues an line item-level refund to the buyer after the buyer requests cancellation of one line item in the order. The seller uses the lineItemId field to identify the line item that will be refunded. The refund amount is $1.00.

POSThttps://api.ebay.com/sell/fulfillment/v1/order/2********7/issue_refund

Output

Sample 3: Single Line Item-Level Refund Using legacyReference

Seller issues line item-level refund using legacyReference container

Input

Seller issues an line item-level refund to the buyer after the buyer requests cancellation of one line item in the order. The seller uses the legacyReference container to identify the line item that will be refunded. The refund amount is $1.00.

POSThttps://api.ebay.com/sell/fulfillment/v1/order/1********/issue_refund