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

Retrieves bill history starting from the billing period of a specific bill

GetBillHistoryV3 Permissions: BillsAndBatches (View)
Use this endpoint when you have a bill ID and want to see the history around that bill’s billing period. Internally resolves the bill’s account and billing period, then returns the same data as GET /account/{accountId}/billHistory.

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 Unique numeric identifier of the bill whose billing period determines the history start point integer (int32) Required

Query Parameters

Name Description Type Required
numberOfYears Number of years of history to return, counting back from the bill’s 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
  }
]