Put /api/v3/account/{accountId}/meter/{meterId}/calculatedBill/{versionId}/use

Operation: ManageCalculateBillUseV3 Permissions: Chargebacks (Manage)

Summary

Manage calculated bill’s use
* If use does not exist on the distribution it will be added
* If use already exists it will be saved as the option sent in and any existing inputs will be deleted
* Since use is required for the calculated bill distribution to work, one option is always required and cannot be deleted

Path and Query Parameters

Parameter Description Type Location
accountId ID of the account to receive calculated bill detailsRequired integer Path
meterId ID of the meter to receive calculated bill detailsRequired integer Path
versionId ID of the calculated bill distribution versionRequired integer Path

Request Body Parameters

Content-Type: application/json

Type Reference: CalculatedBillUseRequest

Defines how use is calculated for a calculated bill distribution

Parameter Description Type
readingsChannelId Use monthly channel data readings to calculate bill use Required (defined) Only one of ReadingsChannelId, FixedAmount, CopyUseFromMeter, UseCalculation, CalendarizedUseCalculation, UseWatticsDataPoint can be set integer
fixedAmount FixedUseRequest
   fixedUseAmount Fixed use amount Required Max scale of 6 number
   unitId Unit to which use is applied Required integer
copyUseFromMeter Defines a meter whose use or cost will be copied when calculating a bill
The meter may have a commodity which is different than the destination meter
When doing the calculation we will sum the use or cost across all accounts this meter is associated with for the billing period begin run		 CopyMeterRequest
   meterId Meter from which use or cost will be copied Required Topmost (LogicalDevice) integer
   percentage Percentage of use or cost to copy
Pass the percentage value
For example 50.5% should be 50.5 Required Max scale of 8		 number
useCalculation Adding/subtracting calculation involving meters and/or meter groups
You must pass in at least 1 thing to sum or subtract		 CalculationRequest
   sum SumRequest
      sumMeterIds Meters in this list will have their use or cost added together during the bill calculation Required (defined) Only one of SumMeterIds, SumMeterGroupIds can be set array
      sumMeterGroupIds Distinct meters from these meter groups will have their use or cost added together during the bill calculation
System auto groups cannot be used Required (defined) Only one of SumMeterIds, SumMeterGroupIds can be set		 array
   subtract SubtractRequest
      subtractMeterIds Meters in this list will have their use or cost subtracted during bill calculation Required (defined) Only one of SubtractMeterIds, SubtractMeterGroupIds can be set array
      subtractMeterGroupIds Distinct meters from these meter groups will have their use or cost subtracted together during the bill calculation
System auto groups cannot be used Required (defined) Only one of SubtractMeterIds, SubtractMeterGroupIds can be set		 array
calendarizedUseCalculation Adding calculation involving meters
You must pass in at least 1 thing to sum		 CalendarizedCalculationRequest
   sum CalendarizedSumRequest
      sumMeterIds Meters in this list will have their use or cost added together during the bill calculation Cannot be Empty Required array
useWatticsDataPoint Use SmartAnalytics (Wattics) data readings to calculate bill use One of ‘True’ Case sensitive Required (defined) Only one of ReadingsChannelId, FixedAmount, CopyUseFromMeter, UseCalculation, CalendarizedUseCalculation, UseWatticsDataPoint can be set boolean

Request Body

{
  "readingsChannelId": 1,
  "fixedAmount": {
    "fixedUseAmount": 1.0,
    "unitId": 1
  },
  "copyUseFromMeter": {
    "meterId": 1,
    "percentage": 1.0
  },
  "useCalculation": {
    "sum": {
      "sumMeterIds": [
        1
      ],
      "sumMeterGroupIds": [
        1
      ]
    },
    "subtract": {
      "subtractMeterIds": [
        1
      ],
      "subtractMeterGroupIds": [
        1
      ]
    }
  },
  "calendarizedUseCalculation": {
    "sum": {
      "sumMeterIds": [
        1
      ]
    }
  },
  "useWatticsDataPoint": false
}

Response Parameters

HTTP 200


Body Parameters

Content Type: application/json

Type Reference: CalculatedBillUseResponse

Definition of how a calculated bill will get its use

Parameter Description Type
readingsFromChannel ChannelChildWithObservationType
   type ObservationTypeChild
      nounId The identifier for the observation type’s noun integer
      nounCode The observation type’s noun code string
      credit Indicates the type of credit for the observation type. Possible values include: 1 (Credit), 2 (Debit), 3 (Ignore) integer
      observationTypeId The observation type identifier integer
      observationTypeCode The observation type code string
      observationTypeInfo The observation type info string
   rule ObservationRule
      observationRuleId The observation rule identifier integer
      observationRuleCode The observation rule code string
      observationRuleInfo The observation rule info string
   channelCode The channel code
