Introduction

Sellers listing on the German and Austrian sites are now subject to a new payment process. The Order Adjustment API can be used by these sellers to respond appropriately to over or under payments made by buyers of their products on eBay.

Service Overview

Order Adjustment is a SOA service that is intended to be consumed by sellers listing on the German and Austrian sites who need to resolve payment discrepancies in their eBay sales.

Below is a high-level summary of the four calls of the Order Adjustment API:

acceptAdjustment: this call enables a seller to accept over or under payments from a buyer.
rejectAdjustment: this call enables a seller to reject over or under payments from a buyer.
issueRefund: this call enables the seller to voluntarily provide a refund to a buyer.
getVersion: this call returns the current version of the Order Adjustment service.

Refer to the Order Adjustment API Call Reference for detailed information on each call, including input fields, output fields, and samples.

Responding to Over or Under Payments

In the new payment process for German and Austrian sellers, buyers can make adjustments to various aspects of their online purchases on eBay which might result in over or under payments of the total amount of the orders. The calls in the Order Adjustment API enable sellers to respond appropriately to those discrepancies.

Calling acceptAdjustment

To accept an over or under payment by a buyer on a particular order, use the acceptAdjustment call. A valid eBay order ID is required to be passed into the orderId.id field. With this call, the seller indicates that the payment on the order is satisfactory.

The acceptAdjustment Response

The acceptAdjustment response contains only the standard output fields. If the call is successful, a payment adjustment is created on the order.

Calling rejectAdjustment

To reject an over or under payment by a buyer on a particular order, use the rejectAdjustment call. A valid eBay order ID is required to be passed into the orderId.id field. With this call, the seller indicates that the payment on the order is not satisfactory.

The rejectAdjustment Response

The rejectAdjustment response contains only the standard output fields. If the call is successful, the order is cancelled and the buyer's payment is returned.

Calling issueRefund

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.

The issueRefund 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.

Platform Notifications for Order Adjustment

Using the SetNotificationPreferences call of the Trading API, users can subscribe to the following platform notifications related to order adjustment.

RefundSuccessful: this notification is sent to German and Austrian sellers when the seller’s refund (using the site or the issueRefund call of the Order Adjustment API) to the buyer is successful.
The payload of this notification is identical to the fields found in the response to the GetOrders call of the Trading API.
RefundFailed: this notification is sent to German and Austrian sellers when the seller’s refund (using the site or the issueRefund call of the Order Adjustment API) to the buyer fails.
The payload of this notification is identical to the fields found in the response to the GetOrders call of the Trading API.

For more information on these notifications and the Platform Notification process, see the Trading API Guide.

Working with the Order Adjustment API

API Call Limits

Please refer to the API Call Limits page on the eBay Developers Program site for current default call limits and call limits for applications that have completed the Compatible Application Check, which is a free service that the eBay Developers Program provides to its members.

Sandbox Environment

For more information about testing, refer to Testing Overview in the Making an Order Adjustment API Call document.

API Reference

Refer to the Call Reference for a list of calls in the Order Adjustment API. The Call Reference includes the following information:

Prototypes of the request and response structure for each call
Comprehensive list of inputs and outputs supported by each call and descriptions of their meaning and behavior
Call samples (request and response)
Index of schema elements (types, fields, enumerations)
Change history information for each call

Additional Resources

You can get more information about the Order Adjustment API at these locations:

User-Contributed Notes

Share tips or code samples related to this call or topic. Questions or observations are welcome, too.

eBay employees moderate these notes to ensure they are pertinent to the document and relevant to the community. Your submission will show up for all developers when it is activated by the moderator.

This documentation and the API may only be used in accordance with the eBay Developers Program and API License Agreement.

Order Adjustment API Users Guide