> This is Payabli documentation. For a complete page index, fetch https://docs.payabli.com/llms.txt — append .md to any page URL for lightweight markdown. For section-level indexes, query parameters, and other AI-optimized access methods, see https://docs.payabli.com/ai-agents.md

# Choose a data source for analytics

> Understand when to use the statistics API, the query API, or webhooks to build metrics from your Payabli data

When you build a dashboard, a merchant scorecard, or your own reports, you can get Payabli data from three sources: the statistics API, the query API, and webhooks. Each one answers a different kind of question. Picking the right one up front saves you from rebuilding totals Payabli already calculates, or from computing a metric on data that can't support it.

For how to build requests, filter, and paginate, see [Use reporting endpoints](/guides/pay-ops-reporting-overview). For the Portal dashboard, Portal reports, and Amigo Insights, see [Reporting and analytics overview](/guides/pay-ops-reporting-analytics-overview).

## Compare the data sources

Each source returns a different shape of data.

| Source             | What you get                                                                                                                                                   | Use it for                                                                                                                           |
| ------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Statistics API** | Totals that Payabli already calculated, one row per period (hour, day, week, or month) for an organization, paypoint, customer, or vendor. JSON only.          | Volume, transaction counts, payment method mix, and new customer or vendor counts over time.                                         |
| **Query API**      | Individual records, like transactions, chargebacks, batches, settlements, customers, vendors, and bills. Filterable, paginated, and exportable as CSV or XLSX. | Any metric that needs record-level detail, a filter the statistics API doesn't offer, or a breakdown by customer, vendor, or status. |
| **Webhooks**       | A notification each time an event happens, like a payment approval or a new chargeback.                                                                        | Reacting to events as they happen, and keeping your own copy of activity up to date without polling.                                 |

Start with the statistics API when the metric is a total or a count over time. Move to the query API when you need to see or filter the records behind the total. Add webhooks when you need to act on events as they happen.

## When the statistics API is enough

The statistics endpoints return pre-calculated totals, so one call can replace paging through thousands of transactions. Use them for metrics like these:

* Pay In and Pay Out volume and transaction counts per month, week, day, or hour
* Payment method mix, like card compared to ACH, using the per-method counts and volumes
* New customers or new vendors per period
* Card chargeback and ACH return counts and volumes per period
* Upcoming subscription renewals over the next 30, 60, 90, or more days

The statistics endpoints are:

* [`GET /Statistic/basic`](/developers/api-reference/get-basic-statistics-for-a-paypoint-or-organization) for an organization (`level` 0) or a paypoint (`level` 2). It's the only statistics endpoint that accepts a custom date range, using `mode=custom` with `startDate` and `endDate`.
* [`GET /Statistic/customerbasic`](/developers/api-reference/customer/get-basic-statistics-for-a-customer) for one customer's Pay In activity.
* [`GET /Statistic/vendorbasic`](/developers/api-reference/vendor/get-basic-statistics-for-a-vendor) for one vendor's bills, broken down by bill status.
* [`GET /Statistic/subscriptions`](/developers/api-reference/subscription/get-subscription-statistics-for-a-paypoint-or-organization) for renewals that are coming up.

## When you need the query API

The statistics API can't answer every question. Use the query API in these cases:

* **The metric involves declines.** The statistics API counts approved transactions only, so it can't tell you a decline rate. Query transactions to see every status.
* **You need a breakdown the statistics API doesn't have.** For example, a ranking of every customer on a paypoint by volume. `/Statistic/customerbasic` covers one customer per call, so query the transactions and group them yourself.
* **You need a filter the statistics API doesn't have.** The statistics endpoints filter by entity and period only. Query endpoints accept field filters, like an amount range or a customer ZIP code.
* **You need the individual records.** For example, to work with each dispute or reconcile a batch.
* **You need a file.** Most query endpoints export CSV or XLSX. The statistics endpoints return JSON only.

When you query, the `Summary` block in the response also carries totals for the matching records, like `totalAmount`. For a filtered total, you might not need to add up the rows yourself.

