The Post-Order API includes interfaces that sellers can use to handle the items that are returned by buyers. While most of the flows described in this document can be achieved using flows on the eBay website, this document describes how sellers can programmatically address buyer returns.

The eBay Returns platform gives buyers a simplified flow to initiate a return request. It also gives sellers the ability to automate the return process as much or as little as they need.

The Post-Order API contains both buyer-facing and seller-facing interfaces. Normally, you will implement only the seller-facing interfaces in your applications; real-life buyers use the eBay web flows to initiate cancellations, returns, inquiries, and escalations. The buyer-facing interfaces are included to facilitate application testing. By implementing the buyer-facing calls, you can programmatically force buyer-initiated conditions so you can test all the seller flows implemented in your application.

Buyer remorse returns vs. SNAD returns

When a buyer initiates a return request, they must supply a return reason with the request. A buyer can return an item for a wide variety of reasons, but these reasons are basically categorized as either "buyer remorse" or "Significantly Not As Described" (SNAD) returns. The following sections outline the return reasons available to buyers:

Buyer remorse return reasons

  • Doesn't fit (usually pertains to clothing items)
  • Changed mind
  • Found a better price
  • Just didn't like it
  • Ordered by mistake

For each of these return reasons, the item's return policy indicates who is responsible for paying the return shipping cost.

SNAD-related return reasons

  • Doesn't work or defective
  • Doesn't match description or photos
  • Wrong item sent
  • Missing parts or accessories
  • Arrived damaged
  • Doesn't seem authentic

To promote buyer satisfaction, the seller is always responsible for paying the return shipping cost for all SNAD-related returns, regardless of what is stated in the item's return policy.

Retrieving buyer-initiated returns

Each return starts with the buyer when, after receiving an item, they go to the eBay website and initiate a return request. So that they can respond in a timely manner, sellers must monitor their listings so they can retrieve any incoming return requests.

Submitting a return request

When a buyer issues a return request, they must state the reason why they want to return the item. If the seller approves the return, the buyer will receive a full refund consisting of the item price and shipping cost, although sellers in the US marketplace can also offer to replace the item.

Although most buyers initiate return requests through My eBay, you can implement buyer-facing calls that allows buyers to (1) verify their item is eligible for a return and (2) initiate the return:

  • A buyer can check an item's return eligibility with a call to POST /return/check_eligibility.

    In this call, the buyer identifies the order line item with the itemId and transactionId fields, sets the checkTypes enumeration value to RETURN_CREATION, and states a return reason. A value of SUCCESS is returned in the eligibilityStatus field in the response.

  • A buyer can initiate a return with a call to POST /return. Here, the buyer specifies if they want their money back, or if they instead want a replacement item:
    • To request a full refund in the POST /return call, the buyer identifies the order line item with the itemId and transactionId fields, sets the type enumeration value to MONEY_BACK, and states a reason for requesting a refund.
    • To request an item replacement in the POST /return call, the buyer identifies the order line item with the itemId and transactionId fields, sets the type enumeration value to REPLACEMENT, and states the reason for requesting a replacement item.

Retrieving return requests

Sellers can retrieve newly-created return requests using GET /return/search, as follows:

  • Call GET /return/search and set the query parameter return_state to RETURN_STARTED.
  • Call GET /return/search and set the query parameters to retrieve orders according to start and end dates.

Ensure you don't re-process a return request by checking that return.Status is set to RETURN_REQUESTED. Capture the returnId of the returns you want to process.

We recommend that sellers use the Post-Order API Return calls to programmatically manage buyer-initiated returns, including using the GET /return/search call to discover pending return requests. Although you can also use a GetOrders call (from the Trading API) to see if a return request has been initiated (the Transaction.Status.ReturnStatus field returns with a value of ReturnRequestPendingApproval), the response does not contain a return ID, or other information you need to process the return.

When you discover that a buyer has requested a return via a call to GET /return/search, the response from the GET call includes the following important information about the return request:

  • The return ID (summary.returnId)
  • The item(s) being returned (summary.creationInfo.item)
  • The reason for the return request (summary.creationInfo.reason)
  • The type of the return requested, either a full or partial amount (summary.creationInfo.type)
  • Whether or not an eBay label is available for the return shipping (detail.replacementShipmentInfo.shipmentTracking.labelAvailableUntilDate)

