POST /api/v3/rate/{rateId}/version

Create a rate schedule version

CreateRateVersionV3 Permissions: RateSchedules (Edit)

Allows the user to create a new version for a rate schedule for use in chargeback scenarios where use or demand cost for calculated bills must be created from a predefined unit cost.

Validation

Account and meter line items
- Subtotal calculation type is not supported

Other Remarks

Inserting a rate version before an existing version will set the new version’s end date to the effective date of the subsequent version.
Null values are acceptable for use and demand unit costs. However, for chargeback bills to calculate correctly, these values must be provided.

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.

Path Parameters

Name	Description	Type	Required
rateId	Unique identifier of the rate schedule to receive the new version	integer (int32)	Required

Request Body

RateVersionRequest

Property

Description

Type

accountLineItems

Cost bodylines for the account Required (defined)

GenericBodylineRequest[]

GenericBodylineRequest properties

Property	Description	Type
calculationType	The calculation type for the line item One of ‘Fixed’, ‘Percentage’, ‘Subtotal’ Required (defined)	string
caption	The caption Must be between 0 and 100 characters Required when CalculationType is set to Fixed, or Percentage, or Subtotal	string
observationTypeId	The observation type For account body lines the observation type must be a charge type Required when CalculationType is set to Fixed, or Percentage	integer (int32)
value	The bodyline’s value When CalculationType is Fixed. Precision max is 2 When CalculationType is Percentage. Precision max is 8 Required when CalculationType is set to Fixed, or Percentage	number (double)

demandUnitCost

Unit cost for the demand Required when DemandUnitID is set Max scale of 8 NULL Valid

number (double)

demandUnitId

Demand unit ID Required when DemandUnitCost is set

integer (int32)

effectiveDate

Effective date for the version Required Must be between 1899-12-31 and 3000-01-01

string (date-time)

meterLineItems

Cost bodylines for the meter Required (defined)

GenericBodylineRequest[]

GenericBodylineRequest properties

Property	Description	Type
calculationType	The calculation type for the line item One of ‘Fixed’, ‘Percentage’, ‘Subtotal’ Required (defined)	string
caption	The caption Must be between 0 and 100 characters Required when CalculationType is set to Fixed, or Percentage, or Subtotal	string
observationTypeId	The observation type For account body lines the observation type must be a charge type Required when CalculationType is set to Fixed, or Percentage	integer (int32)
value	The bodyline’s value When CalculationType is Fixed. Precision max is 2 When CalculationType is Percentage. Precision max is 8 Required when CalculationType is set to Fixed, or Percentage	number (double)

note

Note for the version Must be between 0 and 255 characters Required (defined)

string

udfs

List of user defined/custom fields and values for this version If the Udfs list is null or empty no values are assigned If a udf is omitted no value is assigned to that udf To remove a value from an existing Udf, pass in the UdfId and set the Value to null Required (defined)

UDFValue[]

UDFValue properties

Property	Description	Type
udfId	udfId of the UDF being edited Required (defined)	integer (int32)
value	Required (defined)	string

useUnitCost

Unit cost for the use Required when UseUnitID is set Max scale of 8 NULL Valid

number (double)

useUnitId

Use unit ID Required when UseUnitCost is set

integer (int32)

Example Request Body application/json

{  "accountLineItems": [
    {    "calculationType": "string",    "caption": "string",    "observationTypeId": 1,    "value": 1.0
  }
  ],  "demandUnitCost": 1.0,  "demandUnitId": 1,  "effectiveDate": "2026-03-30",  "meterLineItems": [
    {    "calculationType": "string",    "caption": "string",    "observationTypeId": 1,    "value": 1.0
  }
  ],  "note": "string",  "udfs": [
    {    "udfId": 1,    "value": "string"
  }
  ],  "useUnitCost": 1.0,  "useUnitId": 1
}

Responses

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

Response Body Parameters

RateVersionResponse

Property

Description

Type

accountLineItems

Cost bodylines for the account

GenericBodylineResponse[]

GenericBodylineResponse properties

Property

Description

Type

calculationType

The calculation type for the line item. Either “Fixed”, “Percentage”, or “Subtotal”

string

caption

The caption

string

observationType

ObservationTypeChild

ObservationTypeChild properties

