Order Adjustment API Call Reference Version 1.0.0 Support     Knowledge Base     Forums     All Tutorials     All Code Samples Users Guide Call Reference Making an API Call Tutorials Release Notes

Call Index Field Index Enumeration Index Type Index Errors by Number Input Output Samples Change History User Notes

issueRefund

Use the issueRefund call to voluntarily provide a refund to a buyer. The seller can refund the item price, the shipping cost or an additional amount for one or more line items in the order.

Currently, issueRefund may be applied to one order at a time.

Request Details

If the seller determines that a buyer has overpaid for a particular order, the seller can issue a voluntary refund of the appropriate amount rather than simply rejecting the order. To issue a refund to the buyer, use the issueRefund call. With this call, the seller indicates that the payment on the order can be adjusted satisfactorily.

The issueRefund call requires the following inputs:

• A valid eBay order ID must be passed into the orderId.id field.
• The seller must create and maintain a unique identifier for this issueRefund request for the specified order. Pass this identifier into the externalReferenceId field.
• To specify the line item details of the refund, include one or more lineItem containers, each with the following information for an order line item that is being refunded:
  • orderLineItemId identifies the order line item.
  • One or more priceLine containers provide details of the refund for different charge components of the order line item.
  • For each priceLine of an order line item, specify the type of charge (purchase price, shipping, etc.) and the corresponding refundAmount to be refunded for that type.
• Specify the totalrefundAmount of all line items being refunded with this call.

To optionally provide additional security to this call, specify the unique eBay user ID of the buyer in the buyerId field. This will be validated against the user ID value derived from the orderId.id field. If the values do not match, the call will fail.

To provide the buyer with additional information about any aspect of the refund, include a text message in the note field.

Working with the Response

The issueRefund response returns the refundStatus field to indicate whether the refund was successfully issued, or failed, or is still pending.

If the call failed, eBay in some cases provides the address of an eBay website page in the errorUrl field, where seller can take certain actions that will enable the refund processing to complete.

If the refund is pending, the eBay refunds system uses the estimatedCompletionDate field to return an estimate of the date that the refund transaction will be complete.

If the refund succeeded, the response includes the following outputs:

• refundTransactionId: this field identies the eBay transaction that produced the refund.
• refundFundingSource: this container provides information about the refund, including the following:
  • fundingSource: this field identifies the monetary source from which the refund was made, such as the seller's bank account that is registered with eBay.
  • accountNumber: this field contains the seller's account number with the funding source.
  • amount: this field contains the total amount of money that was refunded to the buyer.
  • processorTransactionId: this field is returned for some refund funding sources, containing a string provided by the funding source that identifies the disbursement transaction for the refund.

Back to top

issueRefund Input

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

<?xml version="1.0" encoding="utf-8"?>
<issueRefundRequest xmlns="http://www.ebay.com/marketplace/payment/v1/services">
  <buyerId> string </buyerId>
  <externalReferenceId> string </externalReferenceId>
  <lineItem> RefundLineItemType
    <orderLineItemId> string </orderLineItemId>
    <priceLine> PriceLine
      <refundAmount currencyId="string"> Amount (double) </refundAmount>
      <type> PriceLineType </type>
    </priceLine>
    <!-- ... more priceLine nodes here ... -->
  </lineItem>
  <!-- ... more lineItem nodes here ... -->
  <note> string </note>
  <orderId> OrderIdType
    <id> string </id>
  </orderId>
  <refundType> RefundType </refundType>
  <totalRefundAmount currencyId="string"> Amount (double) </totalRefundAmount>
</issueRefundRequest>

Back to top

issueRefund Output

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

