PacSpace API Docs

Billing & Usage

Monitor your plan usage, track verified deltas, and manage your subscription.

PacSpace uses a monthly subscription model. Each plan includes a set number of verified deltas per month. Use these endpoints to monitor your usage and plan details.

All routes require a valid JWT in the Authorization header:

bash
-H "Authorization: Bearer YOUR_JWT_TOKEN"

Base URL: https://balance-api.pacspace.io

Get Plan

Retrieve your current subscription plan details.

bash
curl https://balance-api.pacspace.io/dashboard/billing/plan \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK

json
{
  "statusCode": 200,
  "data": {
    "tier": "starter",
    "monthlyAllotment": 100000,
    "planPriceUsd": 3000,
    "overagePriceUsd": 0.012,
    "stripeSubscriptionId": "sub_1R...",
    "cancelAtPeriodEnd": false,
    "stripeCurrentPeriodEnd": "2026-03-13T00:00:00.000Z"
  }
}

Plan Fields

FieldDescription
tierYour current plan: free, pilot, starter, growth, scale, or enterprise
monthlyAllotmentVerified deltas included per month
planPriceUsdMonthly subscription price (in USD)
overagePriceUsdPer-delta rate if you exceed your allotment
stripeSubscriptionIdStripe subscription ID (null if no active subscription)
cancelAtPeriodEndWhether the subscription is scheduled for cancellation
stripeCurrentPeriodEndEnd date of the current period

Get Usage

Retrieve your monthly usage and overage status for the current or a specified period.

bash
curl https://balance-api.pacspace.io/dashboard/billing/usage \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Optionally specify a period:

bash
curl "https://balance-api.pacspace.io/dashboard/billing/usage?period=2026-01" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Query Parameters

ParameterTypeRequiredDescription
periodstringNoPeriod in YYYY-MM format. Defaults to the current period.

Response 200 OK

json
{
  "statusCode": 200,
  "data": {
    "period": "2026-02",
    "consumedDeltas": 1042,
    "overageCount": 0,
    "overageChargesUsd": 0,
    "remainingDeltas": 98958
  }
}

Usage Fields

FieldDescription
periodPeriod (YYYY-MM)
consumedDeltasVerified deltas used so far this period
overageCountDeltas consumed beyond the plan allotment (0 if within limit)
overageChargesUsdAccumulated overage charges for this period
remainingDeltasDeltas remaining in your allotment (0 if in overage)

Monitoring Usage

Via Webhooks

Each delta.verified webhook event includes usage data when available:

json
{
  "event": "delta.verified",
  "data": {
    "usage": {
      "plan": "growth",
      "includedDeltas": 500000,
      "consumedDeltas": 1042,
      "remainingDeltas": 498958,
      "overageRate": "$0.010/delta"
    }
  }
}

Set up a webhook endpoint to track consumption in real time.

Via Dashboard

View your usage, billing history, and plan details at app.pacspace.io.

Subscribe to a Plan

Start a new subscription for a self-serve tier (Pilot, Starter, Growth, or Scale). Returns a Stripe Checkout URL — redirect the user to complete payment.

bash
curl -X POST https://balance-api.pacspace.io/dashboard/stripe/create-subscription-session \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tier": "starter" }'

Request Body

FieldTypeRequiredDescription
tierstringYesOne of: pilot, starter, growth, scale

Response 201 Created

json
{
  "statusCode": 201,
  "data": {
    "url": "https://checkout.stripe.com/c/pay/..."
  }
}

Redirect the user to url. After successful payment, Stripe redirects back to the dashboard Billing page. The plan is activated immediately via webhook.

Change Plan

Upgrade or downgrade an existing subscription. The change takes effect immediately with proration. Usage does not reset mid-cycle.

bash
curl -X POST https://balance-api.pacspace.io/dashboard/stripe/change-plan \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "tier": "growth" }'

Request Body

FieldTypeRequiredDescription
tierstringYesOne of: pilot, starter, growth, scale

Response 200 OK

json
{
  "statusCode": 200,
  "data": {
    "subscriptionId": "sub_1R...",
    "status": "active"
  }
}

Requires an active subscription. If the tenant has no subscription, use the Subscribe endpoint first.

Open Customer Portal

Create a Stripe Customer Portal session for managing payment methods, viewing invoices, and downloading receipts.

bash
curl -X POST https://balance-api.pacspace.io/dashboard/stripe/create-portal-session \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 201 Created

json
{
  "statusCode": 201,
  "data": {
    "url": "https://billing.stripe.com/p/session/..."
  }
}

Redirect the user to url. The portal returns them to the dashboard Billing page when done.

Cancel Subscription

Schedule the subscription for cancellation at the end of the current period. Access continues until that date, then the account reverts to the Free tier.

bash
curl -X POST https://balance-api.pacspace.io/dashboard/stripe/cancel-subscription \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

Response 200 OK

json
{
  "statusCode": 200,
  "data": {
    "subscriptionId": "sub_1R...",
    "cancelAtPeriodEnd": true,
    "currentPeriodEnd": "2026-03-13T00:00:00.000Z"
  }
}

Usage Limits

Free Plan

The Free plan is hard-capped at 100 verified deltas (lifetime cap). Once exhausted, write operations return 402 Payment Required. Upgrade to a paid plan to continue.

Paid plans allow overage beyond the included allotment. Overages are billed at your plan's per-delta rate at the end of each period.

Endpoints Summary

EndpointMethodDescription
/dashboard/billing/planGETCurrent subscription plan details
/dashboard/billing/usageGETMonthly usage and overage status
/dashboard/stripe/create-subscription-sessionPOSTStart a new subscription (returns Checkout URL)
/dashboard/stripe/change-planPOSTUpgrade or downgrade an existing subscription
/dashboard/stripe/create-portal-sessionPOSTOpen Stripe Customer Portal (returns Portal URL)
/dashboard/stripe/cancel-subscriptionPOSTCancel subscription at period end

Previous

Environment Activation

Next

Write Operations