Checkpoint - Period-End
Commit checkpoint proofs, list historical checkpoints, and compare two checkpoints over a customer timeline.
Use checkpoints to lock a period-end proof over verified deltas. Checkpoints support historical replay, faster derivations, and consistent receipts.
Commit A Checkpoint
http
POST https://app.pacspace.io/api/v1/balance/checkpoint
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
customerId | string | No | Customer scope. Omit to checkpoint all active customers in the resolved window. |
period | string | No | Month scope in YYYY-MM. |
timePreset | string | No | current_month or custom. |
startDate | string | No | Custom scope start (ISO 8601). |
endDate | string | No | Custom scope end (ISO 8601). |
mode | string | No | Optional selection mode for advanced checkpoint filtering. |
fingerprints | string[] | No | Optional fingerprint subset when selection mode is enabled. |
Scope Rules
- Scope fields are mutually exclusive by mode (period/preset/custom).
- Dashboard quick-range chips (Last 30/90 days, Last 12 months) resolve to
customwith explicitstartDate/endDate. - Scope is capped by backend limits.
- Repeating the same request for the same resolved scope is idempotent.
SDK Example
typescript
import { PacSpace } from '@pacspace-io/sdk';
const pac = new PacSpace({ apiKey: process.env.PACSPACE_API_KEY! });
const checkpoint = await pac.balance.checkpoint('cust_12345', {
period: '2026-04',
});
console.log(checkpoint.checkpointId);
console.log(checkpoint.proofRoot);
cURL Example
bash
curl -X POST https://app.pacspace.io/api/v1/balance/checkpoint \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_12345",
"period": "2026-04"
}'
List Checkpoints
http
GET https://app.pacspace.io/api/v1/balance/checkpoints
Query filters:
customerIdperiodtimePresetstartDateendDatelimitoffset
SDK example:
typescript
const { checkpoints } = await pac.balance.listCheckpoints({
customerId: 'cust_12345',
period: '2026-04',
limit: 25,
});
Checkpoint Timeline
http
GET https://app.pacspace.io/api/v1/balance/checkpoint-timeline/:customerId
Returns:
- Timeline
points(ordered checkpoints) - Coverage
gaps - Range
summary
SDK example:
typescript
const timeline = await pac.balance.listCheckpointTimeline('cust_12345', {
startDate: '2026-01-01T00:00:00.000Z',
endDate: '2026-05-01T00:00:00.000Z',
});
Compare Two Checkpoints
http
POST https://app.pacspace.io/api/v1/balance/checkpoint-diff/:customerId
Request body:
json
{
"leftCheckpointId": "chk_aaa...",
"rightCheckpointId": "chk_bbb..."
}
SDK example:
typescript
const diff = await pac.balance.diffCheckpoints(
'cust_12345',
'chk_aaa...',
'chk_bbb...',
);
console.log(diff.difference.netDeltaDiff);
console.log(diff.dailyDivergence.length);
Automation Cadence
Checkpoint automation supports three cadence windows:
monthlyweekly(ISO week, Mon-Sun UTC)daily(previous UTC day)
In v1, daily cadence is gated to Enterprise tier records. Automatic runs remain idempotent at the checkpoint identity layer.