AmountString field type impractical for energy tariffs

[joshharris3]

The AmountString field type refers to an amount of currency, with valid currencies defined by ISO 4217, including AUD (Australian Dollars). According to the DSB, the Standards specify that AmountStrings should be represented in the AUD standard format ($00.00). This format is suitable for fees, such as a $12 late payment fee:

                "term": "FIXED",
                "type": "LATE_PAYMENT",
                "amount": "12.00",
                "description": "A late payment fee may be charged when full payment has not been received by the bill due date. This amount is not subject to GST"

However, this format ($00.00) is impractical for energy tariffs. Market analysis shows that retailer websites typically display tariffs in cents, and in discussions with our Accredited Data Recipients (ADRs), storing tariff information in cents is a strong preference as they reduce floating point precision (rounding) issues & (for consistency) reduce necessitating additional conversions for data sharing.

Example retailer website

Example new Tariff Structure

                                   "type": "SHOULDER",
                        "rates": [
                            {
                                "unitPrice": "25.83"
                            }
                        ],

Area Affected Get Generic Plan Detail https://consumerdatastandardsaustralia.github.io/standards/#cdr-energy-api_get-generic-plan-detail

Change Proposed We propose two potential alternatives:

1. Define a new type to support the energy industry's use of cents for tariffs and rebates. For example, a tariff of 5 cents would be represented as "0.05" in AmountString and "5" in a newly defined type.
2. Use the Number type for tariffs and rebates and specify in the attribute descriptions that the values represent cents.

[nils-work]

Hi @joshharris3

The description for AmountString states:

Minimum 2 digits following a decimal point (more digits allowable but only if required)

So "unitPrice": "0.2583" would be valid unless I've misunderstood your concerns.

[joshharris3]

Hi Nils,

I agree with your above comment, however perhaps wasn't as clear above about issue here.

Just to reiterate, we don't believe that the AmountString supports the energy industry which displays tariffs in cents not dollars. What this means practically:

1. Retailers provide tariffs in cents,
2. AER converts into dollars to meet CDR standards,
3. Data recipients must convert back to cents to align with energy industry standards e.g. for comparison websites.

I hope this helps clarify our position.

Thanks

[mattyp]

1. The units to use for an 'AmountString' field is and has always been ambiguous. The definition does not explicitly specify units (dollars or cents): ISO 4217 is only ever referenced for the "CurrencyString" (currency code), not an amount. In reality today, interpretation of this ambiguity means some AmountString values are provided as dollars and some as cents, even within details of the same plan contract. It would help enormously if this ambiguity were to be explicitly clarified in the definition. For example: "A string representing a monetary amount in main currency units with fractional units after a decimal point (e.g., if working with Australian dollars: "123.45" for one hundred twenty-three dollars and forty-five cents)."

2. Whatever the defined units are, converting between cents and dollars is trivial and not a worthy reason for a CR on its own. In terms of practicality, both dollar and cents are practical and what is "displayed" is irrelevant to what is defined. FWIW, in my implementation I try to detect the units being provided and standardise all to cents. Point #1, above, would help a lot to reduce errors in consumer facing products.

3. As one of many data recipients that will rely on the integrity of data from the AER my plead to the AER is to simply implement the format of main units (e.g. dollar) consistently and not let this reported maintenance issue be an excuse to hold up current much needed rectification work:

In summary, I concur with the callout that the definition for "AmountString" is problematically ambiguous, but do not support the notion that a change to the standards beyond clarifying the definition is required.