# Manage Billing

## Overview

The GrailPay Payments API exposes billing through two read endpoints: a summary of charges grouped by billable event,
and the individual billing events behind those totals. Each billing event corresponds to a distinct action that
triggered a charge — such as a transaction, payout, return, or bank account validation — and represents usage of the
GrailPay platform tied to specific API activity. This is particularly useful for vendors or partners who need to track
usage, audit charges, or generate reports for invoicing and financial reconciliation.

- **Get Billing Summary** — totals per billable event, grouped by the merchant, business, or person they are
  attributed to
- **Get Billing Items** — the individual billable events behind those totals, each with the source that triggered it

Both endpoints are scoped to the authenticated vendor or processor and accept the same entity and date filters, so a
summary can be reconciled against the items that make it up by reusing the same query.

---

## Get Billing Summary

Use this endpoint to retrieve billing totals grouped by billable event. Each row in the response is attributed to an
entity — the merchant or business when one exists, otherwise the billing person — and lists, for every billable event
charged to that entity, the amount per occurrence, the number of occurrences, and the total, along with a total across
all of that entity's events. Amounts are in cents.

Results can be narrowed to a single merchant or billing user by UUID, to an inclusive date range, to one billable
event, to merchants matching a partial name, or to a processor MID. The response is paginated with one entity per row,
so a vendor with many merchants receives them across pages.

This is especially useful for:

- Reconciling an invoice against the charges that make it up
- Tracking a merchant's usage across a billing cycle
- Reporting on which billable events drive cost
- Comparing usage between two date ranges

For full request and response schemas, including available filters, refer to the
[Get Billing Summary OpenAPI Documentation](/api/payments/#tag/billing/GET/api/v3/billing/summary).

---

## Get Billing Items

Use this endpoint to retrieve the individual billable events behind the summary, one record per charge. Each item
carries when it was billed, its amount in cents, the billable event it was charged as, the entity it is attributed to,
and the source that triggered it — the transaction, payout, or other record that produced the charge — so a charge can
be traced back to the API activity that caused it.

Results are paginated and can be sorted by created date or amount in either direction. The same entity, billable event,
and processor MID filters as the summary apply, together with an inclusive date range.

:::note
Unlike the summary, the items endpoint always applies a date range. When the start or end date is omitted, it defaults
to the first day of the current month and today, respectively. To retrieve events from earlier months, pass the range
explicitly.
:::

This is especially useful for:

- Auditing an individual charge back to the transaction, payout, or validation that triggered it
- Reconciling a summary total against the events that make it up
- Exporting line-item usage for a merchant within a billing cycle
- Investigating unexpected or disputed charges

For full request and response schemas, including available filters and sort options, refer to the
[Get Billing Items OpenAPI Documentation](/api/payments/#tag/billing/GET/api/v3/billing/items).

---

## Testing

For guidance on testing in Sandbox, see our [Technical Overview](/docs/technical/overview#testing) guide.

---

## Questions?

If you're encountering any issues, please reach out to [support@grailpay.com](mailto:support@grailpay.com).

---