> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ach.netevia.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Get Merchant Billing Summary

> Fetch a summary of billed events for a merchant.

### Overview

Our ACH 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](/docs/onboarding-a-business). 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

GET   **/3p/api/v2/merchants/\{uuid}/billing**

### Optional Query Parameters

| Parameter       | Value                         |
| --------------- | ----------------------------- |
| **start\_date** | string ( format: yyyy-mm-dd ) |
| **end\_date**   | string ( format: yyyy-mm-dd ) |

***

### Response Object(s)

<CodeGroup>
  ```json Success (200) theme={"system"}
  // 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
  }
  ```

  ```json Success (200) - No Billing Data Found theme={"system"}
  // When no billing data can be found for the supplied parameters
  {
      "status": true,
      "message": "",
      "data": {
        "summary": []
      },
      "errors": null,
      "error_code": null
  }
  ```
</CodeGroup>

***

### Errors & Warnings

<CodeGroup>
  ```json Error (404) theme={"system"}
  // 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": []
  }
  ```
</CodeGroup>