Issue Refund

Production

https://api.ebay.com{basePath}

POST

/order/{order_id}/issue_refund

This method allows a seller (opted in to eBay Managed Payments) 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. Note: eBay Managed Payments is currently only available to a limited number of US sellers, but this program is scheduled to become available to more sellers throughout 2019 and beyond.

Request Example

Shell

JavaScript

Java

Swift

curl --location -g --request POST 'https://api.ebay.com{basePath}/order//issue_refund' \
--header 'Content-Type: application/json' \
--data-raw '{
    "comment": "string",
    "orderLevelRefundAmount": {
        "currency": "string",
        "value": "string"
    },
    "reasonForRefund": "string",
    "refundItems": [
        {
            "legacyReference": {
                "legacyItemId": "string",
                "legacyTransactionId": "string"
            },
            "lineItemId": "string",
            "refundAmount": {
                "currency": "string",
                "value": "string"
            }
        }
    ]
}'

Response Example

200 - Example 1

{
    "refundId": "string",
    "refundStatus": "string"
}

Request

Path Params

order_id

string

required

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.

Body Params application/json

The base type used by the request payload of the issueRefund method.

comment

string

optional

This free-text field allows the seller to clarify why the refund is being issued to the buyer. Max Length: 100

orderLevelRefundAmount

object (SimpleAmount)

optional

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.

currency

string

optional

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 always returned with the amount container. For implementation help, refer to eBay API documentation

value

string

optional

The monetary amount of the payment dispute. Both the value and currency fields are always returned with the amount container.

reasonForRefund

string

optional

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. For implementation help, refer to eBay API documentation

refundItems

array[object (RefundItem) {3}]

optional

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.

legacyReference

object (LegacyReference)

optional

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: The lineItemId field is used to identify an order line item in REST API format, and the legacyReference container is used to identify an order line item in Trading/legacy API format. Both legacy and REST API identifiers are returned in getOrder (Fulfillment API) and GetOrders (Trading API).

lineItemId

string

optional

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. Note: The lineItemId field is used to identify an order line item in REST API format, and the legacyReference container is used to identify an order line item in Trading/legacy API format. Both legacy and REST API identifiers are returned in getOrder (Fulfillment API) and GetOrders (Trading API).

refundAmount

object (SimpleAmount)

optional

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.

Examples

Responses

🟢200OK

application/json

Body

This is the base type of the issueRefund response payload. As long as the issueRefund method does not trigger an error, a response payload will be returned.

refundId

string

optional

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.

refundStatus

string

optional

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. For implementation help, refer to eBay API documentation

🟠400Bad Request

🟠403Access Forbidden

🟠404Resource Not found

🟠409Conflict

🔴500Internal Server Error

Modified at 2022-09-11 20:21:04

/order/{orderId}

/order/{orderId}/shipping_fulfillment