Handling Returns

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 new eBay Returns platform gives buyers a simplified web flow to initiate a return request. It also gives sellers the ability to automate the return process as much or as little as they want.

Topics:

 

Important! 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 buyers use the eBay web flows to initiate cancellations, returns, inquiries, and escalations. However, the buyer-facing interfaces are included to facilitate application testing; with the buyer-facing calls, you can programmatically force the buyer-initiated conditions so you can test the seller flows in your apps.

Buyer remorse vs. SNAD-related return reasons

When a buyer initiates a return request, they must supply a return reason. A buyer can return an item for a wide variety of reasons, but these reasons are basically categorized as "buyer remorse" reasons or "Significantly Not As Described" (SNAD) reasons. Note that the seller is responsible for the return shipping cost for all SNAD-related reasons, regardless of what is stated in the item's return policy.

SNAD-related return reasons

For each of these return reasons, the seller is expected to pay for return shipping, regardless of what is stated in the return policy.

Buyer remorse return reasons

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

Setting up 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. Return automation rules are set up 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:

Retrieving returns

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

Initiating a return request

When a buyer issues a return request, they can state various reasons for why they want to return the item, and they can request either a full refund or a replacement item.

While most buyers will initiate a return request 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:

Retrieving return requests

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

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:

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 return request, they can handle the request in any one of the following ways:

  1. The seller approves the request for a full refund, with or without the item being returned. (See: Buyer requests a full refund)
  2. The seller approves the request for a replacement item, with or without the item being returned (see: Buyer requests a replacement item).
  3. The seller negotiates a partial refund, without an item return (see: Negotiating a partial refund).
  4. The seller sends a message to the buyer to clarify the why the buyer wants to return the item (see: Message the buyer).
  5. The seller denies the request (see: Declining a 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

Shipping return items

eBay supports the following ways to ship return items:

In one other scenario, the seller can pay for shipping with a label that they included in their original package. In this case, the seller just approves the return request, then issues the full refund when they receive the item back.

Important! eBay labels are currently available for items purchased on the US and Great Britain sites (EBAY_US and EBAY_GB). If the item transaction occurred on another eBay site, 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.

The seller pays for shipping with an eBay label

This flow is currently available to sellers who list on the US and Great Britain sites (EBAY_US and EBAY_GB). If a seller is opted-in to automated returns, return requests are processed through the seller's return automation rules. (Sellers can configure their automation rules in the seller Web flow.) Upon an automated-return approval, eBay creates a return-shipping label and sends it to the buyer.

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

Here are the detailed steps for using an eBay label:

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

    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. Seller approves the return.

    Call POST /return/{returnId}/decide and set the field decision to APPROVE.

  3. Set the return merchandise authorization (RMA) number.

    After approving the return, set the return merchandise authorization (RMA) number by making a second call to POST /return/{returnId}/decide. Set RMANumber to the seller's RMA number, or null, depending on whether or not the seller uses RMA numbers (eBay requires that the RMA number be set before it can generate a label).

  4. The buyer gets the shipping label and returns the item.

    If an eBay label is available, the label is automatically generated and sent to the buyer when the seller specifies the RMA number.

    The return policy associated with the item listing determines who, by default, is responsible for the return shipping. However, if a refund is being requested for SNAD reasons, then the seller is always responsible for the return shipping cost.

  5. (optional) The seller tracks the package.

    The seller can use the 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.

  6. The seller receives the returned item and (optionally) marks the item as received.

    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 has an issue with the item returned by the buyer (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.

  7. 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, the original shipping cost, and subtract a restocking fee (if one was set for the listing). Note that a seller cannot charge the buyer a restocking fee for items returned with a SNAD-related return reason.

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

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

The seller pays for shipping with their own label

Sellers can generate their own return-shipping lables and provide them to their buyers for cases where a return is requested. Note that sellers must not be opted-in to eBay's automated returns if they want to provide their own shipping labels. Automated returns are available in select marketplaces and if a seller is not opted-in to eBay's auto-return policy, they can provide their own shipping labels for any non-automated returns.

The process for creating a shipping label is show in this diagram:

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

The procedure follows:

  1. The seller approves the return.

    Call POST /return/{returnId}/decide and set the field decision to APPROVE.

  2. Set the return merchandise authorization (RMA) number.

    After approving the return, set the return merchandise authorization (RMA) number by making a second call to POST /return/{returnId}/decide. Set RMANumber to the seller's RMA number, or null, depending on whether or not the seller uses RMA numbers (eBay requires that the RMA number be set before it can update the status of the return).

  3. Create, populate, and upload the shipping label.

    The seller must complete a couple of steps before they can send their shipping label to the buyer:

    1. Upload your shipping label file with a call to POST /return/{returnId}/file_upload. Provide the base64-encoded binary representation of the shipping label in the data container, and a set filePurpose to LABEL_RELATED.
    2. Update the shipping label object with the fileId value returned from the preivious call and upload the label by calling POST /return/{returnId}/add_shipping_label with labelAction set to UPLOAD_LABEL.
  4. Send the shipping label to the buyer.

    Call POST /return/{returnId}/file/upload to send the shipping label to the buyer.

  5. The buyer gets the shipping label and returns the item.

    Although not commonly implemented, the buyer can call POST /return/{returnId}/mark_as_shipped call to provide the seller with the shipping carrier and tracking number.

  6. The seller receives the returned item and (optionally) marks the item as received.

    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 has an issue with the item returned by the buyer (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.

  7. 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, the original shipping cost, and subtract a restocking fee (if one was set for the listing). Note that a seller cannot charge the buyer a restocking fee for items returned with a SNAD-related return reason.

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

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

The buyer pays for shipping

The following flow diagrams the processing when a buyer is responsible for the return shipping costs:

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

Here are the detailed steps:

  1. Seller approves the return.

    Call POST /return/{returnId}/decide and set the field decision to APPROVE.

  2. Set the return merchandise authorization (RMA) number.

    After approving the return, set the return merchandise authorization (RMA) number by making a second call to POST /return/{returnId}/decide. Set RMANumber to the seller's RMA number, or null, depending on whether or not the seller uses RMA numbers (eBay requires that the RMA number be set before it can generate a label).

  3. The buyer returns the item.

    The process here depends on whether or not an eBay label is available:

    • If an eBay label is available, eBay generates and sends the label to the buyer when you set the RMA number.
    • If no eBay label is available, contact the buyer to inform them they need to return the item using the shipping service of their choice. Email the RMA number if applicable.

    If you are implementing buyer-side calls, the buyer could call POST /return/{returnId}/mark_as_shipped to provide the seller with the shipping carrier and tracking number.

  4. The seller receives the returned item and (optionally) marks the item as received.

    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 has an issue with the item returned by the buyer (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.

  5. 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, the original shipping cost, and subtract a restocking fee (if one was set for the listing). Note that a seller cannot charge the buyer a restocking fee for items returned with a SNAD-related return reason.

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

    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 replacment 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.

    As with a full refund, use one of the following flows according to your needs:

  5. If the seller never receives the returned item from the buyer, they can escalate case by calling POST /return/{returnId}/escalate call. Manage return cases with the Case Management interfaces.

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 pratial 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.

    Important! If the buyer decides to decline the partial refund amount, they can do so through My eBay, or by using the POST /return/{returnId}/decide call and setting the decide field to DECLINE_PARTIAL_REFUND. Once the buyer declines the seller's partial refund offer, the seller should contact the buyer with POST /return/{returnId}/send_message) to discover what the buyer is seeking, whether that be a full refund, a replacement item, or a higher partial refund amount. If the buyer is not able to come to an agreement with the seller in regards to resolving the issue, the buyer can escalate the return request to a return case through My eBay or through the POST /return/{returnId}/escalate call.

  3. Return request is closed.

    Once the 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.

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 creating 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 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 1. Retrieves the estimated refund amount and return shipping cost associated with an item being returned
POST /return/metadata/{metadataKey} Both 1. Retrieves the valid return reasons that can be used when making a return request
GET /return/search Both 1. 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 1. 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 1. 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 1. Buyer confirms that a refund was received
POST /return/{returnId}/mark_refund_sent Seller 1. 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 1. 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 1. Retrieves details on the shipping label
POST /return/{returnId}/initiate_shipping_label Buyer 1. 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 1. Send an existing shipping label to a specified email address
POST /return/{returnId}/void_shipping_label Seller 1. 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 1. Buyer creates a return draft that can be converted to an actual return request at a later time
GET /return/draft/{draftId} Buyer 1. Buyer retrieves the details of a specific return draft
PUT /return/draft/{draftId} Buyer 1. Buyer makes modifications to an existing return draft
POST /return/draft/{draftId}/file/upload Buyer 1. Buyer uploads a file to a return draft
DELETE /return/draft/{draftId}/file/{fileId} Buyer 1. Buyer deletes a file that has been associated with the return draft
GET /return/draft/{draftId}/files Buyer 1. Buyer retrieves all files that have been associated with the return draft

 

Copyright © 2005–2016 eBay Inc. All rights reserved. This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.