Checkpoint — Period-End

Use this endpoint to commit a period-end checkpoint. A checkpoint locks a cryptographic proof root over all verified deltas within a billing period, creating a tamper-evident snapshot you can reference later.

Endpoint#

POST https://balance-api.pacspace.io/api/v1/balance/checkpoint

Headers#

Request Body#

Examples#

Checkpoint a Specific Customer#

curl -X POST https://balance-api.pacspace.io/api/v1/balance/checkpoint \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "customerId": "cust_12345",
    "period": "2026-01"
  }'

Checkpoint All Customers for Current Period#

curl -X POST https://balance-api.pacspace.io/api/v1/balance/checkpoint \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

JavaScript (Node.js)#

const response = await fetch(
  "https://balance-api.pacspace.io/api/v1/balance/checkpoint",
  {
    method: "POST",
    headers: {
      "X-Api-Key": "YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      customerId: "cust_12345",
      period: "2026-01",
    }),
  }
);

const result = await response.json();
console.log(result);

Python#

import requests

response = requests.post(
    "https://balance-api.pacspace.io/api/v1/balance/checkpoint",
    headers={
        "X-Api-Key": "YOUR_API_KEY",
        "Content-Type": "application/json",
    },
    json={
        "customerId": "cust_12345",
        "period": "2026-01",
    },
)

result = response.json()
print(result)

Response#

{
  "success": true,
  "data": {
    "checkpointId": "chk_abc123def456",
    "period": "2026-01",
    "merkleRoot": "0x7f3a9b2c...",
    "deltaCount": 42,
    "status": "COMMITTED"
  }
}

Response Fields#

When to Checkpoint#

Checkpoints are designed for specific moments in your billing and record-keeping workflow:

End of Billing Period#

Run a checkpoint at the close of each billing cycle. This locks the period's deltas so that any future queries or receipts referencing that period return a consistent, verifiable snapshot.

# Lock January 2026 at the end of the month
curl -X POST https://balance-api.pacspace.io/api/v1/balance/checkpoint \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"period": "2026-01"}'

Before Generating Invoices#

Checkpoint before pulling receipts or computing invoice totals. This ensures the data backing your invoices is immutable and can be independently verified later.

For Tamper-Evident Records#

Each checkpoint produces a merkleRoot — a single hash that covers every verified delta in the period. If anyone questions the accuracy of a historical record, you can point to the checkpoint as proof that the data hasn't changed since it was locked.

How Checkpoints Work with Other Endpoints#

• Query — Use a checkpoint's merkleRoot as the startingCheckpoint parameter to derive balances efficiently from a known good point.
• Receipt — Generate receipts that align with checkpointed periods for consistent, verifiable invoicing.
• Verify — Reference a checkpoint when comparing balances to ensure both parties are working from the same locked dataset.

Tip: Automate checkpoints at the end of each billing period using a scheduled job or cron task. This ensures you never forget to lock a period before generating invoices.