Get Usage Charges

Description

Retrieve a comprehensive list of all charges and payments for your account within a specified date range. This includes TURN server overage charges, account recharges/top-ups, and subscription renewals. The response provides detailed charge information along with a summary of totals by charge type.

GET

https://<appname>.metered.live/api/v2/payment/usage-charges?secretKey=<YOUR_SECRET_KEY>&startDate=<START_DATE>&endDate=<END_DATE>

<appname> - replace it with the name of your app.

Request

GET /api/v2/payment/usage-charges

Query Parameters

Parameter	Description	Data Type
secretKey	Required. The account secret key used for server-side authentication.	String
startDate	Required. Inclusive start date in YYYY-MM-DD format (UTC).	String
endDate	Required. Inclusive end date in YYYY-MM-DD format (UTC).	String

Rate limit: 4 requests per minute per app.

Responses

Success Response

HTTP Status: 200 OK

Body:

{
  "success": true,
  "data": [
    {
      "date": "2024-05-14",
      "type": "overage",
      "description": "TURN Server overage usage",
      "usage": 125.47,
      "unit": "GB",
      "unitCharge": 0.03,
      "total": 3.76,
      "status": "paid"
    },
    {
      "date": "2024-05-15",
      "type": "recharge",
      "description": "Automatic recharge (balance threshold reached)",
      "total": 100.00,
      "paymentMethod": "automatic",
      "status": "paid"
    },
    {
      "date": "2024-05-20",
      "type": "subscription_renewal",
      "description": "TURN Server Monthly subscription renewal",
      "planName": "Growth Plan (150GB)",
      "total": 299.00,
      "paymentMethod": "automatic",
      "status": "paid"
    }
  ],
  "summary": {
    "totalCharges": 402.76,
    "totalOverages": 3.76,
    "totalSubscriptions": 299.00,
    "totalRecharges": 100.00,
    "currency": "USD"
  },
  "period": {
    "startDate": "2024-10-01",
    "endDate": "2024-10-30"
  }
}

Field	Description	Data Type
success	Indicates if the request was successful.	Boolean
data[]	Array of charge records sorted by date in ascending order.	Array
data[].date	UTC date of the charge in YYYY-MM-DD format.	String
data[].type	Type of charge: overage, subscription_renewal, or recharge.	String
data[].description	Detailed description of the charge.	String
data[].usage	Amount of data used (only for overage charges).	Number
data[].unit	Unit of measurement for usage (only for overage charges).	String
data[].unitCharge	Price per unit (only for overage charges).	Number
data[].total	Total charge amount in dollars (rounded to 2 decimals).	Number
data[].planName	Name of the subscription plan (only for subscription renewals).	String
data[].paymentMethod	Payment method used: automatic, manual, or account_credit.	String
data[].status	Payment status: paid or pending	String
summary	Aggregated totals for all charges in the period.	Object
summary.totalCharges	Sum of all charges (overages + subscriptions + recharges).	Number
summary.totalOverages	Total amount of overage charges.	Number
summary.totalSubscriptions	Total amount of subscription renewal charges.	Number
summary.totalRecharges	Total amount of recharge payments.	Number
summary.currency	Currency code for all amounts	String
period	Date range for the returned data.	Object
period.startDate	Start date of the reporting period in YYYY-MM-DD format.	String
period.endDate	End date of the reporting period in YYYY-MM-DD format.	String

Error Responses

HTTP Status	Message	When it Happens
400 Bad Request	{"success": false, "message": "Please provide both startDate and endDate query parameters"}	Either startDate or endDate is missing.
400 Bad Request	{"success": false, "message": "Invalid date format. Please use ISO 8601 format (YYYY-MM-DD)"}	Date format is invalid.
400 Bad Request	{"success": false, "message": "End date must be on or after start date"}	endDate is before startDate.
400 Bad Request	{"message": "Invalid request. Not subscribed to any turn server plan"}	The app is not subscribed to a TURN Server plan.
400 Bad Request	{"message": "api not available under free plan"}	The app uses the free plan; upgrade to access this endpoint.
401 Unauthorized	{"success": false, "message": "Invalid secret key"}	Secret key is invalid or does not match any app.
500 Internal Server Error	{"success": false, "message": "Internal error occurred, contact support and provide the event id: <EVENT_ID>"}	An unexpected error occurred. Provide the event id to support.