finances API1.4.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.4.0

2020-08-21

Currency conversion for Active Cross-Border Trade enabled, and new transfer resource and getTransfer endpoint added to API

Version 1.3.0

2020-07-09

New TRANSFER transaction type added to getTransactions and getTransactionSummary

Version 1.2.0

2020-06-15 Updated getTransactions method to return selling fees that are deducted from seller payouts, and added a lastAttemptedPayoutDate filter to getPayouts method

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-06-26 Initial API release

Version 1.4.0

New Features

The following new features were added with this release

New transfer resource and getTransfer method added

The getTransfer method retrieves detailed information regarding a TRANSFER transaction type. A TRANSFER is a monetary transaction type that involves a seller transferring money to eBay for reimbursement of a charge

The new schema is summarized below:

  • getTransfer: the new endpoint
  • Transfer: this type is used by the base response of the getTransfer method
  • TransferDetail: this type is used to give full details about a specific transfer, including all charges that are a part of the transfer
  • Charge: this type is used to list each charge that is part of the transfer of funds

Currency conversion fields added to Amount type

The capability to do currency conversion for cross-border trade has been enabled for the Finances API. The following three fields were added to Amount type:

  • convertedFromCurrency
  • convertedFromValue
  • exchangeRate

Version 1.3.0

New Features

The following new feature was added with this release

New TRANSFER transaction type added to getTransactions and getTransactionSummary

For managed payments sellers, the new transaction type TRANSFER is available. This new type tracks seller reimbursements to eBay for buyer refunds.

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

  • getTransactionSummary has added the following response fields:

    • transferAmount: Total transfer amount for given payee within a specified period. Additional supporting fields include currency and value.
    • transferBookingEntry: The credit debit sign indicator for transfer.
    • transferCount: Total transfer count for given payee within a specified period.
  • TransactionTypeEnum type has added the new value TRANSFER. This value indicates that the monetary transaction type involves a seller transferring money to eBay for reimbursement of a buyer refund.
  • TransactionStatusEnum type has added the new values COMPLETED and FAILED. These values indicate whether the monetary transaction type involving a seller transferring money to eBay for reimbursement has completed, or has failed.

Version 1.2.0

New Features

The following new features were added with this release

getTransactions returns selling fees that are deducted from seller payouts

For managed payments sellers who are subject to having final value fees deducted from seller payouts, two new amount fields and a line item-level fees array will be returned for each sales transaction. As of mid-June 2020, this will only apply to a limited number of sellers, but many other managed payments sellers will start getting some selling fees deducted from seller payouts starting in mid-July 2020.

The new schema is summarized below:

  • totalFeeBasisAmount: this field shows the cumulative base amount used to calculate the final value fees for each line item in the order.
  • totalFeeAmount: this field shows the cumulative amount of selling fees for all line items in the order that will be deducted from seller payout.
  • orderLineItems: This array shows the fees that are deducted from a seller payout for each line item in an order.

New paymentsEntity field returned for sales and refunds

A new paymentsEntity field will be returned for all sales and buyer refund transactions. The value in this field just indicates the eBay partner entity that is processing the payment.

getPayout/getPayouts enhanced with lastAttemptedPayoutDate field

A new lastAttemptedPayoutDate field will be returned for all seller payouts. This field was added to help sellers follow up on seller payouts that failed upon the initial attempt.

In getPayouts, a seller will also be able to filter against and sort based on a lastAttemptedPayoutDate date range. For seller payouts that have failed at least once, the timestamps in the payoutDate and lastAttemptedPayoutDate fields will be different. For seller payouts that were successful on the first attempt, the the timestamps in the payoutDate and lastAttemptedPayoutDate fields will be identical.

Doc Changes

New sample added in getTransactions

A new sample was added to getTransactions to show the new selling fee fields.

New sample added in getPayouts

A new sample was added to getPayouts to show the new lastAttemptedPayoutDate filter.

Updated samples in getTransactions

The samples in the getTransactions documentation have been updated to show the new paymentsEntity field, which will be returned for all sales and buyer refund transactions.

Updated samples in getPayouts

The samples in the getPayouts documentation have been updated to show the new lastAttemptedPayoutDate field returned for all seller payouts.

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 initial release of the Finances API, Version 1.0.0

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