Note that a seller's return policy indicates who is responsible for the return shipping, either the buyer or the seller. However, be aware that if the buyer is requesting a return because of a SNAD-related reason, the seller is always responsible for the return shipping costs.

Processing return requests

When a seller gets a buyer-initiated return request, they can handle the request in any one of the following ways:

  1. Buyer requests a full refund - The seller approves the request for a full refund, with or without the item being returned.
  2. Buyer requests a replacement item - The seller approves the request for a replacement item, with or without the original item being returned.
  3. Negotiating a partial refund - The seller and buyer negotiate a partial refund amount, without an item return.
  4. Message the buyer - The seller sends a message to the buyer to clarify why the buyer wants to return the item.
  5. Declining a return request - The seller declines the return request.

The following sections describe, from start to finish, how sellers can handle these different return scenarios:

Buyer requests a full refund

When a buyer requests a full refund, the first thing the seller must do is decide whether or not they want the item returned.

If for any reason the seller does not want the item back (but they still want to honor the return request), then all the seller needs to do is (1) approve the return request and (2) issue a full refund. After these two steps, the return request closes.

However, if the seller wants the item back, then the return goes through the following six steps:

  1. The buyer initiates a return request for a full refund.
  2. The seller approves the return.
  3. The buyer gets a shipping label.
  4. The buyer ships the return.
  5. The seller receives the returned item.
  6. The seller provides a full refund.

While the steps are the same for all cases where the seller wants the item back, there are several different flows for shipping the item, depending on whether or not an eBay label is available to the buyer. The following figure outlines the different possible process flows:

Returning an item for a full refund
 Processes flows for returning an item for a full refund

Returning the item and processing the return

There are several options for how the return shipping cost is paid. Configure how the return shipping is paid for, then set up the process for handling returned items using the following flows:

  1. Returning the item
    The buyer gets a valid shipping label via one of the following processes:
  2. Process the return after the buyer ships it.
    The seller processes all items returned by buyers with the same API flow, no matter how buyers ship the items being returned.

The seller pays for return shipping with an eBay label

Sellers who list on the US and Great Britain marketplaces (EBAY_US and EBAY_GB) can sign up to have eBay provide a return shipping label to the buyer, with the eBay-optimized shipping rates charged back to the seller's account.

eBay labels are currently available only for items purchased on the US and Great Britain marketplaces (EBAY_US and EBAY_GB). If the item transaction occurred on another eBay marketplace, then you must use the non-eBay label flows.

The eBay Australian (EBAY_AU) and German (EBAY_DE) sites are exceptions in that eBay labels are available to the buyer via a My eBay self-service interface on the site (as long as the item was purchased on that site). There are no other options available for generating shipping labels for items purchased on these sites.

If a seller opts-in to automated returns, eBay creates a return-shipping label and sends it to the buyer. The accounting for the label generation is tied to the seller's eBay account.

By setting up seller return-automation rules, returns can be automated so that the labels are generated upon an automated-return approval rule that triggers when a buyer requests a return. Configure seller automation rules in the seller Web flow, or by using the supporting Post-Order API methods.

Returning an item for a full refund using an eBay label
 Processes flow for returning an item using an eBay label

Using RMA numbers with eBay labels

If a seller utilizes RMA numbers in their return processing, they can opt-in to the RMA number program to have eBay print the seller's RMA number on the eBay-provided shipping label. In My eBay, opt-in to RMA number via the Account settings > Site preferences > Return preferences dialog.

When you enroll in the RMA number program, eBay generates a return shipping label for the buyer only after you supply an RMA number with a call to POST /return/{returnId}/decide. Note, however, that the authorization process you implement can delay the time between when the buyer requests a return and the time when you accept the return with your RMA number, and this can affect your ability to provide shipping labels to buyers in real time.

To minimize any delay in processing, we recommend you supply the RMA number in the same POST /decide request that you use to ACCEPT a return, and that you automate the generation of your RMA numbers so you can ACCEPT returns as soon as they are requested.

If you use automation rules to programmatically handle returns, you can insure you're providing real-time shipping labels to your buyers by opting-out of the RMA numbers program. If you are opted-out of the program, you can configure your processing so that there is no delay between the time when the buyer requests a return and when you accept the return, and the buyer can retrieve their return shipping label in the same session in which they request the return.

