Subscriptions API

The Subscriptions API manages a tenant's annual credit subscription. Customers purchase credits that are valid for a full year and draw down from a shared credit pool as the platform is used. Subscriptions, credit packs, and billing settings are managed through the License Manager; Informer proxies those operations and keeps a local entitlement cache in sync. All routes are prefixed with /api.

This API covers buying and managing credits. For how credits are governed (usage profiles, model tiers, per-actor caps) and reported, see Usage & Credits.

Authentication

All endpoints require the billing.manage permission.

Cache sync contract

Money-touching endpoints (_cancel, _reactivate, _purchase, _convert-dollars) refresh the local AiEntitlementCache after the License Manager call and return a cacheUpdated boolean. cacheUpdated: false means the License Manager operation succeeded but the local cache is momentarily stale — the client should trigger its own refresh rather than show an unconditional success.

---

GET /api/usage/subscription

Get the active subscription for the current license from the License Manager.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Response:

Proxied from the License Manager. Representative shape:

{
  "id": "sub-123",
  "status": "active",
  "term": "annual",
  "creditsIncluded": 50000,
  "renewsAt": "2027-05-23T00:00:00Z",
  "cancelAtPeriodEnd": false,
  "cardLast4": "4242",
  "createdAt": "2026-05-23T00:00:00Z"
}

---

POST /api/usage/subscription/_cancel

Schedule cancellation of the subscription at the next renewal date. Credits remain spendable until the end of the current annual term.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Response:

The updated subscription, plus the cache-sync flag:

{
  "id": "sub-123",
  "status": "active",
  "cancelAtPeriodEnd": true,
  "renewsAt": "2027-05-23T00:00:00Z",
  "cacheUpdated": true
}

---

POST /api/usage/subscription/_reactivate

Undo a pending cancellation.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Response:

The updated subscription with cancelAtPeriodEnd: false, plus cacheUpdated.

---

GET /api/usage/subscription/proration-preview

Preview the prorated charge for changing to a different credit pack mid-term. Read-only — both this preview and the eventual purchase route through the same License Manager calculation, so the figures shown match what the customer is billed.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Query Parameters:

Parameter	Type	Required	Description
packSlug	string	Yes	Slug of the target credit pack

Response:

{
  "daysRemaining": 210,
  "dailyRate": 1.37,
  "prorationAmount": 287.70
}

---

GET /api/usage/credit-packs

List the credit packs available for purchase from the License Manager.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Response:

Proxied from the License Manager. Representative shape:

{
  "creditPacks": [
    { "slug": "credits-50k", "name": "50,000 Credits", "credits": 50000, "price": 500.00 },
    { "slug": "credits-100k", "name": "100,000 Credits", "credits": 100000, "price": 900.00 }
  ]
}

---

POST /api/usage/_purchase

Purchase a credit pack. On success the new balance is written straight into the entitlement cache so the credits are immediately visible.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Request Body:

Field	Type	Required	Description
packSlug	string	Yes	Credit pack slug
cardId	string	Yes	Payment card token
quantity	integer	No	Number of packs (min 1, default 1)

Example Request:

{ "packSlug": "credits-50k", "cardId": "card-token-xyz", "quantity": 1 }

Response:

The License Manager purchase response (including the authoritative balance object) plus cacheUpdated:

{
  "balance": { "included": 100000, "used": 12340, "remaining": 87660 },
  "cacheUpdated": true
}

---

POST /api/usage/_convert-dollars

Promote legacy dollar-unit credits (from pre-3.0.0 balances) into the spendable credit pool. One-way migration.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Response:

The License Manager response (with the post-conversion balance) plus cacheUpdated. The local cache is patched with legacyDollars: 0 so the "Convert" prompt disappears immediately.

---

GET /api/usage/billing-config

Get the auto-replenish and alert settings from the License Manager.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Response:

{
  "replenish": {
    "enabled": true,
    "paygDollars": 100,
    "cardId": "card-token-xyz",
    "monthlyCap": 5
  },
  "alerts": {
    "recipients": ["admin@example.com"],
    "thresholds": { "80": true, "90": true, "95": true, "exhausted": true }
  }
}

---

PUT /api/usage/billing-config

Update auto-replenish and alert settings.

Authentication: Required (session)

Pre-blocks: permission.billing.manage

Request Body:

Field	Type	Description
replenish.enabled	boolean	Enable pay-as-you-go auto-replenish
replenish.paygDollars	integer | null	Dollars to spend each time auto-refill fires (20–10000)
replenish.cardId	string | null	Payment card token
replenish.monthlyCap	integer	Max auto-refills per month (1–10)
alerts.recipients	string[]	Email recipients for usage alerts
alerts.thresholds	object	Toggle alerts at 80, 90, 95 percent, and exhausted

Response:

Returns the updated billing configuration (same shape as GET).

---

Subscription lifecycle

1. Purchase — buy a credit pack; credits are valid for the annual term
2. Active — credits draw down from the pool as the platform is used (see Usage & Credits)
3. Auto-replenish (optional) — pay-as-you-go top-ups fire when the pool runs low, subject to the monthly cap
4. Cancellation — scheduled at period end; credits remain spendable until the term expires
5. Reactivation — undo a pending cancellation before the term ends

Related APIs

• Usage & Credits — usage profiles, entity budgets, and consumption reporting
• Teams — assign usage profiles to teams