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.

---

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.

---

Testing

For guidance on testing in Sandbox, see our Technical Overview guide.

---

Questions?

If you’re encountering any issues, please reach out to support@grailpay.com.

---