Versioning system

The Arcadia API uses a dated version scheme (YYYY-MM-DD). A new version is released when one or more breaking changes are made to the API. As we will always ensure changes are backwards compatible, breaking changes on new versions will not impact existing integrations. Though new functionality is often available to old API versions, we recommend you to use the latest version of the API.

Every API request must specify the desired version through the Arcadia-Version header. For example: Arcadia-Version: 2024-02-21. Every response will include the version used in the Arcadia-Version header. API requests that do not provide a valid Arcadia-Version header will return an error with HTTP status 400.

🚧
Every API request MUST specify the desired version through the Arcadia-Version header.

Breaking and Non-Breaking Changes

Breaking Changes

Here is a list of representative examples that we would consider as breaking changes:

Headers

Removing a request header
Removing a required response header
Adding a required request header
Changing a response header from required to optional

Request and Response Bodies

Adding a required field to a request body
Renaming a field in a request body
Removing a required or optional field from a request body
Removing a required or optional field from a response body
Changing a field in a response body from required to optional
Changing the type of a field in a request or response body

Downloadable CSV files

Changing how the columns are ordered
Updating column names

When we make breaking changes, it will always be accompanied by a new version release. We will update the Arcadia Platform Changelog and send an email to you with a link to the Changelog.

Non-Breaking Changes

We consider the following changes to be non-breaking changes:

Headers

Changing a request header entry from required to optional
Changing a response header entry from optional to required
Adding a request or response header entry

Requests and Response Bodies

Changing a field in a request body from required to optional, without a behavioral change
Changing a field in a response body from optional to required
Adding new optional parameters for existing endpoints
Adding new properties to an existing API response schema
Adding new webhook event types

Downloadable CSV files

Adding new columns at the end of the template

Others

Adding new endpoints
Changing error_codes to be more specific for errors that cannot be resolved by the developer consuming the Arcadia API. For example, changing a 500 error code to a 504 error code.

Examples of Non-Breaking Changes in the Arcadia Context

Here are some examples of changes that will happen from time to time in the utility data context. We considered these types changes as non-breaking changes. Therefore, you need to build your integration in a way that can handle these types changes.

Scenario	Who makes the change	Description	Impact on your data	Integration recommendation
Account number changes	Provider	These changes typically happen when the provider has a business reason to do so. For example, a provider may update their accounting system which requires them to update all existing account numbers.	The data you would expect for an account number will be presented under a different account number.	You should keep an internal mapping of old and new account numbers for future reference.
Meter number changes	Provider	Compared to account number changes, meter number changes happen more frequently and are a result of how meters work. Most meters have a three to five year lifecycle and may be replaced after that. When an old meter is replaced, the old meter number will no longer be updated with new data. New data will have the meter number of the new meter.	In most cases, you will continue to see the same number of meters in the `meterData` object or on the account, however, the `meterNumber` (and `normalizedMeterNumber`) and meterId would be updated.	You should keep an internal mapping of old and new meter numbers for future reference.
Summary Keys moving from account level to meter level and vice versa	Arcadia	In the Arcadia context, “Summary Keys” refers to a set of meta-information that may not fit easily into the Account, Meter, Usage, or Charge resource. Refer to this we wil for a full list of Summary Keys. Most of the time, we assign Summary Keys to the `accountData` resource. However, they can be assigned to any level of the Arcadia data model. We may make changes to where we assign a Summary Key in order to make the data model more intuitive.	A nullable and optional field that used to be populated at the account level is no longer populated. The same data will be populated in the same nullable and optional field at the meter level. Or vice versa.	You should build your integration to check for the same field at both the account and meter level.
Number of meter resources returned in the `meterData` object.	Arcadia	When we realize a smart meter and a mechanical meter are duplicative of each other, we will remove the mechanical meter. You would see one or more less meter resources in the `meterData` object.	The overall usages and charges data at the account level would not be impacted as we would only remove duplicates.	For extra assurance to avoid double counting, only count resources that are flagged as `CONTRIBUTING` in the respective `contributionStatus` fields.
Number of usage/charge resources returned in the `usages`/`charges` object. Utility account holder.	Provider	When the utility account holder switches tariffs or when providers update their invoice formats, it may result in a different number of `usages`/`charges` returned in the usages/charge object.	You would see a different number of usage/charge resources in the `usages`/`charges` object.	You should not expect the number of `usages`/`charges` in the `usages`/`charges` object to stay the same.
Tariff name change.	Arcadia Utility account holder Provider	The utility account holder may choose to update their tariff at any time. As a result of being on a different tariff, the tariff name will change. The provider may choose to update the names of their tariffs. We may update a tariff name when we realize that we we have a more accurate interpretation of the data.	The field `tariffName` will have a string that is different from the previous one.	Your API integration should be flexible enough to handle the string for this field to change.
Tariff Rate Component Type field change	Provider	The provider may change this on the bill from time to time.	This field is designed to suggest that changes should be expected. It is an enumeration of strings.	Your API integration should be flexible enough to handle all possible strings, rather than a subset of possible strings. For example, do not hardcode your integration to only handle the value maxPeak as this field may change.
Unit of measure change for a specific usage item	Provider Arcadia	As bill formats published may contain imprecise charge and usage descriptions, we often have to determine when a charge item or usage item is best identified as having no explicit unit measure. Our interpretation always derives from the bill and the bill only. When a usage or charge item has no explicit unit of measure, Arcadia will use `UNDEFINED` in the field response.	At times, seeing `UNDEFINED` as the unit of measure for charge items or usage items is expected.	If you have a preferred unit of measure mapping for specific accounts, you need to build custom logic on your end to account for the mapping.
Usage item changes from `citedUsage` to `measuredUsage` or vice versa.	Provider Arcadia	`citedUsage` is not measured by a meter reading on the current statement. This is the billed usage. Whereas the `measuredUsage` is measured by a meter reading on the current statement. This is the actual usage. As bill formats published may contain imprecise charge and usage descriptions, we often has to determine when a charge item or usage item is best identified as cited or measured. Our interpretation always derives from the bill and the bill only.	For an account, whether you see both or either fields populated may differ from statement to statement.	You should always look for values in both fields to ensure you are not missing data
`usages`/`charges` items changes from `NON_CONTRIBUTING` to `CONTRIBUTING` or vice versa	Arcadia	As bill formats published may contain imprecise charge and usage descriptions, Arcadia often has to determine whether a usage/charge item is best identified as a duplicate/redundant value. Our interpretation always derives from the bill and the bill only.	An `usages`/`charges` item that is considered as `NON_CONTRIBUTING` in one context may be `CONTRIBUTING` in a different context.	You should not assume if a `usages`/`charges` item is `NON_CONTRIBUTING` on one statement, that same usage/charge item will always be `NON_CONTRIBUTING` on all future statements.
`usages`/`charges` item moves from the `accountData` object to the `meterData` object or vice versa.	Provider Arcadia	As bill formats published may contain imprecise charge and usage descriptions, Arcadia often has to determine whether the usage/charge item should be reflected at the account or meter level. Our interpretation always derives from the bill and the bill only.	A nullable and optional field that used to be populated at the account level is no longer populated. The same data will be populated in the same nullable and optional field at the meter level. Or vice versa.	You should build your integration to check for the same field at both the account and meter level.