<?xml version="1.0" encoding="utf-8"?>
<issueRefundResponse xmlns="http://www.ebay.com/marketplace/payment/v1/services">
  <!-- Standard Output Fields -->
  <ack> AckValue </ack>
  <errorMessage> ErrorMessage
    <error> ErrorData
      <errorId> long </errorId>
      <message> string </message>
    </error>
    <!-- ... more error nodes here ... -->
  </errorMessage>
  <extension> ExtensionType
    <contentType> string </contentType>
    <id> positiveInteger </id>
    <value> string </value>
    <version> string </version>
  </extension>
  <!-- ... more extension nodes here ... -->
  <timestamp> dateTime </timestamp>
  <version> string </version>
  <!-- Call-specific Output Fields -->
  <errorUrl> string </errorUrl>
  <estimatedCompletionDate> dateTime </estimatedCompletionDate>
  <refundFundingSource> RefundFundingSource
    <accountNumber> string </accountNumber>
    <amount currencyId="string"> Amount (double) </amount>
    <fundingSource> FundingSourceType </fundingSource>
    <processorTransactionId> string </processorTransactionId>
  </refundFundingSource>
  <!-- ... more refundFundingSource nodes here ... -->
  <refundStatus> RefundStatus </refundStatus>
  <refundTransactionId> string </refundTransactionId>
</issueRefundResponse>

Back to top

issueRefund Samples

New to making API calls? Please see Making an API 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.

Enables a seller to voluntarily provide a refund to a buyer. The seller can refund the item price, the shipping cost or an additional amount for one or more line items in the order.

Description

This issueRefund call enables a seller to issue a refund to a buyer for a specified order. If the call is successful, a refund is disbursed to the buyer.

This call can fail for a number of reasons. The caller must be authenticated to make this call.

Input

The seller wants to refund EUR 1.04 on order line item 6546546546-65765756765, for the order with order ID 4546546546. The seller has generated the external reference ID of 34534534 to track this request. The buyer ID provided for additional security is ererterter.

XML format (HTTP POST). Also available are the .txt version of this XML and the SOAP equivalent.

<?xml version="1.0" encoding="utf-8"?>
<issueRefundRequest xmlns="http://www.ebay.com/marketplace/payment/v1/services">
   <!-- Optional: -->
   <buyerId>ererterter</buyerId>
   <externalReferenceId>34534534</externalReferenceId>
   <orderId>
      <id>4546546546</id>
   </orderId>
   <totalRefundAmount currencyId="EUR">1.04</totalRefundAmount>
   <!-- Optional: -->
   <note>test</note>
   <!-- 1 or more repetitions: -->
   <lineItem>
      <orderLineItemId>6546546546-65765756765</orderLineItemId>
      <!-- 1 or more repetitions: -->
      <priceLine>
         <type></type>
         <refundAmount currencyId="EUR">1.04</refundAmount>
      </priceLine>
   </lineItem>
</issueRefundRequest> 

Output

The ack field indicates that the call was successful. However, the refund itself has failed with an errorId of 105522. The refund could not be issued because the seller's refund and resolution billing agreement was canceled. eBay has provided an errorUrl address where the seller can reestablish the agreement before attempting this call again.

XML format. Also available are the .txt version of this XML and the SOAP and SOAP_XML equivalents.

<?xml version="1.0" encoding="UTF-8"?>
<issueRefundResponse xmlns="http://www.ebay.com/marketplace/payment/v1/services">
   <ack>Success</ack>
      <errorMessage>
         <error>
            <errorId>105522</errorId>
            <message>Your refund could not be processed. No money has been withdrawn from your account. Your refund could not be processed because the refund and resolution billing agreement has canceled. Please log into PayPal and reaccept the refund and resolution billing agreement to finalize the refund.</message>
         </error>
      </errorMessage>
   <version>1.0.0</version>
   <timestamp>2012-04-05T23:01:43.049Z</timestamp>
   <refundStatus>Failure</refundStatus>
   <errorUrl>https://paymentscmd.de.sandbox.ebay.com/ws/eBayISAPI.dll?OpmsUserAgreement&carid=408a06f64b5c3b9a334f0adcaba092a7</errorUrl>
</issueRefundResponse>

Back to top

issueRefund Change History

Back to top

User-Contributed Notes

Copyright © 2012 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.