How to use eBay-generated labels

To process returns using eBay-provided labels:

  1. Check on the availability of the eBay shipping label. (optional)

    Call GET /return/{returnId} to get details about the return. The details.returnShipmentInfo.shipmentTracking.labelAvailableUntilDate indicates whether or not an eBay label is available and for how long it is valid.

    You can also call GET /return/{returnId}/get_shipping_label to get information on an existing shipping label.

  2. The seller approves the return and (optionally) sets the RMA number.

    Call POST /return/{returnId}/decide and both approve the return and set the RMA number as follows:

    • Set decision to APPROVE.
    • If the seller is enrolled in the RMA number program, set RMANumber to the seller-generated RMA number.

      Do not set RMA number to null ("") if you want eBay to generate a shipping label. When opted-in to the RMA numbers program, setting this field to null indicates that you're using seller-supplied return shipping labels, and eBay will not generate a label.

    When the seller is enrolled in automated returns, this call causes eBay to generate a shipping label and supply it to the buyer via My eBay.

Once buyer ships the returned item and the seller receives the item, process the return as detailed below in Processing the return.

The seller pays for return shipping with their own label

Sellers can provide their own return-shipping labels to buyers in two ways:

  • Upload a seller-created label to eBay. (recommended)
  • Send a version of the shipping label directly to the buyer.

If a seller (or buyer) provides their own return shipping labels, they must opt-in to the RMA number program so that eBay can process the return through its flows. Once opted-in to the program, you must set the RMANumber field to null ("") when calling POST /return/{returnId}/decide to approve a return, and in this way eBay can move the return to the next state.

In My eBay, opt-in to the RMA number program via the Account settings > Site preferences > Return preferences dialog.

The following diagram shows how to process a return when the seller provides their own return-shipping label to the buyer by uploading the label to eBay:

Returning an item for a full refund using an eBay label
 Processes flow for returning an item using a seller's label

Uploading a seller-created shipping label to eBay

Supported on all eBay marketplaces, uploading an image of your shipping label to eBay is the recommended way to provide seller-generated labels to buyers.

Upload the shipping label, with the configured shipping carrier and tracking information, as follows:

  1. The seller approves the return and sets the RMA number.

    Call POST /return/{returnId}/decide and set the following fields:

    • Set decision to APPROVE.
    • Set RMANumber to null ("").

      Even if the seller uses RMA numbers, it is important that they set this field to null.
      If appropriate, sellers should print the RMA number on the shipping labels they provide.

  2. Upload the shipping label image file.

    Configure a call to POST /return/{returnId}/file_upload as follows:

    • In the data container, provide the base64-encoded binary representation of the shipping label.
    • Set filename to a user-defined string value. (optional)
    • Set filePurpose to LABEL_RELATED.
  3. Add the label specifics.

    Call POST /return/{returnId}/add_shipping_label with the following settings:

    • Set fieldId to the ID value returned by the call to fileUplaod (made in the step above).
    • Set labelAction to UPLOAD_LABEL.
    • Set carrierEnum to a value provided in the ShippingCarrierEnum list.
    • Set trackingNumber to the value provided by your shipping carrier.
    • Use the comments container to provide return instruction for buyers. Set comments.content to a string that is displayed on the Return Details page when the buyer visits the page to print their shipping label.

    When the seller is enrolled in automated returns, this call causes eBay to supply the seller's shipping label to the buyer via My eBay.

Once buyer ships the returned item and the seller receives the item, process the return as detailed below in Processing the return.

Sending a shipping label to the buyer

There are different ways a seller can provide their own return-shipping label to the buyer, such as emailing a graphic that the buyer prints or including a printed version the label in the original item packaging.

If sellers provide their own shipping labels, the API flow can be streamlined to only (1) approving the buyers return request, (2) add label information so the return can be tracked, and (3) issuing a full refund for the item when they receive it back from the buyer.

