> ## Documentation Index
> Fetch the complete documentation index at: https://docs.streamlinedpayments.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Reports

> Read the figures your dashboard and customer pages show, and see how each one is worked out.

The report endpoints return the same numbers as your Streamlined dashboard and customer pages, from the same calculations. Use them to put your receivables, collections, and customer habits into your own tools.

## Before you start

Every request needs your `X-App-Id` and `X-Api-Key` headers. See [Authentication](https://docs.streamlinedpayments.com/authentication.md).

```bash theme={null}
curl https://api.staging.streamlinedpayments.com/api/v1/reports/aging \
  -H "X-App-Id: $STREAMLINED_APP_ID" \
  -H "X-Api-Key: $STREAMLINED_API_KEY"
```

```json theme={null}
{
  "currency": "USD",
  "total_receivables": 124900000,
  "overdue_receivables": 40200000,
  "credits": 120000,
  "invoice_count": 214,
  "buckets": {
    "not_yet_due": { "amount": 84700000, "invoice_count": 150 },
    "between_1_and_30_days": { "amount": 21800000, "invoice_count": 38 },
    "between_31_and_60_days": { "amount": 8200000, "invoice_count": 14 },
    "between_61_and_90_days": { "amount": 6100000, "invoice_count": 8 },
    "over_91_days": { "amount": 4100000, "invoice_count": 5 }
  }
}
```

These rules hold for every report:

| Rule | Detail |
| - | - |
| Amounts | In cents, in the `currency` the response names. Company reports convert every currency into yours. Customer and group reports use that customer's or group's currency. |
| Rates and shares | Fractions, where `0.25` is 25%. |
| Dates | `YYYY-MM-DD`. Months are `YYYY-MM`. Both are in your account's time zone. |
| Freshness | An answer can be up to five minutes old, except receivables aging. |
| Pages | Lists take `page` (1 to 10000) and `per_page` (default 20). A `per_page` above 100 is treated as 100. `meta` counts every row, not only the page. |
| Missing figures | A figure that can't be worked out yet is `null`, never `0`. |

## Errors

| Status | `error` | Means | What to do |
| - | - | - | - |
| `400` | `invalid_parameter` | A parameter is malformed, out of range, or not one of its allowed values. `message` names it. | Fix the parameter. Values are refused, not ignored. |
| `404` | `customer_not_found` | No customer with that UUID in your account, or it was deleted. | Check the UUID and the environment. |
| `404` | `customer_group_not_found` | No customer group with that UUID in your account. | Check the UUID and the environment. |

See [Errors](https://docs.streamlinedpayments.com/errors.md) for `401` and `429`.

## Receivables aging

[Get receivables aging](https://docs.streamlinedpayments.com/api-reference/reports/get-receivables-aging.md) shows what your customers owe now, by how far past due. The buckets use the same names as an invoice's `aging_status`, described in [Invoice status and aging](https://docs.streamlinedpayments.com/guides/invoice-status-and-aging.md).

* `total_receivables` is the sum of the buckets. Unapplied credit doesn't reduce it. It's reported on its own as `credits`.
* An invoice paid in milestones can have one milestone in each of two buckets, so the bucket invoice counts can add up to more than `invoice_count`.

## Monthly sales and payments

[Get monthly sales and payments](https://docs.streamlinedpayments.com/api-reference/reports/get-monthly-sales-and-payments.md) gives one row per month.

* `sales_amount` is the invoices issued that month. Voided invoices are left out.
* `payment_amount` is the payments received that month.
* With no dates, you get the last six months, including this one. With `start_date` and `end_date`, you get every month they touch, up to 24.

## Average payment period

[Get average payment period](https://docs.streamlinedpayments.com/api-reference/reports/get-average-payment-period.md) gives, for each month, the average days to pay (`average_days_to_pay`) across the invoices paid off that month.

* Days to pay runs from an invoice's issue date to the payment that paid it off.
* `median_days_to_pay` is the median of the same days. A few very old invoices can pull the average far up, so the median is the better guide to how long most invoices take.
* A month with nothing paid off is `null`. `0` means invoices were paid on the day they were issued.
* It takes the same dates as monthly sales and payments.

## Weekly collections

[Get weekly collections](https://docs.streamlinedpayments.com/api-reference/reports/get-weekly-collections.md) compares each week's payments with what was owed when the week started.

* A week runs Monday to Sunday in your time zone. Only complete weeks are rows: the current week is the estimate.
* `payments` counts every payment received that week, applied to an invoice or not. Refunds, chargebacks, and credit notes are left out. `by_method` splits it, adding up to `payments`.
* `rate` is `payments` over `opening_receivables`. It can be above 1, because a week can collect invoices issued during it.
* `usual_rate` is the total payments over the total opening receivables of up to the last 52 weeks.
* `estimate.expected` is what's owed now times the same rate over up to the last 13 weeks. `low` and `high` use the 25th and 75th percentile weekly rate of up to the last 52 weeks. It's a projection from past weeks, not a guarantee.
* The estimate needs 8 complete weeks since your first payment. Until then, `estimate` is `null` and `estimate_unavailable_reason` says why.
* With nothing owed, or nothing paid in the last 13 weeks, `estimate` is `null` rather than `0`, and `estimate_unavailable_reason` is `no_open_receivables` or `no_recent_payments`.
* The estimate and `usual_rate` don't change with `weeks`, `start_date`, or `end_date`.
* With `compare=true`, each week gets `prior_year_rate`, the rate of the same week a year earlier.

> [!NOTE]
>
> The first time your weekly figures are worked out, the response has `status: "preparing"` and no rows. Ask again in a few minutes. Every later response has `status: "ready"`.

## Top customers

[List top customers](https://docs.streamlinedpayments.com/api-reference/reports/list-top-customers.md) ranks customers by `basis`.

* `sales` ranks by invoices issued in the range. `cash` ranks by payments received in it.
* `total` covers every customer, so it matches monthly sales and payments for the same months.
* With no dates, the range is the last six months, including this one. It can be at most 24 months.

## Customers to follow up

[List customers to follow up](https://docs.streamlinedpayments.com/api-reference/reports/list-customers-to-follow-up.md) lists customers with something more than 60 days past due, largest first. `total_receivables` and `over_60_total` cover every customer.

## Quiet customers

[List quiet customers](https://docs.streamlinedpayments.com/api-reference/reports/list-quiet-customers.md) finds regular customers you haven't invoiced in a while.

* A customer's usual gap is the median days between their invoices. It needs 3 invoices on at least two different days, and it's updated overnight.
* A customer is quiet after at least twice their usual gap with no invoice.
* A customer is left out once their last invoice is more than 18 months old, or more than three times their usual gap old if that's longer.
* Customers are ordered by what they bought over the last 12 months.

## Customer insights

[Get customer insights](https://docs.streamlinedpayments.com/api-reference/customers/get-customer-insights.md), and the customer group version, summarize how a customer pays and buys.

* `net_terms` is the customer's or group's own net terms, or your default when they have none. `days_past_terms` is how far `average_days_to_pay` runs past it.
* `payments_by_method` gives shares of the last 12 months' payments. Each method matches the `transaction_type` filter of the same name on [List transactions](https://docs.streamlinedpayments.com/api-reference/transactions/list-transactions.md).
* `failed_payment_count` counts failed attempts in the last 12 months. One declined charge across several invoices counts once.
* `spend_prior_12` is `null` until the first invoice is at least 24 months old, so a new customer isn't compared with an empty year.

## Reminders

[List customer reminders](https://docs.streamlinedpayments.com/api-reference/customers/list-customer-reminders.md), and the customer group version, list reminder emails sent for the customer's invoices.

* Copies sent to CC addresses are left out, so each reminder appears once.
* `open_count` is approximate. Some mail apps load the tracking image without anyone reading the email. It's `0` when the email bounced.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.