Statement Versioning and Repair

Overview

Utility providers often issue corrected bills, and complex PDF layouts can occasionally lead to extraction errors. To handle these updates without disrupting your workflow, Plug uses a two-pronged approach:

• Versioning: Maintains a permanent history of every iteration of a statement.
• Repairs: A proactive workflow to identify and correct data quality issues.

---

Statement Versioning

Prior to December 2025, when a data point changed, the previous value was overwritten. Statement Versioning replaces this "delete-and-replace" model with an immutable ledger.

Key Concepts

Immutable History

Every statement now has a complete version history. Instead of overwriting data during corrections, the system creates new versions while preserving the old ones. This allows developers to "lock" their applications to a specific, stable version of data, preventing unexpected changes from breaking integrations.

Voided Data

To maintain an accurate history without losing data integrity, entities (such as Meters or Accounts) that are removed during a correction are no longer hard-deleted. Instead, they are marked with a voidedAt date-timestamp.

In the edge case that a previously voided object is valid once again, we will unvoid the object by setting the voidedAt value as null. The objects event history will show this change so it can easily be tracked over time. This edge case primarily impacts meters with a null meter number.

Voided Data indicates the data is no longer part of the current valid set but exists for historical reference. You can directly navigate to voided data in the Dashboard, but it is not represented as a first class object intentionally.

Examples of voided data

If an initially extracted account number is incorrect, but later corrected by Arcadia, then then the Account record that has the incorrect number would get voided. The corrected version of the data extraction with the new Account record would be associated to the the Statement, and show up on the newer version of the Statement record. The same concept would apply for Meters.

How it Works

Every statement in Plug is assigned a unique statementId. When a change occurs—such as a manual correction or a re-extraction—Arcadia creates a new version of that statement.

• The "Latest" Version: By default, API requests return the most recent, most accurate version of the statement. On the Dashboard, the most recent version is also shown by default, but you can select a previous version to view. If an Account or Meter record is voided and you select the Statement link, you will land on the latest Statement Version that that voided entity appeared on.
• Audit Trail: Previous versions are retained and remain accessible via the API, allowing you to compare changes over time for financial auditing or ESG reporting.

Why Versioning Matters

• Financial Compliance: Track exactly why a balance changed between two different syncs.
• Data Integrity: Prevent data loss by never deleting historical records.
• Transparency: Understand if a change was triggered by a utility-issued correction or an Arcadia internal update.

CSV downloads

Download account statement CSV, Site usage CSV, and Meter usage CSVs now have a new column appended for "Latest Statement Version ID" to provide users with the ability to trace CSV data to statement versions.

Webhooks

The STATUS_CHANGE webhook will emit when an account or meter is marked as voided or unvoided.

The EXISTING_DATA_UPDATED now includes the new versionId in the payload, allowing clients to identify and retrieve the latest version immediately upon reprocessing.

---

Statement Repairs

Statement Repairs is the internal engine Arcadia uses to ensure the data delivered to you is clean and valid. Arcadia is committed to delivering accurate, reliable utility billing data. Occasionally, after a statement has been ingested, processed and delivered, we may identify issues or improvements and proactively issue a corrected version. Note that this is distinct from an Adjustment Statement issued by a provider.

What is Repaired and Why

Repairs may include:

• Updated charges or line items due to template or parsing improvements
• Adjusted usage proration when interval data becomes available
• Fixes for previously misaligned dates, units, or costs
• Re-extraction using new or corrected source files

We may initiate a repair for a variety of reasons, including:

• Proactive improvements to our data extraction or proration logic
• A fix for a known issue affecting specific providers or statement templates
• A customer-submitted ticket that leads to a systemic template correction

Identifying Repaired Data

When a statement is repaired:

• The statement’s statement_id remains the same
• The contents of the statement (such as totals, charges, and dates) may change
• The statements's lastModifiedAt date will be updated to the date-time that the bill was repaired
• The statement's versionId will be updated to a new hash.

Webhook Behavior

When a statement is repaired and its data changes, Arcadia will emit the EXISTING_DATA_UPDATED EventType webhook event for the associated statementId with a STATEMENT Entity Type. This webhook event signals that a previously-synced record has been updated and your systems may want to re-fetch the latest data. See this page for more details on Webhooks.

Known Limitations

• We do not version statements in the Plug API — only the most recent version is available.
• There is currently no way to preview or compare changes between the original and repaired version unless you fetch the new version and compare it to the previous version in your own database.
• Customers are not directly notified when a repair is triggered unless they are monitoring for EXISTING_DATA_UPDATED events.

Best Practices

To ensure you capture the latest billing data:

• Subscribe to the EXISTING_DATA_UPDATED webhook event
• Use the lastModifiedAt timestamp on the Statement entity to detect changes
• Design your systems to reprocess or reconcile repaired statements as needed
• If you see an issue with one of your Statements, please create a Zendesk ticket.

---

Key Concepts

---

📘 Note on API Implementation

To take full advantage of Statement Versioning, ensure your integration is using the latest API version. This allows you to utilize specific headers and webhooks to stay notified whenever a statement is updated or repaired.