Period Closes

A period close marks the end of an accounting period (e.g. a billing month). It creates a permanent, auditable record in the journal and enables quota resets, credit expirations, and rollover grants.

Base URL: https://api.trancent.dev — all paths below are relative to this.

Close a period

POST /v1/ledgers/:ledgerId/period-closes

Request body

{
  "periodId": "2026-03",
  "reason": "Monthly billing cycle close"
}

Response — 201 Created

{
  "closeId": "01HXS...",
  "periodId": "2026-03",
  "closedAt": "2026-04-01T00:00:12.345Z"
}

Idempotency

Period closes are idempotent — closing the same periodId twice returns the existing close record without creating a duplicate. This makes it safe to retry close operations without side effects.

Merkle integrity

At close time, Trancent computes a Merkle hash tree over all journal entries in the period. The root hash is stored alongside the close record. Any party can later recompute the tree from the entries and compare the root — a mismatch indicates data divergence. This provides a lightweight, auditable checksum that survives exports and backups.

List period closes

GET /v1/ledgers/:ledgerId/period-closes

Response — 200 OK

{
  "closes": [
    {
      "closeId": "01HXS...",
      "periodId": "2026-03",
      "closedAt": "2026-04-01T00:00:12.345Z"
    }
  ]
}

Constraints

• Journal entries cannot be written to a closed period.
• Existing entries in a closed period cannot be reversed.
• A ledger in closed state cannot have new period closes.

Error responses

All errors follow the RFC 9457 problem detail format.