Balance API
Emit — Record a Delta
Record a credit or debit delta for a customer. PacSpace queues the delta, verifies it independently, and sends a webhook when complete.
Use this endpoint to record a balance change (delta) for a customer account. Each delta represents a credit or debit that PacSpace queues, independently verifies, and confirms via webhook.
Endpoint
POST https://balance-api.pacspace.io/api/v1/balance/delta
Headers
| Header | Required | Description |
|---|---|---|
X-Api-Key | Yes | Your PacSpace API key |
Content-Type | Yes | Must be application/json |
Request Body
| Parameter | Type | Required | Description |
|---|---|---|---|
customerId | string | Yes | Unique identifier for the customer account |
delta | number | Yes | Amount to adjust. Positive = credit, negative = debit |
reason | string | Yes | Human-readable reason for the adjustment (audit trail) |
referenceId | string | No | Your internal reference ID for correlation |
metadata | object | No | Arbitrary key-value metadata to store with the delta |
Examples
cURL
curl -X POST https://balance-api.pacspace.io/api/v1/balance/delta \
-H "X-Api-Key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"customerId": "cust_12345",
"delta": -1000,
"reason": "Monthly subscription charge",
"referenceId": "inv_98765",
"metadata": {
"invoiceId": "inv_98765",
"plan": "growth"
}
}'
JavaScript (Node.js)
const response = await fetch(
"https://balance-api.pacspace.io/api/v1/balance/delta",
{
method: "POST",
headers: {
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
body: JSON.stringify({
customerId: "cust_12345",
delta: -1000,
reason: "Monthly subscription charge",
referenceId: "inv_98765",
metadata: {
invoiceId: "inv_98765",
plan: "growth",
},
}),
}
);
const result = await response.json();
console.log(result);
Python
import requests
response = requests.post(
"https://balance-api.pacspace.io/api/v1/balance/delta",
headers={
"X-Api-Key": "YOUR_API_KEY",
"Content-Type": "application/json",
},
json={
"customerId": "cust_12345",
"delta": -1000,
"reason": "Monthly subscription charge",
"referenceId": "inv_98765",
"metadata": {
"invoiceId": "inv_98765",
"plan": "growth",
},
},
)
result = response.json()
print(result)
Response
{
"success": true,
"data": {
"anchorId": "a_1234567890",
"customerId": "cust_12345",
"delta": -1000,
"status": "QUEUED",
"receiptId": "0xabc123...",
"itemsRoot": "0xabc123...",
"message": "Delta queued for verification"
}
}
Response Fields
| Field | Type | Description |
|---|---|---|
anchorId | string | Unique identifier for this delta record |
customerId | string | The customer account this delta belongs to |
delta | number | The recorded adjustment amount |
status | string | Current processing status (starts as QUEUED) |
receiptId | string | Identifier for the verification receipt |
itemsRoot | string | Root hash of the data included in this batch |
message | string | Human-readable status message |
Status Lifecycle
Every delta moves through three stages:
-
QUEUED— The delta has been accepted and is waiting to be processed. This is the status returned immediately after a successful request. -
PROCESSING— PacSpace is actively verifying the delta. The system batches deltas for efficiency, so this stage may take a few seconds. -
VERIFIED— Verification is complete. The delta is now part of the customer's verified balance history and can be used in balance derivations.
Webhook Notification
When a delta reaches the VERIFIED status, PacSpace sends a delta.verified webhook to your configured endpoint. The webhook payload includes the full delta record with its final receiptId and itemsRoot, so you can update your own systems accordingly.
Tip: You don't need to poll for status. Configure a webhook endpoint in your PacSpace dashboard to receive real-time notifications when deltas are verified.
Last updated February 11, 2026