getReturnDetail

This call retrieves detailed information on one eBay-Managed return.

Request Details

To retrieve a specific return, the caller passes a return ID into the ReturnId.id field. The Return ID value can be obtained with the getUserReturns call.

Working with the Response

A ReturnSummary and a ReturnDetail container is returned if a return matches the return ID passed in the request.

The ReturnSummary container consists of the following information:

• creationDate: timestamp indicating when the return was opened by the buyer.
• lastModifiedDate: timestamp indicating the last time the buyer, seller, or eBay initiated an action on the return.
• ReturnId.id: the unique identifier of the return. This value will be used in other Return Management API calls to provide an Return Merchandise Authorization number, to issue a refund, to provide an alternative return shipping address, to provide shipment tracking information, to set a replacement item as received, or to get the next possible action to take on the return.
• status: this field contains an enumeration value that indicates the current status of the return.
• otherParty: this container identifies the eBay user on the other side of the return.
• returnRequest: this container consists of details related to the item being returned, including the buyer's reason for returning the item.
• responseDue: this container is returned if the buyer or seller has a pending response due in the return. The current status of the return dictates the type or response that is due.

The ReturnDetail container consists of the following information:

• refundInfo.estimatedRefundDetail: the data in this container will reflect the buyer's costs in the original transaction, including the purchase price and shipping costs.
• refundInfo.actualRefundDetail: the data in this container will reflect the actual refund transaction issued from the seller to the buyer during the return flow. An itemizedRefund container is required for each refund type, such as purchase price, original shipping, return shipping, and restocking fee. The total refund amount is indicated in the actualRefund.totalAmount field.
• refundInfo.refundDue: the date on which the buyer's refund is due from the seller.
• returnHistory: a returnHistory node is returned for each activity logged in the return. Each node includes the date, description, and author (actor) of each activity.
• globalId: string value that indicates the site ID where the order occurred.
• shipmentInfo: this container consists of detailed information on a package shipment, whether that shipment is the buyer returning an item, or the seller is providing the buyer with a replacement item. This container includes the shipping address of the package's destination, the shipping carrier used, the shipping costs, the estimated delivery date range, and the status of the shipment. If provided/available, the tracking number and Return Merchandise Authorization number may also appear in this container.
• caseId: this container will appear in the response if there is an eBay Buyer Protection case filed against the item.

Input

See also Samples.

The box below lists all fields that could be included in the call request. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are (or soon will be) non-operational.

<?xml version="1.0" encoding="utf-8"?>
<getReturnDetailRequest xmlns="http://www.ebay.com/marketplace/returns/v1/services">
  <!-- Call-specific Input Fields -->
  <ReturnId> ReturnIdType
    <id> string </id>
  </ReturnId>
</getReturnDetailRequest>

Output

See also Samples.

The box below lists all fields that might be returned in the response. To learn more about an individual field or its type, click its name in the box (or scroll down to find it in the table below the box).

See also the Deprecated Objects link above. Fields presented in this color are deprecated, and fields presented in this color are not returned (or soon will not be returned) or are not operational (or soon will be non-operational).

