Get monthly charges summary

GET 
/charges_summary

Retrieve a summary of monthly charges for a specified date range. The date range cannot exceed 31 days to prevent large queries that could cause timeouts.

Query Parameters

start_date daterequired

Start date for the charges summary in ISO date format (YYYY-MM-DD)

end_date daterequired

End date for the charges summary in ISO date format (YYYY-MM-DD). The interval between start_date and end_date cannot exceed 31 days.

200: Monthly charges summary

application/json

• Schema
• Example (from schema)

Schema

data

object

required

user_id stringrequired

User identifier

start_date daterequired

Start date of the summary period

end_date daterequired

End date of the summary period

user_email emailrequired

User email address

currency stringrequired

Currency code

summary

object

required

lines

object[]

required

List of charge summary lines

Array [

oneOf

• ComparativeLine
• SimpleLine

type stringrequired

Possible values: [comparative]

name stringrequired

Service name

alias stringrequired

Service alias

new_this_month

object

required

quantity integerrequired

Number of items

mrc stringrequired

Monthly recurring charge amount as decimal string

otc stringnullable

One-time charge amount as decimal string

existing_this_month

object

required

quantity integerrequired

Number of items

mrc stringrequired

Monthly recurring charge amount as decimal string

otc stringnullable

One-time charge amount as decimal string

type stringrequired

Possible values: [simple]

name stringrequired

Service name

alias stringrequired

Service alias

quantity integerrequired

Number of items

amount stringrequired

Total amount as decimal string

]

List of charge summary lines

adjustments

object[]

required

List of billing adjustments

Array [

amount stringrequired

Adjustment amount as decimal string

description stringrequired

Description of the adjustment

event_date daterequired

Date when the adjustment occurred

]

List of billing adjustments

total

object

required

new_mrc stringrequired

Total new monthly recurring charges as decimal string

new_otc stringrequired

Total new one-time charges as decimal string

existing_mrc stringrequired

Total existing monthly recurring charges as decimal string

other stringrequired

Other charges as decimal string

credits stringrequired

Total credits as decimal string

ledger_adjustments stringrequired

Ledger adjustments as decimal string

grand_total stringrequired

Grand total of all charges as decimal string

{
  "data": {
    "user_id": "0db0b4aa-a83d-4d4f-ad9b-3ba7c1ac2ce8",
    "start_date": "2025-05-01",
    "end_date": "2025-06-01",
    "user_email": "user@example.com",
    "currency": "USD",
    "summary": {
      "lines": [
        {},
        {}
      ],
      "adjustments": [
        {
          "amount": "-10.00",
          "description": "Credit for service outage",
          "event_date": "2025-05-15"
        }
      ]
    },
    "total": {
      "new_mrc": "50.00",
      "new_otc": "25.00",
      "existing_mrc": "100.00",
      "other": "10.00",
      "credits": "-5.00",
      "ledger_adjustments": "0.00",
      "grand_total": "180.00"
    }
  }
}

400: Bad request - invalid date range or parameters

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

default: Unexpected error

application/json

• Schema
• Example (from schema)

Schema

errors

Error[]

Array [

code integerrequired

title stringrequired

detail string

source

object

pointer json-pointer

JSON pointer (RFC6901) to the offending entity.

parameter string

Indicates which query parameter caused the error.

meta object

]

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

Request samples

• cURL

---

curl -L 'https://api.telnyx.com/v2/charges_summary' \
-H 'Accept: application/json' \
-H 'Authorization: Bearer <TOKEN>'

Response samples

• 200
• 400
• default

---

{
  "data": {
    "user_id": "0db0b4aa-a83d-4d4f-ad9b-3ba7c1ac2ce8",
    "start_date": "2025-05-01",
    "end_date": "2025-06-01",
    "user_email": "user@example.com",
    "currency": "USD",
    "summary": {
      "lines": [
        {},
        {}
      ],
      "adjustments": [
        {
          "amount": "-10.00",
          "description": "Credit for service outage",
          "event_date": "2025-05-15"
        }
      ]
    },
    "total": {
      "new_mrc": "50.00",
      "new_otc": "25.00",
      "existing_mrc": "100.00",
      "other": "10.00",
      "credits": "-5.00",
      "ledger_adjustments": "0.00",
      "grand_total": "180.00"
    }
  }
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}

{
  "errors": [
    {
      "code": "string",
      "title": "string",
      "detail": "string",
      "source": {
        "pointer": "string",
        "parameter": "string"
      },
      "meta": {}
    }
  ]
}