> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.mercoa.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.mercoa.com/_mcp/server.

# Get Metrics

GET https://api.mercoa.com/entityGroup/{entityGroupId}/invoice-metrics

Get invoice metrics for an entity group with the given filters. Invoices will be grouped by currency. If none of excludePayables, excludeReceivables, payerId, vendorId, or invoiceId status filters are provided, excludeReceivables will be set to true.

Reference: https://docs.mercoa.com/embedded-ap-ar/api-reference/entity-group/invoice/metrics

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `entityGroupId` (string, required) — Entity Group ID or Entity Group ForeignID

### Query parameters

- `search` (string, optional) — Find invoices by vendor name, invoice number, check number, or amount. Partial matches are supported.
- `excludePayables` (boolean, optional) — Only return invoices that are not payable by the entity. This will return only invoices that are receivable by the entity.
- `excludeReceivables` (boolean, optional) — Only return invoices that are not receivable by the entity. This will return only invoices that are payable by the entity.
- `returnByDate` (enum, optional) — Return invoice metrics grouped by date.
  - Allowed values: `CREATION_DATE`, `DUE_DATE`, `INVOICE_DATE`, `DEDUCTION_DATE`
- `returnByDateFrequency` (enum, optional) — Return invoice metrics grouped by date. Defaults to daily.
  - Allowed values: `DAILY`, `WEEKLY`, `MONTHLY`, `YEARLY`
- `groupBy` (enum, optional) — Return invoice metrics grouped by.
  - Allowed values: `STATUS`
- `payerId` (string, optional) — Filter invoices by payer ID.
- `vendorId` (string, optional) — Filter invoices by vendor ID.
- `approverId` (string, optional) — Filter invoices by assigned approver user ID.
- `approverCount` (string, optional) — Filter invoices by the number of approvers. Use exact number (e.g., 3) or range (e.g., ">3", "\<5", ">=2", "\<=4").
- `invoiceId` (string, optional) — Filter invoices by invoice ID or invoice foreign ID.
- `status` (enum, optional) — Invoice status to filter on
  - Allowed values: `UNASSIGNED`, `DRAFT`, `NEW`, `APPROVED`, `SCHEDULED`, `PENDING`, `PAID`, `ARCHIVED`, `REFUSED`, `CANCELED`, `FAILED`
- `startDate` (datetime, optional) — Start date filter. Defaults to CREATED_AT unless specified the dateType is specified
- `endDate` (datetime, optional) — End date filter. Defaults to CREATED_AT unless specified the dateType is specified
- `dateType` (enum, optional) — Type of date to filter by if startDate and endDate filters are provided. Defaults to CREATED_AT.
  - Allowed values: `INVOICE_DATE`, `DEDUCTION_DATE`, `DUE_DATE`, `SETTLEMENT_DATE`, `CREATED_AT`, `UPDATED_AT`
- `currency` (enum, optional) — Currency to filter on
  - Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `CNY`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`

## Response

### 200

- `list of object`
  - `totalAmount` (double, required)
  - `totalCount` (integer, required)
  - `averageAmount` (double, required)
  - `currency` (enum, required)
    - Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `CNY`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`
  - `group` (list of map from string to string, optional) — If groupBy is provided, this will be the group by value.
  - `dates` (map from string to object, optional)
    - `date` (datetime, required)
    - `totalAmount` (double, required)
    - `totalCount` (integer, required)
    - `averageAmount` (double, required)
    - `currency` (enum, required)
      - Allowed values: `AED`, `AFN`, `ALL`, `AMD`, `ANG`, `AOA`, `ARS`, `AUD`, `AWG`, `AZN`, `BAM`, `BBD`, `BDT`, `BGN`, `BHD`, `BIF`, `BMD`, `BND`, `BOB`, `BOV`, `BRL`, `BSD`, `BTN`, `BWP`, `BYN`, `BZD`, `CAD`, `CDF`, `CHE`, `CHF`, `CHW`, `CLF`, `CLP`, `COP`, `COU`, `CRC`, `CUC`, `CUP`, `CVE`, `CZK`, `DJF`, `DKK`, `DOP`, `DZD`, `EGP`, `ERN`, `ETB`, `EUR`, `FJD`, `FKP`, `GBP`, `GEL`, `GHS`, `GIP`, `GMD`, `GNF`, `GTQ`, `GYD`, `HKD`, `HNL`, `HTG`, `HUF`, `IDR`, `ILS`, `INR`, `IQD`, `IRR`, `ISK`, `JMD`, `JOD`, `JPY`, `KES`, `KGS`, `KHR`, `KMF`, `KPW`, `KRW`, `KWD`, `KYD`, `KZT`, `LAK`, `LBP`, `LKR`, `LRD`, `LSL`, `LYD`, `MAD`, `MDL`, `MGA`, `MKD`, `MMK`, `MNT`, `MOP`, `MRU`, `MUR`, `MVR`, `MWK`, `MXN`, `MXV`, `MYR`, `MZN`, `NAD`, `NGN`, `NIO`, `NOK`, `NPR`, `NZD`, `OMR`, `PAB`, `PEN`, `PGK`, `PHP`, `PKR`, `PLN`, `PYG`, `QAR`, `RON`, `RSD`, `CNY`, `RUB`, `RWF`, `SAR`, `SBD`, `SCR`, `SDG`, `SEK`, `SGD`, `SHP`, `SLE`, `SLL`, `SOS`, `SRD`, `SSP`, `STN`, `SVC`, `SYP`, `SZL`, `THB`, `TJS`, `TMT`, `TND`, `TOP`, `TRY`, `TTD`, `TWD`, `TZS`, `UAH`, `UGX`, `USD`, `USN`, `UYI`, `UYU`, `UYW`, `UZS`, `VED`, `VES`, `VND`, `VUV`, `WST`, `XAF`, `XAG`, `XAU`, `XBA`, `XBB`, `XBC`, `XBD`, `XCD`, `XDR`, `XOF`, `XPD`, `XPF`, `XPT`, `XSU`, `XTS`, `XUA`, `XXX`, `YER`, `ZAR`, `ZMW`, `ZWL`
    - `group` (list of map from string to string, optional) — If groupBy is provided, this will be the group by value.

