POST /api/v3/bill

Creates a new bill with line items and runs bill audits

CreateBillV3 Permissions: BillsAndBatches (Create)
Use this endpoint to create a bill. The bill is audited after creation. If any audits fail, the bill is flagged. If a failed audit’s setting is “Fail and Hold”, the bill is held from export. Use saveAsResolved=true to auto-resolve any failed audits and release the bill for export.

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, including the request body.

Query Parameters

Name Description Type Required
saveAsResolved When true, any failed audits are automatically marked as resolved. When false (default), failed audits leave the bill flagged boolean Optional
comment Optional comment explaining why audits are being auto-resolved. Only applies when saveAsResolved is true string Optional

Request Body

BillCreate
Property Description Type
accountBodyLines The account line items BillAccountBodyLineCreate[]
BillAccountBodyLineCreate properties
Property Description Type
caption The caption Required Must be between 0 and 100 characters string
cost The cost attributed to the line item Required when CostUnitId is set number (double)
costUnitId The bodyline’s cost unit of measure for this Required when Cost is set integer (int32)
observationTypeId The bodyline’s observation type Required integer (int32)
specialChargeId The bodyline’s special charge (SingleLine) id, if applicable integer (int32)
accountId The bill’s account Required integer (int32)
accountPeriod The bill’s accounting period Depending on your settings you can have up to 13 accounting periods Must be between 190001 and 209913 integer (int32)
batchId Existing batch id to add this bill to, if applicable. If batchId is provided, it needs to be an open batch. If the batch is another user’s open batch, the permission “Bills and Batches:Manage” is required. If NOT provided, and current user has multiple open batches, the API will return an error. integer (int32)
beginDate The bill’s begin date Required Must be between 1899-12-31 and 3000-01-01 string (date-time)
billingPeriod The bill’s billing period Required Must be between 190001 and 209912 integer (int32)
controlCode The bill’s control code Must be between 0 and 255 characters string
dueDate The date and time the bill is due Must be between 1899-12-31 and 3000-01-01 string (date-time)
endDate The bill’s end date Required Must be greater than BeginDate Must be between 1899-12-31 and 3000-01-01 string (date-time)
estimated Indicates if the bill is estimated boolean
invoiceNumber The bill’s invoice number Must be between 0 and 32 characters string
manualEntry The bill’s entry method. True = manual entry, false = automatic entry. Required boolean
meters The meters with line items BillMeterCreate[]
BillMeterCreate properties
Property Description Type
bodyLines Required Cannot be Empty BillMeterBodyLineCreate[]
BillMeterBodyLineCreate properties
Property Description Type
caption The caption Required Must be between 0 and 100 characters string
cost The cost attributed to the line item Required when CostUnitId is set number (double)
costUnitId The bodyline’s cost unit of measure for this Required when Cost is set integer (int32)
observationTypeId The bodyline’s observation type Required integer (int32)
value The line item’s value Required when ValueUnitId is set number (double)
valueUnitId The bodyline’s unit of measure Required when Value is set integer (int32)
meterId The meter the line items are assigned to Required integer (int32)
nextReading The date and time the of the next reading Must be between 1899-12-31 and 3000-01-01 string (date-time)
note The bill note string
statementDate The date and time of the bill statement Must be between 1899-12-31 and 3000-01-01 string (date-time)
Example Request Body application/json 
{  "accountBodyLines": [
    {    "caption": "string",    "cost": 1.0,    "costUnitId": 1,    "observationTypeId": 1,    "specialChargeId": 1
  }
  ],  "accountId": 1,  "accountPeriod": 1,  "batchId": 1,  "beginDate": "2026-06-29",  "billingPeriod": 1,  "controlCode": "string",  "dueDate": "2026-06-29",  "endDate": "2026-06-29",  "estimated": false,  "invoiceNumber": "string",  "manualEntry": false,  "meters": [
    {    "bodyLines": [
      {      "caption": "string",      "cost": 1.0,      "costUnitId": 1,      "observationTypeId": 1,      "value": 1.0,      "valueUnitId": 1
    }
    ],    "meterId": 1
  }
  ],  "nextReading": "2026-06-29",  "note": "string",  "statementDate": "2026-06-29"
}

Responses

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

Response Body Parameters

BillIdResponse
Property Description Type
billId The bill identifier integer (int32)
Example Response application/json 
{  "billId": 1
}
400 Bad Request The request was malformed or contains invalid parameters. Check the request body and query parameters.