<?xml version="1.0" encoding="utf-8"?>
<getReturnDetailResponse xmlns="http://www.ebay.com/marketplace/returns/v1/services">
  <!-- Call-specific Output Fields -->
  <ReturnDetail> ReturnDetailType
    <buyerReturnShipment> ShipmentType
      <carrierUsed> string </carrierUsed>
      <deliveryDate> dateTime </deliveryDate>
      <maxEstDeliveryDate> dateTime </maxEstDeliveryDate>
      <minEstDeliveryDate> dateTime </minEstDeliveryDate>
      <returnMerchandiseAuthorization> string </returnMerchandiseAuthorization>
      <shipmentStatus> ShipmentStatusType </shipmentStatus>
      <shippingAddress> Address
        <city> string </city>
        <country> string </country>
        <county> string </county>
        <name> string </name>
        <postalCode> string </postalCode>
        <stateOrProvince> string </stateOrProvince>
        <street1> string </street1>
        <street2> string </street2>
      </shippingAddress>
      <shippingCost> Amount (double) </shippingCost>
      <trackingNumber> string </trackingNumber>
    </buyerReturnShipment>
    <caseId> CaseIdType
      <id> string </id>
      <type> CaseType </type>
    </caseId>
    <globalId> token </globalId>
    <refundInfo> RefundInfoType
      <actualRefundDetail> ActualRefundDetailType
        <actualRefund> RefundDetailType
          <itemizedRefund> ItemizedRefundDetailType
            <amount> Amount (double) </amount>
            <refundFeeType> RefundFeeType </refundFeeType>
          </itemizedRefund>
          <!-- ... more itemizedRefund nodes allowed here ... -->
          <totalAmount> Amount (double) </totalAmount>
        </actualRefund>
        <refundDate> dateTime </refundDate>
        <refundStatus> RefundStatusType </refundStatus>
      </actualRefundDetail>
      <estimatedRefundDetail> EstimatedRefundDetailType
        <estimatedRefund> RefundDetailType
          <itemizedRefund> ItemizedRefundDetailType
            <amount> Amount (double) </amount>
            <refundFeeType> RefundFeeType </refundFeeType>
          </itemizedRefund>
          <!-- ... more itemizedRefund nodes allowed here ... -->
          <totalAmount> Amount (double) </totalAmount>
        </estimatedRefund>
        <itemizedOptionalRefund> ItemizedRefundDetailType
          <amount> Amount (double) </amount>
          <refundFeeType> RefundFeeType </refundFeeType>
        </itemizedOptionalRefund>
        <!-- ... more itemizedOptionalRefund nodes allowed here ... -->
      </estimatedRefundDetail>
      <refundDue> dateTime </refundDue>
    </refundInfo>
    <returnHistory> ReturnResponseHistoryType
      <activityDetail> ActivityDetailType (EnumerationDetailType)
        <code> token </code>
        <content> token </content>
        <description> token </description>
      </activityDetail>
      <author> ReturnUserType
        <role> ReturnUserRoleType </role>
        <userId> string </userId>
      </author>
      <creationDate> dateTime </creationDate>
      <note> string </note>
    </returnHistory>
    <!-- ... more returnHistory nodes allowed here ... -->
    <returnPolicy> ReturnPolicyInfoType
      <optedForMultipleReturnAddress> boolean </optedForMultipleReturnAddress>
      <optedForRMA> boolean </optedForRMA>
    </returnPolicy>
    <shipmentInfo> ShipmentType
      <carrierUsed> string </carrierUsed>
      <deliveryDate> dateTime </deliveryDate>
      <maxEstDeliveryDate> dateTime </maxEstDeliveryDate>
      <minEstDeliveryDate> dateTime </minEstDeliveryDate>
      <returnMerchandiseAuthorization> string </returnMerchandiseAuthorization>
      <shipmentStatus> ShipmentStatusType </shipmentStatus>
      <shippingAddress> Address
        <city> string </city>
        <country> string </country>
        <county> string </county>
        <name> string </name>
        <postalCode> string </postalCode>
        <stateOrProvince> string </stateOrProvince>
        <street1> string </street1>
        <street2> string </street2>
      </shippingAddress>
      <shippingCost> Amount (double) </shippingCost>
      <trackingNumber> string </trackingNumber>
    </shipmentInfo>
    <!-- ... more shipmentInfo nodes allowed here ... -->
  </ReturnDetail>
  <ReturnSummary> ReturnSummaryType
    <creationDate> dateTime </creationDate>
    <lastModifiedDate> dateTime </lastModifiedDate>
    <otherParty> ReturnUserType
      <role> ReturnUserRoleType </role>
      <userId> string </userId>
    </otherParty>
    <responseDue> ReturnResponseDueType
      <party> ReturnUserType
        <role> ReturnUserRoleType </role>
        <userId> string </userId>
      </party>
      <respondByDate> dateTime </respondByDate>
    </responseDue>
    <ReturnId> ReturnIdType
      <id> string </id>
    </ReturnId>
    <returnRequest> ReturnRequestType
      <comments> string </comments>
      <returnItem> ReturnItemType
        <itemId> string </itemId>
        <returnQuantity> int </returnQuantity>
        <transactionId> string </transactionId>
      </returnItem>
      <!-- ... more returnItem nodes allowed here ... -->
      <returnReason> ReturnReasonType (EnumerationDetailType)
        <code> token </code>
        <content> token </content>
        <description> token </description>
      </returnReason>
    </returnRequest>
    <ReturnType> ReturnType </ReturnType>
    <status> ReturnStatusType </status>
  </ReturnSummary>
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage
    <error> ErrorData
      <category> ErrorCategory </category>
      <domain> string </domain>
      <errorId> long </errorId>
      <exceptionId> token </exceptionId>
      <message> string </message>
      <parameter name="string"> ErrorParameter (string) </parameter>
      <!-- ... more parameter values allowed here ... -->
      <severity> ErrorSeverity </severity>
      <subdomain> string </subdomain>
    </error>
    <!-- ... more error nodes allowed here ... -->
  </errorMessage>
  <timestamp> dateTime </timestamp>
  <version> string </version>
