GET /api/v3/bill/{billId}/billHistory

Retrieves bill history from starting at the billId billing period

GetBillHistoryV3 Permissions: BillsAndBatches (View)

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
billId billId to get bill history for integer (int32) Required

Query Parameters

Name Description Type Required
numberOfYears optional: Number of years of history to return. Defaults to 5 integer (int32) Optional
includeVoid optional: Should voided bills be included. Defaults to false boolean Optional
includeAccrual optional: Should accrual bills be included. Defaults to false 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-03-30",    "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-03-30",    "dueDate": "2026-03-30",    "endDate": "2026-03-30",    "estimated": false,    "invoiceNumber": "string",    "statementDate": "2026-03-30",    "totalCost": 1.0,    "totalCostUnit": {      "unitCode": "string",      "unitId": 1,      "unitInfo": "string"
    },    "void": false
  }
]