Introduction

The Payout Details API can be used by sellers listing on the German and Austrian sites to retrieve details on payouts sent by eBay to the seller's account.

This API is used by sellers listing on the German and Austrian sites. These sellers will use the Payout Details API to discover the status of, or review the details of their payout(s) for one or more orders that are subject to the new eBay payment proccess.

Note: Payout Details API Version 1.1.0 is only available for testing in the Sandbox environment until May 7, 2012. Until this service becomes available in the Production environment in May, DE and AT sellers should use Payout Details API Version 1.0.0 to retrieve seller payouts. Fields that are only available in 1.1.0 Version are called out in this documentation.

Service Overview

Payout Details is a SOA service that is intended to be consumed by sellers listing on the German and Austrian sites who are interested in retrieving detailed information about payouts from eBay to their seller accounts.

Below is a high-level summary of the three calls of the Payout Details API:

getOrderPayoutDetails: this call allows the seller to retrieve detailed seller payout information based on a specific eBay order ID.
getPayoutDetails: this call allows the seller to retrieve detailed seller payout information based on a specified date range or by specific payout ID(s).
getVersion: this call returns the current version of the Payout Details service.
getScheduledPayoutDetails: this call allows the seller to retrieve all seller payouts scheduled to be distributed to the seller's account. Note that this call is new for Version 1.1.0.

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

Retrieving Seller Payouts

In the new eBay payment process for German and Austrian sellers, eBay sends money to the seller's account as aggregated payouts. The three calls in the Payout Details API allow these sellers to retrieve detailed information on these payouts.

Calling getOrderPayoutDetails

To retrieve seller payout information based on a specific eBay order ID, use the getOrderPayoutDetails call. A valid eBay order ID is required to be passed into the orderId.id field.

The getOrderPayoutDetails Response

The getOrderPayoutDetails response provides the seller a detailed look at seller payout(s) for the specified eBay order ID. All seller payout information for the order is contained under one or more payoutDetail elements. One payoutDetail element is returned for each seller payout related to the order. The following are the key containers and fields under the payoutDetail element:

