eBay API

eBay Finances API 101: reading SALE, NON_SALE_CHARGE, and dispute transactions

Most sellers' first contact with the Finances API is a support thread titled something like "why does my earnings column say -£3 on an order I definitely sold". The honest answer is almost always the same: the Finances API is not a single number, it is a ledger, and reading only part of the ledger gives you a wrong and sometimes actively misleading figure.

Here is what is actually in that ledger, what each entry means for your payout, and the order they tend to arrive in.

The API returns transactions, not totals

Call the Finances API for a date range and you get back a list of individual transactions, each tagged with a transactionType. A single order might generate two, three, or more of these over its lifetime: a sale, an advertising charge, maybe a dispute, maybe a later credit. Your job, or your tooling's job, is to sum the right ones for that order before you call it "earnings".

This is the detail that trips up most home-built trackers, because it is tempting to grab the first transaction you see for an order and treat it as final.

SALE: the actual payout, fees already removed

A SALE transaction is the core one: it represents the buyer's payment landing in your account. Critically, its amount field is already net of the selling fee, which is broken out separately in totalFeeAmount for your records. If you subtract the fee again from the sale amount, you will understate your earnings by double-counting it.

We wrote about the broader version of this mistake in why eBay's Order API gives you the wrong earnings number: the Order API hands you a gross price and lets you guess the fee yourself, while the Finances API's SALE transaction hands you the number that actually hit your account.

NON_SALE_CHARGE: ad fees and other debits that arrive on their own schedule

Promoted Listings advertising charges show up as their own transaction type, commonly a NON_SALE_CHARGE with feeType set to something like AD_FEE. The important quirk: this charge does not always arrive at the same time as the SALE transaction for the same order. On a fresh order it is entirely possible for the ad fee to post to the ledger before the sale itself has settled.

If your tracker naively subtracts every charge it sees from a running total for that order, a brand-new order can show a small negative "earning" made up of nothing but an ad fee, days before the actual sale transaction arrives. That is not a bug in eBay's data, it is a timing gap that your reading logic needs to account for by checking whether a genuine SALE transaction exists for the order before trusting any total.

• Selling fee: already deducted inside the SALE transaction's amount, not a separate line you need to subtract yourself.
• Ad fee: a separate NON_SALE_CHARGE, can arrive before or after the SALE.
• Other charges: refunds, adjustments, and withdrawals also appear as their own transaction types in the same feed.

DISPUTE: a real hold, not a stale reading

A DISPUTE transaction type is a genuine debit that eBay applies when a claim is opened on an order, and it can temporarily or permanently claw back a sale that already settled. This is a different situation from an ad fee arriving early: a dispute hold means eBay has actually reversed money pending investigation, not that your data is simply out of date.

Seeing a negative or near-zero earning on an order that clearly sold is not automatically a data error. Check the transaction list for a DISPUTE entry before assuming something is broken; sometimes the number is telling you the truth about an active claim.

The practical distinction matters: a "no SALE transaction yet" order needs a fallback estimate and a bit of patience, while a "SALE plus DISPUTE" order needs your attention, because there is an active case attached to it.

Building a reader that gets this right

The reliable pattern is to pull every transaction for an order, not just the first one you encounter, and to check specifically whether a SALE transaction is present before you treat any total as final. If no SALE exists yet, fall back to an estimate from the order object itself rather than reporting a partial, charge-only figure as if it were the real earning.

1. Fetch all transactions in the date range, grouped by order ID.
2. Check whether a SALE transaction exists for that order. If not, use an estimate and revisit later.
3. If a SALE exists, sum it with any NON_SALE_CHARGE and DISPUTE entries for the same order to get the true current position.
4. Flag orders carrying a DISPUTE transaction separately, since they represent an active situation rather than a settled number.

Fetch Order Tracking does exactly this on every sync: it reads the full transaction set for each order, only trusts a total once a genuine SALE transaction is present, and writes the real net figure into your Google Sheet instead of a partial reading. See how it works.

Frequently asked questions

Why does a brand-new order sometimes show a negative earning?

This usually happens when a NON_SALE_CHARGE, such as a Promoted Listings ad fee, posts to the Finances API before the order's SALE transaction has settled. Reading logic that trusts any charge as final without checking for a SALE transaction first will report a misleading negative figure for what is actually just a timing gap.

Do I need to subtract the selling fee from the SALE amount myself?

No. The SALE transaction's amount field is already net of the selling fee, which is reported separately in totalFeeAmount for reference. Subtracting it again will understate your true earnings.

What does a DISPUTE transaction mean for my payout?

It means eBay has applied a real debit against a settled sale while a claim, such as an Item Not Received case, is under investigation. It is a genuine hold rather than stale or missing data, and orders carrying one are worth reviewing directly rather than treated as a simple bookkeeping error.

Related guides

• Why eBay's Order API gives you the wrong earnings number
• What changes when eBay sends an order through Promoted Listings Advanced
• Why your gross profit column is wrong (and what to use instead)

---