PUT /api/v3/account/{accountId}/meter/{meterId}/billSplit

Manages the bill split version history for an account-meter relationship (create, update, delete)

ManageBillSplitVersionHistoryV3 Permissions: Chargebacks (Manage)
Use this endpoint to set the final desired state of all split versions on an account-meter pair. Pass all versions that should exist: new versions (no versionId) are created, existing versions (with versionId) are updated, and versions in the database but not in the request are deleted. Set copyVersionId to copy instructions/inputs from another version. Versions cannot overlap in effective dates. Deletions fail if the version has associated bills. The entire operation is transactional.

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
accountId Unique numeric identifier of the account integer (int32) Required
meterId Unique numeric identifier of the meter integer (int32) Required

Request Body

Array of:

DistributionVersionManage
Property Description Type
beginPeriod Begin period for the version in the format YYYYMM Cannot overlap any existing versions on this account and meter for the chargeback type being managed Required Valid billing period between 190001 and 300001 integer (int32)
copyVersionId An existing version id on this account meter to copy A new version will be created and all instructions will be copied to the new version CopyVersionId chargeback type must match the chargeback type being managed (Either “Split” or “Calculation”). CopyVersionId must exist on the account and meter relationship being updated Required (defined) Only one of VersionId, CopyVersionId can be set integer (int32)
endPeriod End period for the version in the format YYYYMM null value means continuing indefinitely Cannot overlap any existing versions on this account and meter for the chargeback type being managed Valid billing period between 190001 and 300001 NULL Valid Must be greater than or equal to BeginPeriod Required (defined) integer (int32)
name Name given to the version Name must be unique for a particular account and meter Required Must be between 0 and 64 characters string
versionId Version id to update VersionId must exist on the account and meter relationship being updated Required (defined) Only one of VersionId, CopyVersionId can be set integer (int32)
workflowStepId Workflow step this version will belong to The workflow step type must match the chargeback type being managed (Either “Split” or “Calculation”) Required (defined) integer (int32)
Example Request Body application/json 
[
  {    "beginPeriod": 1,    "copyVersionId": 1,    "endPeriod": 1,    "name": "string",    "versionId": 1,    "workflowStepId": 1
  }
]

Responses

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

Response Body Parameters

Array of:

DistributionVersionResponse
Property Description Type
account AccountChildWithType
AccountChildWithType properties
Property Description Type
accountCode The account code (unique identifier assigned by the organization) string
accountId The unique identifier of the account integer (int32)
accountInfo The account description/name string
accountType AccountTypeChild
AccountTypeChild properties
Property Description Type
accountTypeCode The account type code string
accountTypeId The account type identifier integer (int32)
accountTypeInfo The account type info string
active Whether the account is currently active. Null if not applicable. boolean
hasCalculatedMeter Whether the account has a child calculated meter boolean
hasSplitChildMeter Whether the account has a child split meter boolean
hasSplitParentMeter Whether the account is a recipient of a meter split boolean
hasSubAccount Whether this account has sub-accounts beneath it boolean
isSubAccount Whether this account is a sub-account of a summary account boolean
vendor VendorChild
VendorChild properties
Property Description Type
vendorCode The vendor code string
vendorId The vendor identifier integer (int32)
vendorInfo The vendor info string
beginPeriod Begin period for the version integer (int32)
chargebackType The chargeback type. Either “Split” or “Calculation” string
endPeriod End period for the version null value means continuing indefinitely integer (int32)
hasBills Do any bills exist that were created by this version? A version cannot be deleted if there are any existing bills that were created using this version boolean
meter MeterChild
MeterChild properties
Property Description Type
active Indicates whether the Meter is Active boolean
commodity CommodityChild
CommodityChild properties
Property Description Type
commodityCode The commodity code Required (defined) string
commodityIcon Icon
Icon properties
Property Description Type
code The icon code Must be between 0 and 64 characters Required when Color is set string
color The icon color Must be between 0 and 32 characters Required when Code is set string
commodityId The commodity identifier Required (defined) integer (int32)
commodityInfo The commodity info Required (defined) string
isCalculatedMeter Indicates whether the meter is a calculated meter boolean
isEsaCalculatedMeter Indicates whether the meter is an ESA calculated meter boolean
isSplitChildMeter Indicates whether the meter is a child of a split boolean
isSplitParentMeter Indicates whether the meter is a parent of a split boolean
meterCode The meter code string
meterId The meter identifier integer (int32)
meterInfo The meter info string
meterType MeterTypeChild
MeterTypeChild properties
Property Description Type
meterTypeCode Short code for the meter type (e.g., “ELEC”, “GAS”) string
meterTypeId Unique numeric identifier of the meter type integer (int32)
meterTypeInfo Descriptive name of the meter type string
serialNumber The meter’s current serial number string
versionId Identifier for the version integer (int32)
versionInfo Name given to a version string
workflow ChargebackWorkflowStepChild
ChargebackWorkflowStepChild properties
Property Description Type
chargebackWorkflow ChargebackWorkflowBase
ChargebackWorkflowBase properties
Property Description Type
chargebackWorkflowId Identifier for the chargeback workflow integer (int32)
chargebackWorkflowInfo Name given to the chargeback workflow string
chargebackWorkflowStepDescription Description for the chargeback workflow step string
chargebackWorkflowStepId Identifier for the chargeback workflow step integer (int32)
chargebackWorkflowStepInfo Name given to the chargeback workflow step string
chargebackWorkflowStepOrder The order for this step within the chargeback workflow integer (int32)
chargebackWorkflowStepType The chargeback type that can be assign to this chargeback workflow step. One of ‘Split’, ‘Calculation’ One of ‘Split’, ‘Calculation’ string
Example Response application/json 
[
  {    "account": {      "accountCode": "string",      "accountId": 1,      "accountInfo": "string",      "accountType": {},      "active": false,      "hasCalculatedMeter": false,      "hasSplitChildMeter": false,      "hasSplitParentMeter": false,      "hasSubAccount": false,      "isSubAccount": false,      "vendor": {}
    },    "beginPeriod": 1,    "chargebackType": "string",    "endPeriod": 1,    "hasBills": false,    "meter": {      "active": false,      "commodity": {},      "isCalculatedMeter": false,      "isEsaCalculatedMeter": false,      "isSplitChildMeter": false,      "isSplitParentMeter": false,      "meterCode": "string",      "meterId": 1,      "meterInfo": "string",      "meterType": {},      "serialNumber": "string"
    },    "versionId": 1,    "versionInfo": "string",    "workflow": {      "chargebackWorkflow": {},      "chargebackWorkflowStepDescription": "string",      "chargebackWorkflowStepId": 1,      "chargebackWorkflowStepInfo": "string",      "chargebackWorkflowStepOrder": 1,      "chargebackWorkflowStepType": "string"
    }
  }
]