Property	Description	Type
credit	Indicates the type of credit for the observation type. Possible values include: 1 (Credit), 2 (Debit), 3 (Ignore)	integer (int32)
nounCode	The observation type’s noun code	string
nounId	The identifier for the observation type’s noun	integer (int32)
observationTypeCode	The observation type code	string
observationTypeId	The observation type identifier	integer (int32)
observationTypeInfo	The observation type info	string

value

The bodyline’s value

number (double)

beginDate

Begin date for the version

string (date-time)

costUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

createdBy

UserChild

UserChild properties

Property	Description	Type
fullName	The user’s full name	string
userCode	The user code	string
userId	The user identifier	integer (int32)

createdDate

Created date

string (date-time)

demandUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

demandUnitCost

Unit cost for the demand

number (double)

endDate

End date for the version

string (date-time)

meterLineItems

Cost bodylines for the meter

GenericBodylineResponse[]

GenericBodylineResponse properties

Property

Description

Type

calculationType

The calculation type for the line item. Either “Fixed”, “Percentage”, or “Subtotal”

string

caption

The caption

string

observationType

ObservationTypeChild

ObservationTypeChild properties

Property	Description	Type
credit	Indicates the type of credit for the observation type. Possible values include: 1 (Credit), 2 (Debit), 3 (Ignore)	integer (int32)
nounCode	The observation type’s noun code	string
nounId	The identifier for the observation type’s noun	integer (int32)
observationTypeCode	The observation type code	string
observationTypeId	The observation type identifier	integer (int32)
observationTypeInfo	The observation type info	string

value

The bodyline’s value

number (double)

modifiedBy

UserChild

UserChild properties

Property	Description	Type
fullName	The user’s full name	string
userCode	The user code	string
userId	The user identifier	integer (int32)

modifiedDate

Last modified date

string (date-time)

note

Note

string

udfs

List of user defined/custom fields and values for this version

UDFFieldChild[]

UDFFieldChild properties

Property

Description

Type

dataType

DataTypeResponse

DataTypeResponse properties

Property	Description	Type
dataTypeCode	Required (defined)	string
dataTypeId	Required (defined)	integer (int32)
dataTypeInfo	Required (defined)	string

description

Required (defined)

string

displayOrder

Required (defined)

integer (int32)

important

Required (defined)

boolean

name

Required (defined)

string

udfId

Required (defined)

integer (int32)

udfSelectValues

Required (defined)

UDFSelectValueEntityResponse[]

UDFSelectValueEntityResponse properties

Property	Description	Type
displayOrder	Required (defined)	integer (int32)
udfSelectValueId	Required (defined)	integer (int32)
value	Required (defined)	string

value

Required (defined)

string

useUnit

UnitChild

UnitChild properties

Property	Description	Type
unitCode	The unit code	string
unitId	The unit identifier	integer (int32)
unitInfo	The unit info	string

useUnitCost

Unit cost for the use

number (double)

versionId

ID of the rate schedule version

integer (int32)

Example Response application/json

{  "accountLineItems": [
    {    "calculationType": "string",    "caption": "string",    "observationType": {      "credit": 1,      "nounCode": "string",      "nounId": 1,      "observationTypeCode": "string",      "observationTypeId": 1,      "observationTypeInfo": "string"
    },    "value": 1.0
  }
  ],  "beginDate": "2026-03-30",  "costUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "createdBy": {    "fullName": "string",    "userCode": "string",    "userId": 1
  },  "createdDate": "2026-03-30",  "demandUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "demandUnitCost": 1.0,  "endDate": "2026-03-30",  "meterLineItems": [
    {    "calculationType": "string",    "caption": "string",    "observationType": {      "credit": 1,      "nounCode": "string",      "nounId": 1,      "observationTypeCode": "string",      "observationTypeId": 1,      "observationTypeInfo": "string"
    },    "value": 1.0
  }
  ],  "modifiedBy": {    "fullName": "string",    "userCode": "string",    "userId": 1
  },  "modifiedDate": "2026-03-30",  "note": "string",  "udfs": [
    {    "dataType": {      "dataTypeCode": "string",      "dataTypeId": 1,      "dataTypeInfo": "string"
    },    "description": "string",    "displayOrder": 1,    "important": false,    "name": "string",    "udfId": 1,    "udfSelectValues": [
      {      "displayOrder": 1,      "udfSelectValueId": 1,      "value": "string"
    }
    ],    "value": "string"
  }
  ],  "useUnit": {    "unitCode": "string",    "unitId": 1,    "unitInfo": "string"
  },  "useUnitCost": 1.0,  "versionId": 1
}