Get Billing Summary for Merchant

Overview

GrailPay’s API delivers a straightforward and efficient method to retrieve a summary of all billed events for a specific merchant, providing comprehensive billing details to support seamless integration.

The API response features a summary array, where each object represents the totals for every unique billable event recorded for the merchant. Each object in this array includes the following:

• billable_event: The name of the billable event
• total: This is the total of all the occurrences of this event for the date range provided.
• total_occurrences: This is the total number of occurrences for this billable event.
• amount_per_occurrence: This is the amount charged per occurrence.

To use this endpoint, include the user UUID associated with the merchant as a path parameter. This unique identifier ensures the data returned is accurate and tailored to the merchant you are targeting.

Use Cases

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 in the response payload. Since onboarding, you have created 20 transactions for this merchant: 10 in January and 10 in February. Each transaction was created as a Standard ACH with a fee associated 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 return a JSON object containing a summary array that will have an object with the billable event name of Standard ACH, a total of 200 ( $2.00 ), total_occrrences equal to 20, and amount_per_occurrence of 10 ( $0.10 ).

Scenario 2 - Get Billing Events for Date Range

Using the same merchant and transaction data from the previous example, let’s say you want to retrieve only the billing events for January. You can achieve this by including the desired date range as query parameters in your GET request:
/3p/api/v2/merchants/abcd-efgh-ijkl-mnop/billing?start_date=2025-01-01&end_date=2025-01-31

The response will return a JSON object containing a summary array that will have an object with the billable event name of Standard ACH, a total of 100 ( $1.00 ), total_occrrences equal to 10, and amount_per_occurrence of 10 ( $0.10 ) to summary the billing events for January.

Endpoint

Optional Query Parameters

Response Object(s)

// When billing data is found for the supplied parameters
{
    "status": true,
    "message": "",
    "data": {
      "summary": [
        {
          "billable_event": "Standard ACH",
          "total": 1500,
          "total_occurrences": 150,
          "amount_per_occurrence": 10
        },
        {
          .....
        }
      ]
    },
    "errors": null,
    "error_code": null
}

// When no billing data can be found for the supplied parameters
{
    "status": true,
    "message": "",
    "data": {
      "summary": []
    },
    "errors": null,
    "error_code": null
}

Errors & Warnings

// When the uuid doesn't exist
// When uuid does not belong to merchant
// When the merchant associated with the uuid does not belong to the Auth Token supplied
{
    "status": false,
    "message": "The merchant was not found.",
    "data": [],
    "errors": []
}