Use this API process if you directly supply a seller-generated shipping label to the buyer:

  1. The seller approves the return and sets the RMA number.

    Call POST /return/{returnId}/decide and set the following fields:

    • Set decision to APPROVE.
    • Set RMANumber to null ("").

      Even if the seller uses RMA numbers, it is important the seller be opted-in to the RMA number program and that they set this field to null.
      If appropriate, sellers should print the RMA number on the shipping labels they provide to their buyers.
  2. Add the label specifics.

    Call POST /return/{returnId}/add_shipping_label with the following settings:

    • Set labelSentDate value to a timestamp that matches time when the label was sent to the buyer.
    • Set labelAction to MARK_AS_SENT.
    • Set forwardShippingLabelProvided to true.
    • Set carrierEnum to a value provided in the ShippingCarrierEnum list.
    • Set trackingNumber to the value provided by your shipping carrier.
    • Use the comments container to provide return instruction for buyers. Set comments.content to a string that is displayed on the Return Details page when the buyer visits the page to print their shipping label.

Once buyer ships the returned item and the seller receives the item, process the return as detailed below in Processing the return.

The buyer pays for the return shipping

When the buyer pays for the return shipping costs, they do so by providing their own shipping label (the buyer does not reimburse the seller for a seller-provided label).

Important! When the buyer pays for return shipping, the seller must opt-in to the RMA number program so that eBay can process the return through its flows. Once opted-in to the program, you must set the RMANumber field to null ("") when calling POST /return/{returnId}/decide to approve a return, and in this way eBay can move the return to the next state.

In My eBay, opt-in to the RMA number program via the Account settings > Site preferences > Return preferences dialog.

The following flow shows the process API process when the buyer is responsible for handling the return shipping costs:

Returning an item for a full refund using an eBay label

Processes flow for returning an item using the buyer's label

The return policy associated with the item listing determines who, by default, is responsible for the return shipping cost. However, note that the seller is always responsible for paying the return shipping cost for items being returned for a SNAD reason.

Follow this API process when the buyer pays for their own return shipping costs:

  1. The seller approves the return and sets the RMA number.

    Call POST /return/{returnId}/decide and set the following fields:

    • Set decision to APPROVE.
    • Set RMANumber to null ("").

      Even if the seller uses RMA numbers, it is important the seller be opted-in to the RMA number program and that they set this field to null.
      If appropriate, sellers should print the RMA number on the shipping labels they provide to their buyers.

  2. Add the label specifics (optional).

    Call POST /return/{returnId}/add_shipping_label with the following settings:

    • Set labelAction to NO_LABEL.
    • Set noLabelReason to WORK_WITH_BUYER.

Once buyer ships the returned item and the seller receives the item, process the return as detailed below in Processing the return.

Processing the return

