GET /api/v3/account/{accountId}/billHistory

Retrieves bill history for an account starting at a specific billing period

GetAccountBillHistoryV3 Permissions: BillsAndBatches (View)
Use this endpoint to get historical bills for an account over a range of years, starting from a given billing period. Useful for displaying bill trends and comparisons on the bill entry/view screens.

Request Headers

Header Value Required Description
ECI-ApiKey string Yes Your API key. See Authentication.
Content-Type application/json Yes All requests must specify JSON content type.

Path Parameters

Name Description Type Required
accountId Unique numeric identifier of the account integer (int32) Required

Query Parameters

Name Description Type Required
billingPeriod Required billing period in YYYYMM integer format (e.g., 202301 for January 2023). Must be between years 1900 and 2100 integer (int32) Optional
numberOfYears Number of years of history to return, counting back from the billing period. Defaults to 5 integer (int32) Optional
includeVoid When true, includes voided bills in the history. When false (default), voided bills are excluded boolean Optional
includeAccrual When true, includes accrual bills in the history. When false (default), accrual bills are excluded boolean Optional

Responses

200 OK The request succeeded and the response body contains the requested data.

Response Body Parameters

Array of:

BillHistoryResponse
Property Description Type
accrual The bill’s accrual indicator boolean
beginDate The bill’s begin date string (date-time)
billAccountMeters The bill’s account-meter summaries BillAccountMeterChild[]
BillAccountMeterChild properties
Property Description Type
accountId The bill-account-meter’s account id integer (int32)
directCost The bill-account-meter’s direct cost number (double)
directCostPerDay The bill-account-meter’s direct cost per day number (double)
directCostUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
meterId The bill-account-meter’s meter id integer (int32)
nativeActualDemand The bill-account-meter’s native actual demand number (double)
nativeActualDemandUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
nativeBilledDemand The bill-account-meter’s native billed demand number (double)
nativeBilledDemandUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
nativeUse The bill-account-meter’s native use number (double)
nativeUsePerDay The bill-account-meter’s native use per day number (double)
nativeUseUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
nativeUseUnitCost The bill-account-meter’s native use unit cost number (double)
billId The bill’s bill id integer (int32)
billingPeriod The bill’s billing period integer (int32)
createdDate The bill’s created date string (date-time)
dueDate The bill’s due date string (date-time)
endDate The bill’s end date string (date-time)
estimated Indicates if the bill is estimated or not boolean
invoiceNumber The bill’s invoice number string
statementDate The bill’s statement date string (date-time)
totalCost The bill’s total cost number (double)
totalCostUnit UnitChild
UnitChild properties
Property Description Type
unitCode The unit code string
unitId The unit identifier integer (int32)
unitInfo The unit info string
void The bill’s void indicator boolean
Example Response application/json 
[
  {    "accrual": false,    "beginDate": "2026-06-29",    "billAccountMeters": [
      {      "accountId": 1,      "directCost": 1.0,      "directCostPerDay": 1.0,      "directCostUnit": {},      "meterId": 1,      "nativeActualDemand": 1.0,      "nativeActualDemandUnit": {},      "nativeBilledDemand": 1.0,      "nativeBilledDemandUnit": {},      "nativeUse": 1.0,      "nativeUsePerDay": 1.0,      "nativeUseUnit": {},      "nativeUseUnitCost": 1.0
    }
    ],    "billId": 1,    "billingPeriod": 1,    "createdDate": "2026-06-29",    "dueDate": "2026-06-29",    "endDate": "2026-06-29",    "estimated": false,    "invoiceNumber": "string",    "statementDate": "2026-06-29",    "totalCost": 1.0,    "totalCostUnit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "void": false
  }
]