</getReturnDetailResponse>

Samples

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

Note: Some item IDs, user IDs, or other data in these samples might no longer be active on eBay. If necessary, you can substitute current eBay data in your requests.

This call retrieves detailed information on one eBay return.

Description

This getReturnDetail call sample retrieves detailed return information for an eBay return identified as return 5********8.

This call will fail if an invalid return ID is passed in. The caller must be authenticated to make this call.

This call returns a ReturnSummary container, which consists of data such as the following:

• the role and user ID of the calling party
• the role and user ID of the other party in the return
• the return ID
• the return creation and 'last modified" dates
• the current status of the return
• information on the item being returned

This call returns a ReturnDetail container, which consists of data such as the following:

• estimated refund amount (based on the total of purchase price and shipping costs)
• actual refund amount (if the seller has already issue a refund to the buyer)
• refund due date
• global ID of the eBay site
• return shipping details, including the seller's return shipping address, the shippier carrier being used, shipping costs, etc.
• an activity log for each action in the return
• eBay Buyer Protection case ID (if applicable)

Input

A seller, identified as u********a, uses the getReturnDetail call to retrieve detailed return information for an eBay return identified as return 5********8.

SOAP format. Also available is the XML equivalent.

<soap:Envelope xmlns:soap="http://www.w3.org/2003/05/soap-envelope" xmlns:ser="http://www.ebay.com/marketplace/returns/v1/services">
   <soap:Header/>
   <soap:Body>
      <ser:getReturnDetailRequest>
         <ser:RequesterCredentials>
             <ser:eBayAuthToken>A********3</ser:eBayAuthToken>
          </ser:RequesterCredentials>
         <ser:ReturnId>
            <ser:id>5********8</ser:id>
         </ser:ReturnId>
      </ser:getReturnDetailRequest>
   </soap:Body>
</soap:Envelope>

Output

By looking at the ReturnSummary container in the response, we know the following:

• The buyer who started the return (identified in the otherParty.role field) is identified as u********r.
• The buyer's reason for returning the item (identified in the returnRequest.returnReason.description field) is 'CHANGED_MY_MIND', also known as buyer remorse.
• The buyer's response is due on the return. To discover the type of response that is due, the seller would need to perform a getActivitiyOptions call, passing in '5********8' as the return ID.

By looking at the ReturnDetail container, we know the following:

