> For the complete documentation index, see [llms.txt](https://developers.bead.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developers.bead.xyz/reporting.md).

# Reporting

The Reporting section provides read-only access to historical payments recorded in the Bead platform. Use it for reconciliation, analytics, dashboards, and operational audits.

Use Reporting when you need lists of payments filtered by merchant, terminal, partner, date range, status, or tender type. For how those payments were grouped, settled, and funded, use the [Settlements](/settlement/settlements.md) APIs.

> **Building residual or revenue-share reports?** Start with [Settlements](/settlement/settlements.md) for fee and net fundable amount data, then use [Residual Reporting](/settlement/residual-reporting.md) for the full integration pattern. Use Reporting APIs to pull the underlying payment activity for the period.

#### When to use Reporting

Use Reporting when you need to:

* Run daily or monthly reconciliation against internal ledgers.
* Generate statements for partners, merchants, or terminals.
* Build dashboards showing recent sales or payment trends.
* Investigate payment discrepancies such as underpaid or overpaid transactions.
* Filter payment history by status, tender type, currency, date range, or reference.

For real-time updates, use webhooks. Reporting complements — it does not replace — webhook notifications.

#### How it works

1. Send a GET request to one of the payment history endpoints.
2. Bead queries a replicated read-only reporting store, updated within seconds of payment and settlement events.
3. Results are returned in pages. Control page size, sort order, date range, and status filters with query parameters.

#### Available endpoints

| Scope    | Path                       | Best for                                                  |
| -------- | -------------------------- | --------------------------------------------------------- |
| Partner  | `/Partners/{id}/payments`  | Portfolio-wide history across all merchants and terminals |
| Merchant | `/Merchants/{id}/payments` | Store-level sales and per-location reports                |
| Terminal | `/Terminals/{id}/payments` | Device-level reconciliation and troubleshooting           |

All three endpoints share the same query parameters, response schema, and field set. See [Pagination and Sorting](/reporting/payment-history-concepts/pagination-and-sorting.md) for the full parameter reference.

#### Relationship to Settlement

Reporting focuses on payments. Settlement focuses on how those payments were grouped and funded.

Use Reporting when you need payment lists, status filters, and transaction-level fields. Use Settlement when you need fee breakdowns, net fundable amounts, batch groupings, deposit confirmation, or residual reporting data.

A common pattern is to use Reporting to identify the payments for a report or investigation, then use [Settlements](/settlement/settlements.md) to review the settlement fees and net amounts for that period.

#### Consistency and delay

The reporting database is eventually consistent. Most updates appear within seconds, but large payment volumes or settlement batches can take a minute or two. If a job must not miss records, use fixed time windows and paginate until you receive an empty `data` array.

#### Next steps

* Review [Pagination and Sorting](/reporting/payment-history-concepts/pagination-and-sorting.md) for query parameter definitions.
* Use [Partner Payments](/reporting/partner-payments.md) for portfolio-level history.
* Use [Merchant Payments](/reporting/merchant-payments.md) for store-level history.
* Use [Terminal Payments](/reporting/terminal-payments.md) for device-level history.
* Use [Settlements](/settlement/settlements.md) when you need fee totals, adjustments, and net fundable amount.
* Use [Residual Reporting](/settlement/residual-reporting.md) to assemble fee revenue data for partner reporting.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://developers.bead.xyz/reporting.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.