Billing API

Authentication and identifiers

Use the implemented HTTP interface at https://api.atrium.st/v0/billing. There is no released atrium.billing.* SDK to import. Requests require an authenticated Atrium workspace session; examples use Authorization: Bearer <workspace-access-token> and Content-Type: application/json.

agent is the app's agnt_... identifier or UUID, not its display name or slug. Entitlement keys match the manifest catalog. The authenticated session determines the workspace; do not trust a browser-supplied workspace ID as authorization.

Make enforcement calls from your trusted application backend before doing restricted work. Keep credentials out of browser bundles and public logs. Enrollment in an explicit Free plan is required just as it is for a paid subscription.

Check feature access

POST /v0/billing/require
Authorization: Bearer <workspace-access-token>
Content-Type: application/json

{"agent":"<agent-id>","entitlement_key":"priority_support"}

{"allowed":true}

require answers whether the active plan includes the feature. It returns allowed:false when there is no active subscription or the feature is unavailable. For numeric entitlements, it does not check the remaining quota: an exhausted but included feature can still return allowed:true.

Read a numeric balance

POST /v0/billing/balance
Authorization: Bearer <workspace-access-token>
Content-Type: application/json

{"agent":"<agent-id>","entitlement_key":"pdf_exports"}

Example response for a monthly quota of 50 after seven exports:

{"allowed":50,"used":7,"remaining":43,"period":"month"}

Here allowed is a quantity, unlike the boolean field returned by require. period is month or lifetime. Monthly metering uses UTC calendar months. Display a balance as a snapshot; another request can consume quota before the user acts. Do not use a balance read as the authorization to consume it.

Consume a quantity

POST /v0/billing/consume
Authorization: Bearer <workspace-access-token>
Content-Type: application/json

{
  "agent":"<agent-id>",
  "entitlement_key":"pdf_exports",
  "quantity":1,
  "idempotency_key":"export-job-123"
}

{"allowed":50,"used":8,"remaining":42,"deduplicated":false}

Use a positive integer quantity and a stable idempotency key for one logical operation. Retry an uncertain request with the same key and quantity; use a new key only for a new operation. deduplicated:true indicates a previously recorded consumption was recognized.

Consumption records usage; it is not a reservation and has no paired release/refund operation in this interface. Design your application job retries and failure handling around that limitation. A successful usage call does not make your application work itself idempotent.

Start subscription checkout

POST /v0/billing/checkout
Authorization: Bearer <workspace-access-token>
Content-Type: application/json

{
  "agent":"<agent-id>",
  "offering":"pro",
  "price":"monthly",
  "success_url":"https://my-agent.atrium.st/billing/success",
  "cancel_url":"https://my-agent.atrium.st/billing/cancel",
  "idempotency_key":"checkout-request-123"
}

For subscription checkout, the response includes url and session_id. Redirect the customer to the returned URL. Offering and price are stable manifest keys, not provider IDs.

The checkout URL and success redirect are not proof of payment or access. On return, re-read the workspace's authoritative subscription/entitlement state before unlocking a feature. Keep a processing or retry state when confirmation has not arrived. Your app does not need to implement Atrium's payment provider webhook or expose a provider secret to the customer.

Errors and availability

Result	Meaning and response
require with allowed:false	Show the feature requirement or enrollment action.
402 from balance/consume	No eligible subscription, missing metered feature, or exhausted quota.
400 from checkout	The checkout request or offering/price selection could not be accepted.
401 / 403	Check authentication and the selected workspace's permissions.
422	Check the request schema and required fields.

One-time checkout is recognized by the API, but credit fulfillment and mixed plan-plus-credit consumption have unresolved reliability issues. Do not treat returned purchase fields or a balance as a production-ready paid-credit integration. There is no public purchase-history, reservation/release, or refund/dispute-reversal API documented here. Confirm availability before building those workflows.