Get Billing Items By Merchant

Overview

GrailPay’s API provides a simple and efficient way to retrieve all billing records for a specific merchant, offering comprehensive billing information to support your integration needs. The response includes a billings array, where each object contains:

• event_name: The name of the billable event.
• amount: The billed amount for the event, returned in cents to ensure precision. ( If you need to display dollar amounts, you will need to convert this value to dollars as part of your integration. )
• created_at: The timestamp when the event occurred.

The response also includes a pagination object that provides the following based on the query parameters supplied:

• current_page: The page number of the current response.
• total_pages: The total number of pages available.
• total_items: The total number of billable events.
• per_page: The number of items displayed per page.

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.

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 billings array with 20 objects, where each object represents a billable event corresponding to a transaction.

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 billings array with 10 objects, each representing the billable event for each transaction that occurred in January.

Endpoint

Optional Query Parameters

Response Object(s)

// When billing data is found for the supplied parameters
{
    "status": true,
    "message": null,
    "data": {
      "billings": [
        {
          "event_name": "Bank Link Widget Links",
          "amount": 10,
          "created_at": "..."
        },
        {
          .....
        },
      ],
      "pagination": {
          "current_page": 1,
          "total_pages": 2,
          "total_items": 15,
          "per_page": 10
      }
    },
    "errors": null,
    "error_code": null
}

// When no billing data can be found for the supplied parameters
{
    "status": true,
    "message": null,
    "data": {
      "billings": [],
      "pagination": {
          "current_page": 1,
          "total_pages": 0,
          "total_items": 0,
          "per_page": 10
      }
    },
    "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": []
}