## When to add webhooks

The statistics and query APIs tell you what's in Payabli when you ask. Webhooks tell you when something changes. Use webhooks to update a dashboard as payments arrive, to trigger your own workflows, or to keep your own data store current without polling on a schedule.

To build a history, pair webhooks with the query API. Query the past records once, then let webhooks keep your copy up to date. Payabli retries a failed webhook only twice, so an outage on your side can leave gaps. Run a regular query, like a daily transactions query with date filters, to catch anything you missed, or [resend failed notifications](/guides/pay-ops-notifications-webhooks-overview#retry-logic). To decide between webhooks and polling for a specific workflow, see [Decision guide: Webhooks vs polling](/guides/pay-ops-notifications-webhooks-vs-polling).

## Avoid common mistakes

These details in the statistics responses lead to wrong metrics if you miss them:

* **Don't compare net volume to gross volume.** `/Statistic/basic` volumes are net of fees. `/Statistic/customerbasic` volume is gross, before fees. Pick one basis for a metric and stay with it.
* **Don't add up customer or vendor totals across periods.** `inCustomers` and `outCustomers` are running totals through the end of each period, not counts for that period. For new customers or vendors per period, use `inNewCustomers` and `outNewCustomers`.
* **Don't add subscription payments to the total.** `inSubscriptionsPaid` is part of `inTransactions`, not extra transactions on top of it.
* **Don't treat subscription statistics as revenue.** `/Statistic/subscriptions` is a forecast of renewals that are coming up. For subscription payments already collected, use `inSubscriptionsPaid` and `inSubscriptionsPaidVolume` from `/Statistic/basic`.
* **Read subscription intervals as separate ranges.** In `/Statistic/subscriptions`, `60` covers days 31 through 60 and `90` covers days 61 through 90. They don't include the shorter ranges. Use `all` to get every range in one call.

On the Pay In side of `/Statistic/basic`, the per-method counts don't overlap, and they add up to `inTransactions`. You can safely use them for a payment method breakdown.

## Build a monthly scorecard for one paypoint

To show a merchant their last 12 months of Pay In activity, call `/Statistic/basic` once at the paypoint level with `mode=m12` and `freq=m`:

```curl
curl -X GET https://api-sandbox.payabli.com/api/Statistic/basic/m12/m/2/{entryId} \
    -H "accept: application/json" \
    -H "Authorization: Bearer YOUR_ACCESS_TOKEN"
```

Each row in the response is one month. From those rows, you can chart:

* Monthly volume and transaction count, from `inTransactionsVolume` and `inTransactions`
* Payment method mix, from `inCardVolume`, `inACHVolume`, and the other per-method volumes
* New customers per month, from `inNewCustomers`
* Chargebacks and returns per month, from `inCardChargeBacks` and `inACHReturns`

To add a decline rate or a top-customers list, query the paypoint's transactions for the same date range and calculate them from the records. The transactions query returns only the last 60 days by default, so add `transactionDate` filters to cover all 12 months.

## Build an organization dashboard

For an organization-wide trend line, call `/Statistic/basic` at the organization level (`level` 0) with the organization ID as `entryId`. To compare paypoints side by side, make one call per paypoint at `level` 2. Use the query API to [list the organization's paypoints](/developers/api-reference/paypoint/get-list-of-paypoints-for-an-organization) first.

The statistics API doesn't cover boarding. To track boarding progress, [list the boarding applications](/developers/api-reference/applications/list-applications) instead.

## Related resources

See these related resources to help you get the most out of Payabli.

#### Related topics

* **[Use reporting endpoints](/guides/pay-ops-reporting-overview)** - Build query and statistics requests, filter results, and paginate
* **[Reporting and analytics overview](/guides/pay-ops-reporting-analytics-overview)** - Compare the reporting APIs with the Portal dashboard, Portal reports, and Amigo Insights
* **[Decision guide: Webhooks vs polling](/guides/pay-ops-notifications-webhooks-vs-polling)** - Decide between webhooks and polling for a specific workflow