Combines observationTypeCode:unitCode:observationMethodCode:observationRuleCode:interval in minutes		 string
   channelId The channel identifier integer
   interval The channel interval in seconds.
Monthly = 2592000
Weekly = 604800
Daily = 86400
Hourly = 3600
Thirty_Minutes = 1800
Fifteen_Minutes = 900		 integer
fixedAmount Fixed amount per unit to apply during bill calculation FixedAmountResponse
   amount Fixed amount number
   unit UnitChild
      unitId The unit identifier integer
      unitCode The unit code string
      unitInfo The unit info string
copyUseFromMeter Defines an account and meter whose use or cost will be copied when calculating a bill CopyFromMeterResponse
   meter MeterChild
      meterId The meter identifier integer
      meterCode The meter code string
      meterInfo The meter info string
      meterType MeterTypeChild
         meterTypeId integer
         meterTypeCode string
         meterTypeInfo string
      commodity CommodityChild
         commodityId The commodity identifier Required (defined) integer
         commodityCode The commodity code Required (defined) string
         commodityInfo The commodity info Required (defined) string
         commodityIcon Icon
            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
      active Indicates whether the Meter is Active boolean
      isCalculatedMeter Indicates whether the meter is a calculated meter boolean
      isSplitParentMeter Indicates whether the meter is a parent of a split boolean
      isSplitChildMeter Indicates whether the meter is a child of a split boolean
      serialNumber The meter’s current serial number string
   percentage Percentage of use or cost to copy number
useCalculation Adding/subtracting calculation involving meters and/or meter groups
For each type (sum or subtract), expect only one of the properties to be populated (e.g. if SumMeters has values, then SumMeterGroups should not)		 CalculationResponse
   sum SumResponse
      sumMeters Meters in this list will have their use or cost added together during the bill calculation MeterChild [Array]
         meterId The meter identifier integer
         meterCode The meter code string
         meterInfo The meter info string
         meterType MeterTypeChild
            meterTypeId integer
            meterTypeCode string
            meterTypeInfo string
         commodity CommodityChild
            commodityId The commodity identifier Required (defined) integer
            commodityCode The commodity code Required (defined) string
            commodityInfo The commodity info Required (defined) string
            commodityIcon Icon
               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
         active Indicates whether the Meter is Active boolean
         isCalculatedMeter Indicates whether the meter is a calculated meter boolean
         isSplitParentMeter Indicates whether the meter is a parent of a split boolean
         isSplitChildMeter Indicates whether the meter is a child of a split boolean
         serialNumber The meter’s current serial number string
      sumMeterGroups Distinct meters from these meter groups will have their use or cost added together during the bill calculation MeterGroupChild [Array]
         meterGroupId The meter group identifier integer
         meterGroupCode The meter group code string
         meterGroupInfo The meter group info string
         autoGroup Indicates if this meter group is an autogroup boolean
         userDefinedAutoGroup Indicates if this meter group is an user defined auto group boolean
   subtract SubtractResponse
      subtractMeters Meters in this list will have their use or cost subtracted during bill calculation MeterChild [Array]
         meterId The meter identifier integer
         meterCode The meter code string
         meterInfo The meter info string
         meterType MeterTypeChild
            meterTypeId integer
            meterTypeCode string
            meterTypeInfo string
         commodity CommodityChild
            commodityId The commodity identifier Required (defined) integer
            commodityCode The commodity code Required (defined) string
            commodityInfo The commodity info Required (defined) string
            commodityIcon Icon
               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
         active Indicates whether the Meter is Active boolean
         isCalculatedMeter Indicates whether the meter is a calculated meter boolean
         isSplitParentMeter Indicates whether the meter is a parent of a split boolean
         isSplitChildMeter Indicates whether the meter is a child of a split boolean
         serialNumber The meter’s current serial number string
      subtractMeterGroups Distinct meters from these meter groups will have their use or cost subtracted together during the bill calculation MeterGroupChild [Array]
         meterGroupId The meter group identifier integer
         meterGroupCode The meter group code string
         meterGroupInfo The meter group info string
         autoGroup Indicates if this meter group is an autogroup boolean
         userDefinedAutoGroup Indicates if this meter group is an user defined auto group boolean
