POST/order/{order_id}/issue_refund
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 (production)
URI parameters
| Parameter | Type | Description |
|---|---|---|
| order_id | string | The unique identifier of the order. Order IDs are returned in the getOrders method (and GetOrders call of Trading API). The issueRefund method supports the legacy API Order IDs and REST API order IDs. Note: In the Trading API (and other legacy APIs), Order IDs are transitioning to a new format. The new format is a non-parsable string, globally unique across all eBay marketplaces, and consistent for both single line item and multiple line item orders. These order identifiers will be automatically generated after buyer payment, and unlike in the past, instead of just being known and exposed to the seller, these unique order identifiers will also be known and used/referenced by the buyer and eBay customer support. For developers and sellers who are already integrated with the Trading API's order management calls, this change shouldn't impact your integration unless you parse the existing order identifiers (e.g., OrderID or OrderLineItemID), or otherwise infer meaning from the format (e.g., differentiating between a single line item order versus a multiple line item order). Because we realize that some integrations may have logic that is dependent upon the identifier format, eBay is rolling out the Trading API change with version control to support a transition period of approximately 9 months before applications must switch to the new format completely. See the OrderID field description in the GetOrders call for more details and requirements on transitioning to the new Order ID format. Occurrence: Required |
HTTP request headers
All requests made to eBay REST operations require you to provide the Authorization HTTP header for authentication authorization.
In addition, this method requires you to include the Content-Type header and its value should be set to "application/json". See HTTP request headers- opens rest request components page for details.
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 clipboardRequest 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. Occurrence: Required |
| comment | string | This free-text field allows the seller to clarify why the refund is being issued to the buyer. 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 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. 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. Occurrence: Conditional |
| refundItems.legacyReference.legacyItemId | string | The unique identifier of a listing in legacy/Trading API format. 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. 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 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
Response fields
| 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 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 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
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
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 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
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.