PacSpace Docs

Python SDK

Install and use pacspace-sdk for Python services and jobs.

The Python SDK gives Python services the same core Balance API flow as the TypeScript SDK.

Use it to record usage, wait for verification, derive balances, compare views, checkpoint periods, and verify webhook signatures.

Install

bash
pip install pacspace-sdk

Requires Python 3.10 or later.

Create A Client

python
import os
from pacspace_sdk import PacSpace

pac = PacSpace.init(
    os.environ["PACSPACE_API_KEY"],
    production_url="https://app.pacspace.io",
)

Use a pk_live_* key for Production. Use a pk_test_* key for Sandbox and pass the Sandbox URL from your PacSpace dashboard.

Record Usage

python
emit = pac.balance.emit(
    "cust_acme",
    -42.5,
    "compute_minutes",
    {
        "referenceId": "usage_2026_05_001",
        "metadata": {
            "product": "inference",
            "units": 50,
        },
    },
)

print(emit["recordId"])
print(emit["receiptId"])
print(emit["status"])

emit() returns immediately. Store recordId for status checks and receiptId for proof lookup.

To wait for a terminal result:

python
verified = pac.balance.emit_and_wait(
    "cust_acme",
    -42.5,
    "compute_minutes",
    {
        "timeout": 30_000,
        "pollInterval": 1_000,
    },
)

print(verified["status"])

Derive A Balance

python
balance = pac.balance.derive(
    "cust_acme",
    {
        "period": "2026-05",
    },
)

print(balance["computedBalance"])
print(balance.get("deltaCount") or balance.get("deltasCount"))

Common-window helpers are also available:

python
pac.balance.derive_current_month("cust_acme")
pac.balance.derive_for_period("cust_acme", "2026-05")
pac.balance.derive_months_back("cust_acme", 3)

Compare Two Views

python
report = pac.balance.compare(
    "cust_acme",
    {
        "yours": 95000,
        "theirs": 98000,
    },
    {
        "period": "2026-05",
    },
)

print(report["neutralBalance"])
print(report["matchesYours"])
print(report["matchesTheirs"])

Compare tells you whether either submitted view matches the balance PacSpace derives from verified deltas.

Checkpoint A Period

python
checkpoint = pac.balance.checkpoint(
    "cust_acme",
    {
        "period": "2026-05",
    },
)

print(checkpoint["proofRoot"])
print(checkpoint["deltaCount"])
print(checkpoint["status"])

A checkpoint gives the period a single proof root that can be included with an invoice or close package.

Receipts

Python 0.2.0 supports customer-scoped receipt data:

python
receipt = pac.balance.receipt(
    "cust_acme",
    {
        "period": "2026-05",
    },
)

print(receipt["proofRoot"])
print(receipt.get("verifyUrl"))
print(receipt.get("verificationApiUrl"))
print(receipt.get("verificationExplorerUrl"))

verificationExplorerUrl remains a public response field. Keep it if your integration already stores it.

Customer Records

Every new customer_id passed to emit() creates a customer record.

python
customers = pac.balance.customers(
    {
        "search": "cust_",
        "limit": 25,
    },
)

customer = pac.balance.customer(
    "cust_acme",
    {
        "period": "2026-05",
    },
)

print(len(customers["customers"]))
print(customer["computedBalance"])

Dashboard customer helpers are also available on pac.customers. They use Dashboard API credentials, not Balance API keys.

Client-Side Submission Helpers

The SDK includes optional client-side helpers for integrations that summarize usage before sending it.

python
pac.balance.queue_summary(
    {
        "customerId": "cust_acme",
        "delta": -100,
        "reason": "daily_usage",
        "referenceId": "usage_day_2026_05_27",
    }
)

result = pac.balance.flush_summaries()

print(result["accepted"])
print(result["failed"])

These helpers run in your application process. They are not required for normal emit() usage.

Webhook Verification

python
from pacspace_sdk import Webhooks

webhooks = Webhooks(os.environ["PACSPACE_WEBHOOK_SECRET"])

event = webhooks.verify_from_headers(headers, raw_body)

if event["event"] == "delta.verified":
    print(event["data"]["receiptId"])

The verifier checks x-pacspace-signature and x-pacspace-timestamp against the raw request body.

Errors

All SDK errors extend PacSpaceError.

python
from pacspace_sdk import PacSpaceError, RateLimitError, ValidationError

try:
    pac.balance.emit("cust_acme", -100, "usage")
except RateLimitError as err:
    print(f"Retry after {err.retry_after} seconds")
except ValidationError as err:
    print(err)
except PacSpaceError as err:
    print(err.code)

Parity Notes

Python 0.2.0 covers the core Recordation flow: emit, wait, derive, compare, checkpoint, customer records, customer-scoped receipts, usage, webhook delivery helpers, and webhook signature verification.

The TypeScript SDK currently has helpers that Python does not yet expose:

  • receipts.* receipt-document helpers by receipt ID
  • checkpoint timeline helpers
  • checkpoint diff helpers

Use the REST API directly for those workflows until the next Python SDK release adds helper methods.

Package Details

DetailValue
PyPI packagepacspace-sdk
Current docs target0.2.0
RuntimePython 3.10+
LicenseMIT
Public sourcePacSpace/python-sdk

Next Steps

Previous

TypeScript SDK

Next

Emit - Record a Delta