Skip to main content

​
Overview

The Get Merchant Billing Summary endpoint allows you to retrieve a list of billing events associated with a specific business (also referred to as a merchant). This is particularly useful for vendors or partners who need to track usage, audit charges, or generate reports for invoicing and financial reconciliation. Each billing item returned corresponds to a distinct event that triggered a charge—such as a transaction, payout, refund, or bank account validation. These events represent usage of the GrailPay platform and are tied to specific API activity for the given merchant. You can filter results by date range to isolate events within a specific billing cycle or time window. The endpoint is also paginated to efficiently return large data sets for merchants with high transaction volume. For complete request and response schema details, refer to the OpenAPI Documentation

​
Use Cases

Below are a couple of common scenarios where you might use this endpoint.

​
Scenario 1 - Get All Billing Events

Let’s assume you have onboarded a new merchant, Acme Tool Company, using the Onboard a Merchant API. As part of the onboarding process, you received a UUID of abcd-efgh-ijkl-mnop. Since onboarding, you’ve created 20 transactions for this merchant: 10 in January and 10 in February. Each transaction is a Standard ACH with a billing rate of $0.10 per event. To retrieve all billing events for this merchant, simply make a GET request to: /3p/api/v2/merchants/abcd-efgh-ijkl-mnop/billing The response will include a summary array containing a single object with:
  • billable_event: Standard ACH
  • total_occurrences: 20
  • amount_per_occurrence: 10 (cents)
  • total: 200 (cents = $2.00)

​
Scenario 2 - Get Billing Events for Date Range

Using the same merchant and transaction data, suppose you only want to retrieve billing events for January. You can pass a date range in the query parameters: /3p/api/v2/merchants/abcd-efgh-ijkl-mnop/billing?start_date=2025-01-01&end_date=2025-01-31 The response will include a summary array containing a single object with:
  • billable_event: Standard ACH
  • total_occurrences: 10
  • amount_per_occurrence: 10 (cents)
  • total: 100 (cents = $1.00)

​
Testing

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

​
Questions?

If you’re encountering any issues, please reach out to [email protected].