canonical: https://jentic.com/apis/apiz.ebay.com/sell-finances

# Ebay Finances API

The eBay Finances API gives sellers programmatic access to their payouts and the underlying monetary transactions that make up each payout. Through OAuth-scoped endpoints a seller can retrieve individual payouts, list payout history, fetch a financial summary, and drill into the order, refund, and dispute transactions that net to each settlement. The API is the system of record for cash movement on a seller account and is widely used to reconcile eBay activity into accounting platforms like QuickBooks and Xero.

## For AI agents

Retrieve eBay seller payouts, transaction history, and funds summaries via OAuth so accounting integrations can reconcile cash movement.

## Scope

Does not handle listing management, order fulfilment, refund issuance, or triggering payouts to bank accounts - use for reading payouts, transactions, and funds summaries only.

## Capabilities

- Retrieve a specific seller payout by ID via GET `/payout/{payout_Id}`
- List paginated seller payouts with date filters via GET /payout
- Fetch a payout summary across a date range via GET /payout_summary
- Read the seller's current funds balance via GET /seller_funds_summary
- List the underlying monetary transactions that make up payouts via GET /transaction
- Fetch a specific transfer detail via GET `/transfer/{transfer_Id}`

## Use cases

### Accounting Reconciliation

Bookkeepers reconcile eBay seller activity into QuickBooks or Xero by pulling each payout and the transactions that net to it. GET /payout lists settlements in a window, GET `/payout/{payout_Id}` returns the headline figures, and GET /transaction breaks the payout into orders, refunds, and fees so the journal entries line up to the cent.

Example prompt: Call GET /payout for the last month, iterate each payout, and pull GET /transaction filtered by payout ID to populate journal entries in the accounting system.

### Seller Cash-flow Dashboard

Multi-channel sellers build cash-flow dashboards that show pending balance, recent payouts, and the trajectory of weekly settlements. GET /seller_funds_summary returns the live balance, GET /payout_summary returns the period total, and the per-payout endpoints supply the detail when the user clicks through.

Example prompt: Call GET /seller_funds_summary for the live balance and GET /payout_summary for the trailing 30 days, then render both in the seller dashboard.

### Dispute and Refund Audit

When a seller queries why a payout came in lower than expected, support and finance teams use the Finances API to walk every deduction. GET /transaction with a transactionType filter surfaces refunds and dispute holds against a payout so the team can attribute the gap to a specific order rather than guess.

Example prompt: Call GET `/payout/{payout_Id}` for the disputed settlement, then GET /transaction filtered by that payout to list every refund and dispute deduction.

### AI Agent Finance Assistant

An AI assistant for an eBay seller pulls payout figures and explains the cash impact of recent activity through Jentic. Jentic isolates the OAuth credential, surfaces the right Finances operation by intent, and validates inputs against the schema, so the agent only has to pick the time window.

Example prompt: Search Jentic for 'list eBay payouts', load the GET /payout schema, and execute it for the last 30 days to summarise total settlements for the seller.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/payout` | List seller payouts with date and status filters. |
| GET | `/payout/{payout_Id}` | Retrieve a specific payout by ID. |
| GET | `/payout_summary` | Aggregate payout figures across a date range. |
| GET | `/seller_funds_summary` | Get the seller's current funds balance. |
| GET | `/transaction` | List the monetary transactions that make up payouts. |
| GET | `/transaction_summary` | Aggregate transaction figures across a date range. |
| GET | `/transfer/{transfer_Id}` | Retrieve a specific transfer detail. |

## Key resources

- **Payout** — List and retrieve seller payouts; pull headline payout records by ID or by date filter.
- **PayoutSummary** — Aggregate payout figures across a date window for finance reporting.
- **SellerFundsSummary** — Live balance and pending funds for the authenticated seller account.
- **Transaction** — List and summarise the monetary transactions (orders, refunds, fees, holds) that make up payouts.
- **Transfer** — Retrieve a specific transfer record tied to a payout.

## Why Jentic

- **Setup:** Wiring the eBay Finances API by hand means running the seller OAuth2 flow, refreshing tokens, and mapping payout, transaction, and transfer reads against the apiz.ebay.com host yourself. Through Jentic you install once, import the eBay Finances API from the API Directory, store the OAuth token once, and your agent calls it.
- **Permission scoping:** The Finances API puts payout and transfer ids in the URL path (`/payout/{payout_Id}`, `/transfer/{transfer_Id}`), and every operation here is read-only, so a rule can pin your agent to reading a specific payout or transfer and its summaries. You choose the operations it may call, so it reads payouts and transactions and cannot trigger any payout or transfer.
- **Credential handling:** Your eBay seller OAuth token is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'list eBay seller payouts' or 'get eBay funds balance', and Jentic returns the matching Finances operation with its filter schema so the agent calls the right endpoint without reading eBay's REST docs.

## Related APIs

- **eBay Identity API** — Use Identity to confirm which eBay seller is authenticated before pulling Finances data.
- **eBay Sell Account API** — Manage seller payment, fulfilment, and return policies that drive how Finances records are produced.
- **PayPal Payouts API** — Alternative settlement view for sellers that still use PayPal as a payout channel.

## FAQ

### What authentication does the eBay Finances API use?

The Finances API uses OAuth 2.0 with the seller's account scopes. The seller authorises your application, you exchange the code for an access token, and pass it as a bearer token on each call. Through Jentic the OAuth token is stored encrypted in the vault and injected at call time, so the agent never sees raw seller credentials.

### Can I trigger a payout to the seller's bank account with this API?

No. The Finances API is read-only - you can list payouts, summarise them, and drill into transactions, but eBay schedules the settlement to the seller's bank itself. Use this API for reconciliation and reporting, not for moving money.

### What are the rate limits for the eBay Finances API?

Specific limits are not declared in the spec but eBay applies application-level limits per call type that surface as 429 responses. For reconciliation jobs use GET /payout with date filters and back off on 429 rather than fanning out per-payout calls in parallel.

### How do I list this month's payouts through Jentic?

Run pip install jentic, then search Jentic for 'list eBay payouts', load the schema for GET /payout, and execute it with the filter parameter set to a date range covering the current month. Jentic injects the OAuth bearer token from your stored credentials. Run it through Jentic One, the self-hosted execution layer.

### How do I see why a payout was lower than expected?

Call GET `/payout/{payout_Id}` for the headline figures, then GET /transaction filtered by that payout to list each refund, dispute deduction, and fee. The transaction breakdown is what reconciles to the headline payout amount.

### Does the Finances API cover historical payouts back to account opening?

GET /payout supports date-range filters and returns historical payouts as far back as the underlying eBay account retention permits. For very old activity, expect the seller account itself to be the binding constraint rather than the API.

### Can I limit what my agent is allowed to do with the eBay Finances API?

Yes. Jentic One is self-hosted, so you run it and your own rules decide which Finances operations and credentials the agent may use. Because every operation here is read-only, you can allow only the reads you want, such as GET /payout, GET /payout_summary, GET /seller_funds_summary, and GET /transaction, and the agent still cannot trigger any payout or transfer. Since payout and transfer IDs sit in the path (`/payout/{payout_Id}`, `/transfer/{transfer_Id}`), you can even pin the agent to a specific payout or transfer and its summaries.