When the seller receives an item returned by the buyer, process the return as follows:

  1. The buyer gets the shipping label and returns the item. (optional)

    You can implement this optional buyer-initiated step to aid in the testing of your item-return process flows.

    Call POST /return/{returnId}/mark_as_shipped call to notify the seller that the returned item has been shipped and it's in transit. The seller can then track the item using the supplied tracking number.

  2. The seller tracks the package. (optional)

    Call GET /return/{returnId}/tracking call to track the return item. Every time the package is scanned by the shipping carrier, the updated location and status information for the package becomes available via the tracking number.

  3. The seller receives the returned item and marks it as received. (optional)

    The seller can call POST /return/{returnId}/mark_as_received to update the return request to let the buyer know they're received the return item.

    If the seller never receives the item back from the buyer, or if the seller has an issue with the returned item (for example, if it's not the same item they originally shipped to the buyer), they can escalate the return request to a return case using the POST /return/{returnId}/escalate call. Return cases can be managed with the Case Management interfaces (see Escalating and resolving a case).

  4. Seller issues a full refund to the buyer.

    Call POST /return/{returnId}/issue_refund to issue a full refund to the buyer for the returned item. The refund request closes when this call successfully completes.

    When calling issue_refund, use a separate itemizedRefundDetail container for each separate cost or fee that is being refunded to the buyer. Include the item price and the original shipping cost.

  5. Mark the refund as being sent. (optional)

    Call POST /return/{returnId}/mark_refund_sent to notify the buyer that their refund is on the way.

Buyer requests a replacement item

In some circumstances, a buyer may receive an item which is defective, missing parts, or otherwise damaged. It could be that the buyer still wants the item, but they just want a "replacement" item that has all of its parts and is in good working order. If this is the case, and the seller's return policy says "Money Back or Replacement", the buyer can create a return request and ask for a replacement item instead of a refund.

Here's the process flow for this use case:

Replacement item flow

Process flow for an item replacement

To handle a request for a replacement item:

  1. The seller approves the replacement request.

    Call POST /return/{returnId}/decide with decision set to APPROVE to approve the replacement request.

    When a buyer requests a replacement item, the return reason is often SNAD-related and the seller is responsible for the return shipping cost.

  2. Seller ships a replacement item.

    After shipping the replacement item, the seller can call POST /return/{returnId}/mark_as_shipped call to provide the buyer with the shipping details (the shipping carrier and tracking number). Every time the package is scanned by the shipping carrier, location and status information for the package becomes available.

  3. If the seller does not want the item back, message the buyer.

    If the seller does not need the original item to be returned (at the seller's expense), call POST /return/{returnId}/send_message to inform the buyer they need not return the original item.

    When the replacement item is received, call POST /return/{returnId}/mark_as_received to indicate the replacement item has been received. In a replacement item situation, this action closes the return request.

  4. If the seller does want the item back, use the shipping flows used for a full refund.

    For details on this flow, see: Returning the item and processing the return

Negotiating a partial refund

In some circumstances, a buyer may receive an item which is quite different than how it is described in the listing, or is defective, missing parts, or otherwise damaged. It could be that the buyer still wants the item, but they are not fully satisfied with the item they have received. The buyer does not specifically request a partial refund, but in some cases, the seller and the buyer can negotiate a partial refund amount. In these cases, the buyer still keeps the item (there is no return scenario).

The process for negotiating a partial refund is as follows:

Offer Partial Refund Flow

Process flow for offering a partial refund

  1. Seller offers a partial refund.

    If part of an order is defective, missing, or in some way not satisfactory, the seller can offer a partial refund of the order amount.

    The seller calls POST /return/{returnId}/decide with the decision field set to OFFER_PARTIAL_REFUND, and the proposed partial refund amount in the partialRefundAmount container of the call.

  2. Buyer accepts the partial refund amount.

    The buyer can accept the partial refund amount through My eBay, or optionally, the buyer can call POST /return/{returnId}/decide and set the decide field to ACCEPT_PARTIAL_REFUND.

    The buyer can decline a partial refund offer through My eBay (or by calling POST /return/{returnId}/decide with decide set to DECLINE_PARTIAL_REFUND).

    If the buyer declines the seller's partial refund offer, the seller should contact the buyer by calling POST /return/{returnId}/send_message) to discover whether the buyer wants a full refund, a replacement item, or a higher partial refund amount.

    If the buyer is unable to come to an agreement with the seller, the buyer can escalate the return request to a return case through My eBay, or by calling POST /return/{returnId}/escalate.

  3. Return request is closed.

    Once the partial refund amount is accepted by the buyer, the return request is closed. eBay issues the partial refund amount to the buyer's account and debits the seller's account. The seller's Final Value Fee on the original purchase is reversed.

Declining a return request

Although it is generally not recommended, a seller has the right to decline a return request if the return period for the item has expired. However, if the buyer's return reason is SNAD-related, the eBay Money Back Guarantee has a 30-day policy that overrides a shorter return period in the listing's return policy. So, if the seller declines the buyer's return request, and the item is being returned for a SNAD-related reason, the buyer often escalates a declined return request, and creates a return case.

The seller can decline a return request by calling POST /return/{returnId}/decide with the decision field set to DECLINE. If the seller declines the buyer's return request, the return request is closed.

The buyer can dispute this action and escalate the return request to a return case by using the POST /return/{returnId}/escalate call. The seller manages cases using the Case Management interfaces (see Escalating and resolving a case).

Configuring return automation rules

If a seller offers returns on some or all of their items, it is a good idea to set up return automation rules to partially or fully automate the return flow. You can configure return automation rules online in the Return Preferences section of a seller's My eBay, and they include basic and advanced rules. The basic and advanced rules are similar; however, the advanced rules can be applied to specific categories and to a specific list of items. Below is a summary of the three main rule types:

  • Approve a return automatically: This advanced automation rule lets sellers customize when they will automatically approve a return based on the buyer's return reason and the item price.

    If a buyer initiates a return, the return is automatically approved if both return reason and item price matches this rule. With advanced return automation rules, the seller also has the option of setting a specific return address. If a return address is not specified, eBay uses the seller's default return address. Additionally, when using advanced rules, the seller can create a list of active items or eBay categories to which the rule applies. Note this feature is not available with the basic return automation rules.

  • Keep item and issue refund: This rule lets sellers specify the items that they do not want returned.

    In a standard return flow, the buyer is expected to return the item to the seller, and the seller issues a refund after receiving the item. However, the seller can create a rule that allows the buyer to keep the item and receive an immediate refund. For example, a seller might create an automatic refund rule for low-value items, where it's not worth the time it takes to process the returned items. A rule like this increases customer satisfaction, where they do not have to worry about returning the item and waiting for a refund. Similar to the Approve a return automatically rule, the keep item/automatic refund rule is based on the purchase price, the return reasons, and, optionally, a list of active items or eBay categories.

  • Keep item and send replacement item: This rule lets sellers specify the items for which they will automatically send a replacement, without a return.

    Some sellers may have enough inventory of an item to give buyers a choice of a refund or a replacement item. In a replacement item flow, the buyer is expected to return the original item to the seller, and the seller sends the replacement item after receiving the return. However, the seller can create a rule that allows the buyer to keep the original item and still receive a replacement item. A seller might want to create a rule like this for low-value items, where it's not worth the time it takes to process the returned item. Setting up an auto-replace rule is also a customer-pleasing action. Similar to the Approve a return automatically rule, the keep item/automatic refund rule is based on the purchase price, the return reasons, and, optionally, a list of active items or eBay categories. Note that in addition to the specifications of the automation rule, the buyer must be seeking a replacement item (instead of a refund) in order for this rule to be applicable. This rule type is not available with the basic return automation rules.

Attaching files to return requests

Buyers can attach image files to a return request. These image files will either be return shipping labels (or related to return shipping) or they may be pictures that illustrate the condition of an item. If the seller is responsible for return shipping, and that seller would prefer to use their own shipping labels instead of an eBay shipping label, that seller would use the POST /return/{returnId}/file/upload call to upload the shipping label. The entire process of providing a return shipping label to the buyer is covered in the Seller-provided shipping labels section. The supported file types are .BMP, .GIF, .JPEG, and .PNG.

To attach a file to a return request:

  1. Add file the return request.

    Call POST /return/{returnId}/file/upload to add a base64-encoded binary representation of an image file to the return request. The filePurpose should be set to ITEM_RELATED for files that demonstrate the condition of the item, or set to LABEL_RELATED for files that are either a shipping label or other document that provided more information about shipment tracking.

  2. Activate the file associated with a return request.

    Call POST /return/{returnId}/file/submit to activate the files you have associated with the return request.

Working with drafts

Buyers can create a return draft before they actually submit the return request to the seller. Creating a draft lets buyers review and prepare the files they want to attach to the return request before they submit it. The following flow shows what a buyer may do before actually submitting the return request:

  1. Create the return draft.

    Call POST /return/draft to create a return draft. This call is very similar to the POST /return call.

  2. Add files to the return draft.

    Call POST /return/draft/{draftId}/file/upload to add image files to the draft. Only one image file can be uploaded per call. Supported file types are .BMP, .GIF, .JPEG, and .PNG.

  3. Manage the files associated with a return draft.

    Use the following operations to inspect the files you're attached to the return draft, and to delete unwanted files:

  4. Revise the data associated with the return draft.

    Call PUT /return/draft/{draftId} to modify any settings/values in the existing return draft. All of the fields of the call request payload you supply will overwrite the settings/values in the existing draft, so be sure to include all the fields you want to include in your return draft.

  5. Convert the return draft into a live return request.

    Once the return draft is set, call POST /return, making sure you supply the correct draftId value in the payload.

Overview of the return calls

The Post-Order API provides the following operations to help you manage the return process:

Post-Order API Return Management Operations

Operation Buyer or Seller-Facing? Use Case(s)
POST /return/check_eligibility Buyer
  1. Buyer checks to see if a return request (money back) can be opened against the order line item
  2. Buyer checks to see if a return request (replacement item) can be opened against the order line item
POST /return Buyer
  1. Creates a new return request
  2. Converts a return draft into a return request
POST /return/estimate Buyer Retrieves the estimated refund amount and return shipping cost associated with an item being returned
POST /return/metadata/{metadataKey} Both Retrieves the valid return reasons that can be used when making a return request
GET /return/search Both Retrieves the details for one or more return requests
GET /return/{returnId} Both
  1. Retrieves detailed information for a specific return request
  2. Retrieves high-level information for a specific return request
POST /post-order/v2/return/{returnId}/decide Both
  1. Seller approves the buyer's return request
  2. Seller declines the buyer's return request
  3. Seller offers the buyer a partial refund and the opportunity to keep the item
  4. Seller provides a Return Merchandise Authorization (RMA) number to the buyer
  5. Buyer accepts the seller's partial refund offer
  6. Buyer declines the seller's partial refund offer
POST /return/{returnId}/cancel Buyer Cancels and closes the return request
POST/return/{returnId}/escalate Both
  1. Escalates a return request into a return case for the buyer
  2. Escalates a return request into a return case for the seller
POST /return/{returnId}/issue_refund Seller Issues a full or partial refund to the buyer.
POST /return/{returnId}/mark_as_shipped Both
  1. Buyer marks a return item as "shipped" and provides shipment tracking information
  2. Seller marks a replacement item as "shipped" and provides shipment tracking information
POST /return/{returnId}/mark_as_received Both
  1. Seller marks a return item as "received"
  2. Buyer marks a replacement item as "received"
POST /return/{returnId}/mark_refund_received Buyer Buyer confirms that a refund was received
POST /return/{returnId}/mark_refund_sent Seller Seller marks the refund as being sent, and optionally, provides details on the refund
POST /return/{returnId}/send_message Both
  1. Buyer sends message to seller regarding the return request
  2. Seller sends message to buyer regarding the return request
GET /return/{returnId}/tracking Both
  1. Seller retrieves the shipment tracking activity log for an item being returned
  2. Buyer retrieves the shipment tracking activity log for a replacement item
POST /post-order/v2/return/{returnId}/file/upload Both
  1. Seller uploads a base64-encoded binary representation of a shipping label
  2. Seller uploads a base64-encoded binary representation of an image file showing the condition of an item
  3. Buyer uploads a base64-encoded binary representation of a shipping label
  4. Buyer uploads a base64-encoded binary representation of an image file showing the condition of an item
POST /return/{returnId}/add_shipping_label Seller
  1. Seller uploads their own shipping label for buyer to use
  2. Seller informs buyer that an eBay shipping label is already available for use
  3. Seller informs buyer that a shipping label has recently been sent to them
  4. Seller instructs buyer to purchase their own shipping label, and then they will reimburse the buyer for the return shipping cost when the refund is issued
  5. Seller informs buyer that the buyer is responsible for shipping
  6. Seller informs buyer that the item is too large to ship using a shipping label
  7. Seller informs international buyer that shipping labels are not available for international shipping
  8. Seller informs buyer that the item should be returned to the store where it was picked up (applicable for In-Store Pickup and Click and Collect orders)
GET /return/{returnId}/check_label_print_eligibility Buyer Checks to see if a valid shipping label is ready to be printed and used for return shipping
GET /return/{returnId}/get_shipping_label Buyer Retrieves details on the shipping label
POST /return/{returnId}/initiate_shipping_label Buyer Initiates the creation of an eBay shipping label; this call must be run before the get_shipping_label and send_shipping_label calls.
POST /return/{returnId}/send_shipping_label Buyer Send an existing shipping label to a specified email address
POST /return/{returnId}/void_shipping_label Seller Voids a seller-generated shipping label
POST /return/{returnId}/file/submit Both
  1. Buyer activates the file that has been associated with the return request
  2. Seller activates the file that has been associated with the return request
DELETE /return/{returnId}/file/{fileId} Both
  1. Buyer deletes a file that has been associated with the return request
  2. Seller deletes the file that has been associated with the return request
GET /return/{returnId}/files Both
  1. Buyer retrieves all files that have been associated with the return request
  2. Seller retrieves all files that have been associated with the return request
POST /return/draft Buyer Buyer creates a return draft that can be converted to an actual return request at a later time
GET /return/draft/{draftId} Buyer Buyer retrieves the details of a specific return draft
PUT /return/draft/{draftId} Buyer Buyer makes modifications to an existing return draft
POST /return/draft/{draftId}/file/upload Buyer Buyer uploads a file to a return draft
DELETE /return/draft/{draftId}/file/{fileId} Buyer Buyer deletes a file that has been associated with the return draft
GET /return/draft/{draftId}/files Buyer Buyer retrieves all files that have been associated with the return draft