finances API1.1.0

Finances API release notes

Just getting started with the Finances API? See the following documents for details on using this API:

The API release history

The following table lists the releases for the Finances API:

Release Version

Release Date

Description of Release

Version 1.1.0

2020-02-26 Updated getTransactions and getTransactionSummary methods with shipping label capability and 'booking entry' fields for all transaction types

Version 1.0.0

2019-10-26 Initial release of GA version of API

Version 1.1.0

New Features

The following new features were added with this release

getTransactions and getTransactionSummary methods now return shipping label transactions

For sellers in eBay managed payments, eBay will start billing sellers' accounts for eBay-generated shipping labels instead of the seller paying USPS or FedEx directly. eBay shipping label fees will show up on the seller's monthly invoice and these shipping label transaction fees will also be returned in the getTransactions and getTransactionSummary methods.

To support this new feature, the following schema was added:

  • SHIPPING_LABEL enum value added to TransactionTypeEnum type. This new enum value will be returned in the transactionType field if the transaction type is related to a shipping label. This new enum value can also be used as a filter value for the transactionType filter available in the getTransactions and getTransactionSummary methods.
  • shippingLabelCount, shippingLabelAmount, and shippingLabelBookingEntry fields were added to the getTransactionSummary response to account for shipping label transactions. Note that corresponding 'booking entry' fields were added for all transaction types returned in the getTransactionSummary response, and the enum value returned in those fields indicate if the value returned in the 'amount' fields is a charge (debit) or credit to the seller's account.

'Booking entry' fields added for all transaction types

In order to indicate whether a monetary transaction amount is a charge (debit) or a credit to a seller's account, 'booking entry' fields sere added for all transaction types. Negative dollar amounts (e.g -21.75) will not be shown in amount fields, so the 'booking entry' fields are used to indicate if it is a debit or credit to the seller's account.

To support this new feature, the following schema was added:

  • BookingEntryEnum type was added to the Finances API, with its values being DEBIT CREDIT. One of these values will be returned for all monetary transaction amount fields.
  • bookingEntry field was added to Transaction type, and will be returned for all monetary transactions returned under the getTransactions response to indicate if the transaction is a debit or credit to the seller's account.
  • The following 'booking entry' fields were added to the base response of the getTransactionSummary response to indicate if the corresponding cumulative transaction amount is a debit or credit to the seller's account.
    • creditBookingEntry
    • disputeBookingEntry
    • onHoldBookingEntry
    • refundBookingEntry
    • shippingLabelBookingEntry

Changed Functionality

salesRecordReference value can no longer be used to identify orders

For all orders originating after February 1, 2020, a value of 0 will be returned in the salesRecordReference field. The Sales Record Number has also been removed from the Orders tab in Seller Hub, and the plan is to deprecate this field in the future. Sellers can use the orderId field (and as a filter value) instead to identify an order. For orders that originated before February 1, 2020, the actual Sales Record Number will still be shown in the salesRecordReference field.

Doc Changes

Updated samples in getTransactions and getTransactionSummary methods

The samples in the getTransactions and getTransactionSummary documentation have been updated to show the new shipping label and booking entry fields

transactionMemo field description updated to reflect actual behavior

The transactionMemo field description previously stated that the field could be used to provide more details about several different transaction types, but currently, it will only be returned for shipping label transactions. For shipping label transactions, it will provide more detail about whether the transaction is a shipping label purchase, a refund, or a price adjustment to the cost of the shipping label. Itis possible that this field will be used for other transaction types in the future.

Version 1.0.0

This is the first General Availability (GA) release of the Finances API. This initial GA release builds upon the 1.0.0 alpha version. All new users should use the GA version instead of the alpha version. The alpha version endpoints will still be supported for a limited time, but users that are using the alpha version should make plans to migrate to the GA version. Documentation for the alpha version can now be accessed at this URL: https://developer.ebay.com/api-docs/sell/finances-v1_alpha/resources/methods.

Below is a summary of changes between alpha version 1.0.0 and GA version 1.0.0:

  • New getSellerFundsSummary method that retrieves all pending order funds that have yet to be paid out to seller.
  • New payoutStatusDecription field for Payouts, which provides more details about the current status of payout.
  • INITIATED added as a new PayoutStatusEnum value. This value indicates that a payout has been initiated. This new value can be used with the payoutStatus filter in a getPayouts method.
  • The payoutInstrument.institution field has been renamed to payoutInstrument.nickname. Although the name was changed, this field still serves the same purpose of indicating to the seller to which account payouts are being distributed.
  • New transactions.orderId field, which identifies the order associated with the monetary transaction.
  • New transactions.transactionMemo field captures any notes about the monetary transaction.
  • getTransactions and getTransactionSummary methods have been updated to return information on monetary transactions involving eBay managed payment disputes. These payment disputes are disputes that are initiated by the buyer through their payment provider. The new DISPUTE value in the TransactionTypeEnum type can be used with the transactionType filter in a getTransactions or getTransactionSummary method to limit transaction type to payment disputes.

For a list of resources and methods, see the Finances API Call Reference.