Saved statements are the records that make up a customer’s statement history in Finance & Billing. Each record stores the balance, date, and document link captured when the statement was saved. This reference explains how you can create, change, remove, and batch-update those records. It also explains why Rhythm blocks deleting a contact or organization that still has saved statements, and why Portal members cannot access them.
Creating or Changing a Statement Record Directly
The usual way to create a saved statement record is to generate and send a statement. You can also use the API to create, replace, or change a record directly, without generating a statement.
| Route | What it does | Requirements |
|---|---|---|
POST /statements/{tenantId} | Creates a new record | Set customer_type to contact or organization, include the matching identifier (contact_id or organization_id), and provide open_balance, open_credits, and statement_uri |
PUT /statements/{tenantId}/{id} | Replaces an existing record | The record must already exist, and your request must include its current version |
PATCH /statements/{tenantId}/{id} | Changes only the fields you send | Include the current version, just as you do when replacing a record |
After Rhythm checks the schema, it does not validate the record’s contents. You can set the balance, credits, date, and document link to anything the schema allows. Rhythm does not confirm that a document exists at the statement_uri you provide, or that the amounts match anything else on the customer’s account. If you include a date, it must be a date with no time portion.
Because Rhythm allows these changes, a record updated this way can stop matching the statement the customer actually received. Rhythm does not keep a separate, unchangeable copy of what was sent. Each write still gets Rhythm’s standard version number, created-by and changed-by stamps, and a history entry. See Audit History for how Finance & Billing keeps that history the same way it does for other records.
To review a specific sent statement in the Console instead of the API, open the related contact or organization record. Go to the Finance tab, open Statements, and select the statement's identifier. The detail view shows who generated and sent the statement, and when, using the same created-by and changed-by information this API exposes.
Warning
Because a saved statement can be changed after it was sent, do not treat its saved amounts as proof of what a customer received without checking the record’s version and history first.
Removing a Saved Statement Record
DELETE /statements/{tenantId}/{id} removes a saved statement record from the customer’s statement history. It does not remove the statement document. The document stays available at its original address, so anyone who still has the link, such as from the original statement email, can open it after the record is gone. The deleted record’s last version stays in Rhythm’s history, so you can still see who deleted it and when.
Sending Many Changes in One Request
POST /statements/{tenantId}/batch runs many create, read, update, patch, and delete operations for statement records in one request. Rhythm checks each operation the same way it checks that operation by itself, then reports each result separately. One item in the batch can fail while the rest succeed.
Why You Cannot Delete a Contact or Organization with Saved Statements
Every saved statement names the contact or organization it belongs to. If at least one saved statement still refers to that contact or organization, Rhythm refuses to delete the contact or organization and shows a message like “we cannot delete the record(s) because N record(s) depend on it,” where N is the number of statements. You’ll see this as a server error rather than a normal conflict response. The contact or organization does not change; you must delete or otherwise clear the statements pointing to it before the delete can go through.
This block lasts as long as any saved statement refers to the contact or organization, because saved statements do not expire on their own. The rule applies only to statements that were actually saved. A statement that was generated but never saved through the record above has no reference and does not block anything. The same rule applies whether you delete the record from Contacts & Organizations or through its own API. See Change a Contact's Status or Delete a Contact for more about that delete.
Portal Access
A Portal member can never read or create a saved statement record through the API. Rhythm refuses both actions with 401 Unauthorized for a Portal sign-in, whether or not the requested record exists. A member who still has a statement’s direct document link, such as from the statement email, can still open that document. Only the saved record is out of reach.
Related
- Subledger Entries Through the API
- Change a Contact's Status or Delete a Contact
- Customer Balance Statements Explained