• The order occurred on the U.S. site (site ID 0)
• The buyer created the return on 12-05-2012.
• By looking at the refundInfo.estimatedRefundDetail container, we know that the total estimated refund amount is $1.01 USD, and that this covers what the buyer paid for the item. The seller also has the option of refunding the buyer's original shipping costs, which was $5.00 USD.

SOAP format. Also available is the XML equivalent.

<soapenv:Envelope xmlns:soapenv="http://www.w3.org/2003/05/soap-envelope">
   <soapenv:Header/>
   <soapenv:Body>
      <ns1:getReturnDetailResponse xmlns:ns1="http://www.ebay.com/marketplace/returns/v1/services">
         <ns1:ack>Success</ns1:ack>
         <ns1:version>1.0.0</ns1:version>
         <ns1:timestamp>2012-01-13T18:19:34.707Z</ns1:timestamp>
         <ns1:ReturnSummary>
            <ns1:ReturnId>
               <ns1:id>5********8</ns1:id>
            </ns1:ReturnId>
            <ns1:otherParty>
               <ns1:userId>u********r</ns1:userId>
               <ns1:role>BUYER</ns1:role>
            </ns1:otherParty>
            <ns1:returnRequest>
               <ns1:returnItem>
                  <ns1:itemId>1**********0</ns1:itemId>
                  <ns1:transactionId>2*********1</ns1:transactionId>
                  <ns1:returnQuantity>1</ns1:returnQuantity>
                </ns1:returnItem>
               <ns1:returnReason>
                  <ns1:code>2</ns1:code>
                  <ns1:description>ORDERED_ACCIDENTALLY</ns1:description>
               </ns1:returnReason>
               <comments>test</comments>
            </ns1:returnRequest>
            <ns1:status>WAITING_FOR_SELLER_INFO</ns1:status>
            <ns1:responseDue>
               <ns1:party>
                  <ns1:userId>u********a</ns1:userId>
                  <ns1:role>SELLER</ns1:role>
               </ns1:party>
               <ns1:respondByDate>2011-12-06T23:59:08.000Z</ns1:respondByDate>
            </ns1:responseDue>
            <ns1:creationDate>2011-12-05T16:36:10.000Z</ns1:creationDate>
         </ns1:ReturnSummary>
         <ns1:ReturnDetail>
            <ns1:globalId>EBAY-US</ns1:globalId>
            <ns1:returnHistory>
               <note>test</note>
               <ns1:author>
                  <ns1:userId>0</ns1:userId>
                  <ns1:role>BUYER</ns1:role>
               </ns1:author>
               <ns1:activityDetail>
                  <ns1:code>1</ns1:code>
                  <ns1:description>buyerCreateReturn</ns1:description>
               </ns1:activityDetail>
               <ns1:creationDate>2011-12-05T16:36:10.000Z</ns1:creationDate>
            </ns1:returnHistory>
            <ns1:refundInfo>
               <ns1:estimatedRefundDetail>
                  <ns1:estimatedRefund>
                     <ns1:totalAmount currencyId="USD">1.01</ns1:totalAmount>
                     <ns1:itemizedRefund>
                        <ns1:refundFeeType>PURCHASE_PRICE</ns1:refundFeeType>
                        <ns1:amount currencyId="USD">1.01</ns1:amount>
                     </ns1:itemizedRefund>
                  </ns1:estimatedRefund>
                  <ns1:itemizedOptionalRefund>
                     <ns1:refundFeeType>ORIGINAL_SHIPPING</ns1:refundFeeType>
                     <ns1:amount currencyId="USD">5.0</ns1:amount>
                  </ns1:itemizedOptionalRefund>
               </ns1:estimatedRefundDetail>
            </ns1:refundInfo>
            <ns1:returnPolicy>
                <ns1:optedForRMA>true</ns1:optedForRMA>
                <ns1:optedForMultipleReturnAddress>true</ns1:optedForMultipleReturnAddress>
            </ns1:returnPolicy>
            <ns1:buyerReturnShipment>
                <ns1:shipmentStatus>READY_FOR_SHIPPING</ns1:shipmentStatus>
                <ns1:carrierUsed>USPS</ns1:carrierUsed>
                <ns1:shippingAddress>
                  <ns1:name>T********r</ns1:name>
                  <ns1:street1>a********s</ns1:street1>
                  <ns1:city>c********y</ns1:city>
                  <ns1:stateOrProvince>**</ns1:stateOrProvince>
                  <ns1:country>US</ns1:country>
                  <ns1:postalCode>9***2</ns1:postalCode>
                </ns1:shippingAddress>
            </ns1:buyerReturnShipment>
         </ns1:ReturnDetail>
      </ns1:getReturnDetailResponse>
   </soapenv:Body>