actualPayoutAmount: this field indicates the total amount of the seller payout paid to, or due to paid to the seller.
payoutStatus: this field indicates the status of the seller's payout. The two possible values are PaidOut (funds are in seller's account) or PayoutSent (funds are en route to the seller's account).
payoutDate: this timestamp indicates the date and time when the payout was made by eBay to the seller's account.
orderPayoutDetailType: this container contains detailed information about the order, including unique identifiers for the order (order ID, transaction ID(s), and buyer ID), the order amount, the amount of any seller refunds to the buyer, and a flag to indicate if there are multiple payouts associated with the order.
payoutAccountDetail: this container consists of the account type and number of the seller's account to which funds will be sent.
caseFund: this container is returned if there is an eBay Buyer Protection case filed against the eBay order, and includes the case ID and the monetary amount in dispute for the case.
refund: this container is only returned if the seller has issued one or more refunds to the buyer for the order. A separate refund transaction is required for each order line item, and for each refund type. For example, refunding purchase price and refunding shipping are two separate refund transactions. Note that the refund container is not yet available in the Production environment.

If no payouts have been made for the order, or the orderId is invalid, an error is returned.

See the getOrderPayoutDetails call reference for more information on the getOrderPayoutDetails response.

Calling getPayoutDetails

To retrieve seller payout information based on specific payout IDs, or a specified date range, use the getPayoutDetails call. Either payout IDs or a date range can be used to restrict/control results, but not both.

One or more payout IDs are passed into the payoutId field of the payoutIdArray container. If a payoutId is invalid, an error is returned

To filter by a date range, include the payoutDateRange container and specify a fromDate and a toDate value. All payouts processed by eBay within the specified date range are returned in the response. The maximum date range that can be specified with the fromDate and toDate values (or fromDate to present) is 90 days.

If you expect the response payload of a getPayoutDetails call to be large, pagination can be used to control the number of seller payouts returned per page of data. If there are multiple pages of seller payouts to view, you can programmatically "scroll" through the pages by making subsequent calls, incrementing the paginationInput.entriesPerPage value each time until all pages have been viewed and/or handled.

The getPayoutDetails Response

The getPayoutDetails response provides the seller a detailed look at payouts for the specified payout ID(s), or for all payouts processed by eBay within a specified date range. One payoutDetail element is returned for each seller payout. The following are the key containers and fields under the payoutDetail element:

actualPayoutAmount: this field indicates the total amount of the seller payout(s) paid to, or due to paid to the seller.
payoutStatus: this field indicates the status of the seller's payout. The two possible values are PaidOut (funds are in seller's account) or PayoutSent (funds are en route to the seller's account).
payoutDate: this timestamp indicates the date and time when the payout was made by eBay to the seller's account.
orderPayoutDetailType: this container contains detailed information about the order, including unique identifiers for the order (order ID, transaction ID(s), and buyer ID), the order amount, the amount of any seller refunds to the buyer, and a flag to indicate if there are multiple payouts associated with the order.
payoutAccountDetail: this container consists of the account type and number of the seller's account to which funds will be sent.
caseFund: this container is returned if there is an eBay Buyer Protection case filed against the eBay order, and includes the case ID and the monetary amount in dispute for the case.
refund: this container is only returned if the seller has issued one or more refunds to the buyer for the order. A separate refund transaction is required for each order line item, and for each refund type. For example, refunding purchase price and refunding shipping are two separate refund transactions. Note that the refund container is not yet available in the Production environment.

The paginationOutput container is always returned, even when the caller does not include the paginationInput container in the request. The child fields of the paginationOutput container include the total number of payouts returned based on the input criteria, the number of seller payouts per page, the total pages returned, and the current page number of results.

See the getPayoutDetails call reference for more information on the getPayoutDetails response.

Calling getScheduledPayoutDetails

To retrieve all payouts that are scheduled for disbursement from eBay to the seller, use the getScheduledPayoutDetails call. The optional paginationInput container can be used to control the pagination of the result set, including the the maximum number of scheduled payouts returned per page and the page number to retrieve.

Note: The getScheduledPayoutDetails call was introduced with Payout Details API Version 1.1.0, and is not yet available in the Production environment.

The getScheduledPayoutDetails Response

The getScheduledPayoutDetails response provides the seller a detailed look at all scheduled seller payout(s) for the seller. All seller payout information for the order is contained under one or more scheduledPayoutDetail elements. One scheduledPayoutDetail element is returned for each scheduled seller payout. The following are the key containers and fields under the scheduledPayoutDetail element:

estimatedPayoutAmount: this field indicates the expected amount of the seller payout.
estimatedPayoutDate: this timestamp indicates the expected date of the seller payout.
orderDetail: this container contains detailed information about each order tied to the scheduled seller payout, including unique identifiers for the order (order ID, transaction ID(s), and buyer ID), the order amount, and the amount of any refund issued from the seller to the buyer.
payoutAccountDetail: this container consists of the account type to which funds will be sent.
caseFund: this container is returned if there is an eBay Buyer Protection case filed against the eBay order, and includes the case ID and the monetary amount in dispute for the case.
refund: this container is only returned if the seller has issued one or more refunds to the buyer for any of the orders tied to the scheduled seller payout. A separate refund transaction is required for each order line item, and for each refund type. For example, refunding purchase price and refunding shipping are two separate refund transactions.

Platform Notifications for Seller Payouts

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

ReadyToShip: this notification is sent to a DE or AT seller when an order (subject to the new eBay payment process) has been paid for by the buyer. This notification is triggered and sent when Checkout status is complete in GetOrders and other order retrieval API calls. Shipping the item and providing proof of shipment can expedite the process of eBay distributing payouts to the seller's account.
ReadyForPayout: this notification is sent to a DE or AT seller when a seller payout for the order is scheduled to be distributed to the seller's account in the next payout cycle. This notification is triggered and sent when the value of PaymentHoldStatus is 'Complete' in GetOrders and other order retrieval API calls.

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

Working with the Payout Details 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 a Payout Details API Call document.

API Reference

Refer to the Call Reference for a list of calls in the Payout Details 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 Payout Details 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.

Payout Details API Users Guide