calendarizedUseCalculation Adding calendarized calculation involving meters CalendarizedCalculationResponse
   calendarizedSum Addition calculation involving meters MeterChild [Array]
      meterId The meter identifier integer
      meterCode The meter code string
      meterInfo The meter info string
      meterType MeterTypeChild
         meterTypeId integer
         meterTypeCode string
         meterTypeInfo string
      commodity CommodityChild
         commodityId The commodity identifier Required (defined) integer
         commodityCode The commodity code Required (defined) string
         commodityInfo The commodity info Required (defined) string
         commodityIcon Icon
            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
      active Indicates whether the Meter is Active boolean
      isCalculatedMeter Indicates whether the meter is a calculated meter boolean
      isSplitParentMeter Indicates whether the meter is a parent of a split boolean
      isSplitChildMeter Indicates whether the meter is a child of a split boolean
      serialNumber The meter’s current serial number string
readingsFromWatticsDataPoint WatticsDataPointChild
   watticsDataPointId The identifier for a SmartAnalytics (Wattics) meter integer
   watticsDataPointInfo The name for a SmartAnalytics (Wattics) meter string

Responses

HTTP 200

Body

Content Type: application/json
{
  "readingsFromChannel": {
    "type": {
      "nounId": 1,
      "nounCode": "string",
      "credit": 1,
      "observationTypeId": 1,
      "observationTypeCode": "string",
      "observationTypeInfo": "string"
    },
    "rule": {
      "observationRuleId": 1,
      "observationRuleCode": "string",
      "observationRuleInfo": "string"
    },
    "channelCode": "string",
    "channelId": 1,
    "interval": 1
  },
  "fixedAmount": {
    "amount": 1.0,
    "unit": {
      "unitId": 1,
      "unitCode": "string",
      "unitInfo": "string"
    }
  },
  "copyUseFromMeter": {
    "meter": {
      "meterId": 1,
      "meterCode": "string",
      "meterInfo": "string",
      "meterType": {
        "meterTypeId": 1,
        "meterTypeCode": "string",
        "meterTypeInfo": "string"
      },
      "commodity": {
        "commodityId": 1,
        "commodityCode": "string",
        "commodityInfo": "string",
        "commodityIcon": {
          "code": "string",
          "color": "string"
        }
      },
      "active": false,
      "isCalculatedMeter": false,
      "isSplitParentMeter": false,
      "isSplitChildMeter": false,
      "serialNumber": "string"
    },
    "percentage": 1.0
  },
  "useCalculation": {
    "sum": {
      "sumMeters": [
        {
          "meterId": 1,
          "meterCode": "string",
          "meterInfo": "string",
          "meterType": {
            "meterTypeId": 1,
            "meterTypeCode": "string",
            "meterTypeInfo": "string"
          },
          "commodity": {
            "commodityId": 1,
            "commodityCode": "string",
            "commodityInfo": "string",
            "commodityIcon": {
              "code": "string",
              "color": "string"
            }
          },
          "active": false,
          "isCalculatedMeter": false,
          "isSplitParentMeter": false,
          "isSplitChildMeter": false,
          "serialNumber": "string"
        }
      ],
      "sumMeterGroups": [
        {
          "meterGroupId": 1,
          "meterGroupCode": "string",
          "meterGroupInfo": "string",
          "autoGroup": false,
          "userDefinedAutoGroup": false
        }
      ]
    },
    "subtract": {
      "subtractMeters": [
        {
          "meterId": 1,
          "meterCode": "string",
          "meterInfo": "string",
          "meterType": {
            "meterTypeId": 1,
            "meterTypeCode": "string",
            "meterTypeInfo": "string"
          },
          "commodity": {
            "commodityId": 1,
            "commodityCode": "string",
            "commodityInfo": "string",
            "commodityIcon": {
              "code": "string",
              "color": "string"
            }
          },
          "active": false,
          "isCalculatedMeter": false,
          "isSplitParentMeter": false,
          "isSplitChildMeter": false,
          "serialNumber": "string"
        }
      ],
      "subtractMeterGroups": [
        {
          "meterGroupId": 1,
          "meterGroupCode": "string",
          "meterGroupInfo": "string",
          "autoGroup": false,
          "userDefinedAutoGroup": false
        }
      ]
    }
  },
  "calendarizedUseCalculation": {
    "calendarizedSum": [
      {
        "meterId": 1,
        "meterCode": "string",
        "meterInfo": "string",
        "meterType": {
          "meterTypeId": 1,
          "meterTypeCode": "string",
          "meterTypeInfo": "string"
        },
        "commodity": {
          "commodityId": 1,
          "commodityCode": "string",
          "commodityInfo": "string",
          "commodityIcon": {
            "code": "string",
            "color": "string"
          }
        },
        "active": false,
        "isCalculatedMeter": false,
        "isSplitParentMeter": false,
        "isSplitChildMeter": false,
        "serialNumber": "string"
      }
    ]
  },
  "readingsFromWatticsDataPoint": {
    "watticsDataPointId": 1,
    "watticsDataPointInfo": "string"
  }
}