</soapenv:Envelope>

   Here is the same output in XML format. Note that this does not include standard values.

XML format. Also available is the SOAP equivalent.

<?xml version="1.0" encoding="utf-8"?>
<getReturnDetailResponse xmlns:ns1="http://www.ebay.com/marketplace/returns/v1/services">
   <ack>Success</ack>
   <version>1.0.0</version>
   <timestamp>2012-01-13T18:19:34.707Z</timestamp>
   <ReturnSummary>
      <ReturnId>
         <id>5********8</id>
      </ReturnId>
      <otherParty>
         <userId>u********r</userId>
         <role>BUYER</role>
      </otherParty>
      <returnRequest>
         <returnItem>
            <itemId>1**********0</itemId>
            <transactionId>2*********1</transactionId>
            <returnQuantity>1</returnQuantity>
         </returnItem>
         <returnReason>
            <code>2</code>
            <description>ORDERED_ACCIDENTALLY</description>
         </returnReason>
         <comments>test</comments>
      </returnRequest>
      <status>WAITING_FOR_SELLER_INFO</status>
      <responseDue>
         <party>
            <userId>u********a</userId>
            <role>SELLER</role>
         </party>
         <respondByDate>2011-12-06T23:59:08.000Z</respondByDate>
      </responseDue>
      <creationDate>2011-12-05T16:36:10.000Z</creationDate>
   </ReturnSummary>
   <ReturnDetail>
      <globalId>EBAY-US</globalId>
      <returnHistory>
         <note>test</note>
         <author>
            <userId>0</userId>
            <role>BUYER</role>
         </author>
         <activityDetail>
            <code>1</code>
            <description>buyerCreateReturn</description>
         </activityDetail>
         <creationDate>2011-12-05T16:36:10.000Z</creationDate>
      </returnHistory>
      <refundInfo>
         <estimatedRefundDetail>
            <estimatedRefund>
               <totalAmount currencyId="USD">1.01</totalAmount>
               <itemizedRefund>
                  <refundFeeType>PURCHASE_PRICE</refundFeeType>
                  <amount currencyId="USD">1.01</amount>
               </itemizedRefund>
            </estimatedRefund>
            <itemizedOptionalRefund>
               <refundFeeType>ORIGINAL_SHIPPING</refundFeeType>
               <amount currencyId="USD">5.0</amount>
            </itemizedOptionalRefund>
         </estimatedRefundDetail>
      </refundInfo>
      <returnPolicy>
          <optedForRMA>true</optedForRMA>
          <optedForMultipleReturnAddress>true</optedForMultipleReturnAddress>
      </returnPolicy>
      <buyerReturnShipment>
          <shipmentStatus>READY_FOR_SHIPPING</shipmentStatus>
          <carrierUsed>USPS</carrierUsed>
          <shippingAddress>
            <name>T********r</name>
            <street1>a********s</street1>
            <city>c********y</city>
            <stateOrProvince>**</stateOrProvince>
            <country>US</country>
            <postalCode>9***2</postalCode>
          </shippingAddress>
      </buyerReturnShipment>
   </ReturnDetail>
</getReturnDetailResponse>

Change History