HomeGuidesRecipesAPI ReferenceChangelog
Log In
Guides

Edge Case: When Accounts with Adjustment Bills are Present

Task

Obtain the total consumption for a given meter during a given service period.

Contextual notes

  • In Utility Cloud, there are four types of statements: BILL, NOTICE, ADJUSTMENT, PREPAID. Adjustment statements are invoices issued by a provider after an initial invoice has been issued to update the content on the original invoice. The update may or may not relate to usages and charges. Therefore, you should always confirm whether the usage and charges on the adjustment statement is the same as the original statement.
    • If they are the same, you can continue to use the previous data that you’ve already proceeded with – make sure you are not counting the usages from both statements which would result in double counting.
    • If they are different, we recommend you manually review the two statements and decide which one is more suitable to be used contextually. Currently, we do not have a recommendation that works for all, if not most, cases. If you are having trouble deciding, please reach out to us for help.
  • At a high level, the following steps checks: For a statement period (denoted by the periodStart and periodEnd date values), whether a meter (identified by the meterId) shows up on more than one statement (identified by the statementId).

Steps

Accounting for adjustment bills for one meter:

  1. Use the List Meter’s Statements endpoint to make a request by specifying the meterId.
  2. The response will include a list of statements at the JSON path ._embedded.statements. For each statement, there will be a periodStart and periodEnd date pair. Identify the respective periodStart and periodEnd fields for each statementId and review them to identify whether there are periods that have multiple statementIds.
    1. If there are no periods that have more than one statementIds (in other words, each period only has one corresponding statementId), then there are no adjustment statements. You have completed this check and can continue to use the data you’ve stored without extra processing steps.
    2. If there are periods that have more than one statementIds, then there may be adjustment statements. You need to proceed to step 3.
  3. For the statementIds that have the same values for the periodStart and periodEnd fields, review the value for the statementType field at the JSON path ._embedded.statements.statementType for each statementId. If the value for the statementType field is ADJUSTMENT, its statement object is created from an adjustment bill from the provider.
  4. Compare the totalUsage and totalCharges values on the meterData objects at the JSON path ._embedded.statements.accountData.meterData from all statement types during the same period and determine which one is more appropriate to be used contextually.

    📘

    Likely, you will need to carry this step out manually.

Accounting for adjustment bills for all meters:

  1. Use the List Meters endpoint to make a request with no search parameters specified.
  2. The response will include a list of all meters that belongs to your organization.
  3. Follow steps 1-4 for each meterId returned in the response in step 6.