## Errors

### 400 Bad Request

- `errorName` ("BadRequest", required)
- `content` (string, required)

### 401 Unauthorized

- `errorName` ("Unauthorized", required)
- `content` (string, required)

### 403 Forbidden

- `errorName` ("Forbidden", required)
- `content` (string, required)

### 404 Not Found

- `errorName` ("NotFound", required)
- `content` (string, required)

### 409 Conflict

- `errorName` ("Conflict", required)
- `content` (string, required)

### 500 Internal Server Error

- `errorName` ("InternalServerError", required)
- `content` (string, required)

### 501 Unimplemented

- `errorName` ("Unimplemented", required)
- `content` (string, required)

## Examples

**Response**

```json
[
  {
    "totalAmount": 1000,
    "totalCount": 10,
    "averageAmount": 100,
    "currency": "USD",
    "dates": {
      "2021-01-01T00:00:00Z": {
        "date": "2021-01-01T00:00:00Z",
        "totalAmount": 100,
        "totalCount": 1,
        "averageAmount": 100,
        "currency": "USD"
      },
      "2021-01-02T00:00:00Z": {
        "date": "2021-01-02T00:00:00Z",
        "totalAmount": 200,
        "totalCount": 2,
        "averageAmount": 100,
        "currency": "USD"
      },
      "2021-01-03T00:00:00Z": {
        "date": "2021-01-03T00:00:00Z",
        "totalAmount": 400,
        "totalCount": 2,
        "averageAmount": 200,
        "currency": "USD"
      }
    }
  }
]
```

**SDK Code**

```python Default
import requests

url = "https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics"

querystring = {"returnByDate":"CREATION_DATE","excludeReceivables":"true","startDate":"2021-01-01T00:00:00.000Z","endDate":"2021-01-31T23:59:59.999Z","currency":"USD","status":"NEW"}

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers, params=querystring)

print(response.json())
```

```typescript Default
import { MercoaClient } from "@mercoa/javascript";

const client = new MercoaClient({ token: "YOUR_TOKEN" });
await client.entityGroup.invoice.metrics("entg_8545a84e-a45f-41bf-bdf1-33b42a55812c", {
    returnByDate: "CREATION_DATE",
    excludeReceivables: true,
    startDate: new Date("2021-01-01T00:00:00.000Z"),
    endDate: new Date("2021-01-31T23:59:59.999Z"),
    currency: "USD",
    status: "NEW"
});

```

```go Default
package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics?returnByDate=CREATION_DATE&excludeReceivables=true&startDate=2021-01-01T00%3A00%3A00.000Z&endDate=2021-01-31T23%3A59%3A59.999Z&currency=USD&status=NEW"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Default
require 'uri'
require 'net/http'

url = URI("https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics?returnByDate=CREATION_DATE&excludeReceivables=true&startDate=2021-01-01T00%3A00%3A00.000Z&endDate=2021-01-31T23%3A59%3A59.999Z&currency=USD&status=NEW")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body
```

```java Default
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.get("https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics?returnByDate=CREATION_DATE&excludeReceivables=true&startDate=2021-01-01T00%3A00%3A00.000Z&endDate=2021-01-31T23%3A59%3A59.999Z&currency=USD&status=NEW")
  .header("Authorization", "Bearer <token>")
  .asString();
```

```php Default
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('GET', 'https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics?returnByDate=CREATION_DATE&excludeReceivables=true&startDate=2021-01-01T00%3A00%3A00.000Z&endDate=2021-01-31T23%3A59%3A59.999Z&currency=USD&status=NEW', [
  'headers' => [
    'Authorization' => 'Bearer <token>',
  ],
]);

echo $response->getBody();
```

```csharp Default
using RestSharp;

var client = new RestClient("https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics?returnByDate=CREATION_DATE&excludeReceivables=true&startDate=2021-01-01T00%3A00%3A00.000Z&endDate=2021-01-31T23%3A59%3A59.999Z&currency=USD&status=NEW");
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer <token>");
IRestResponse response = client.Execute(request);
```

```swift Default
import Foundation

let headers = ["Authorization": "Bearer <token>"]

let request = NSMutableURLRequest(url: NSURL(string: "https://api.mercoa.com/entityGroup/entg_8545a84e-a45f-41bf-bdf1-33b42a55812c/invoice-metrics?returnByDate=CREATION_DATE&excludeReceivables=true&startDate=2021-01-01T00%3A00%3A00.000Z&endDate=2021-01-31T23%3A59%3A59.999Z&currency=USD&status=NEW")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "GET"
request.allHTTPHeaderFields = headers

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```