Billing

TenkeyBridge is billed per organization, through Stripe, based on how many company files (realms) that organization has connected. This page covers the plans, how the metering and enforcement actually work, what happens if a payment fails, and how to manage a subscription from the developer portal.

Where this fits

Billing is opt-in at the gateway level — a deployment with no Stripe configuration behaves exactly as it did before #92: every realm gets unlimited, unmetered API usage. This page describes the gateway's behavior once billing is configured; see Gateway ops for how that's set up.

Plans

Plan	Price	What you get
Trial	Free	1 connection for testing and development · unlimited test API usage
Production	$44.99 per company file / month	Unlimited production API usage
Enterprise	Tailored	Contact sales

Enterprise pricing is arranged directly — email sales@tenkeybridge.com — and isn't sold through Stripe Checkout.

How billing works

A Production subscription is metered by company file, not by API call volume: the subscription's Stripe line-item quantity is kept equal to the organization's realm count. Creating a new realm under an org with an active production subscription pushes an updated quantity to Stripe immediately (POST /admin/v1/realms → syncRealmQuantity); Stripe then prorates and bills the difference automatically for the current period. If that push ever fails transiently, it's self-healing — Stripe's own customer.subscription.updated webhook reconciles the stored quantity on its next delivery regardless.

There's no metering knob to configure and no usage-based overage charge: $44.99/company-file/month, however many requests that connection makes.

Trial limits

Every organization starts on the trial plan with no Stripe subscription at all. A trial organization may connect at most one realm. Trying to create a second realm on a trial org returns 409 plan_limit_realms from the Admin API — see Admin API errors — with a checkoutPath pointing at that org's checkout endpoint.

Trial has no time limit and no usage cap: test API traffic is unlimited for that one connected realm. Subscribing (below) lifts the one-realm limit and switches the organization to the Production plan.

What happens when payment fails

If a production subscription's invoice fails to collect, Stripe's invoice.payment_failed webhook moves the organization's status to past_due and starts a 7-day grace period (graceUntil, set the first time the org enters past_due — a second failed invoice within the same lapse doesn't push the deadline further out). API access is unaffected during the grace period.

If the grace period elapses without a successful payment, the organization loses entitlement (lapsed) and further API calls return 402 SUBSCRIPTION_REQUIRED — see below — until Stripe collects successfully (invoice.paid, which clears past_due and graceUntil immediately) or the subscription is otherwise canceled, at which point the organization is downgraded to trial rules (one realm, unmetered).

SUBSCRIPTION_REQUIRED

HTTP 402. Returned from the QBO-compatible REST surface (/v3/company/{realmId}/...) when the realm's organization is not entitled — no subscription, a trial over its one-realm limit, or a production subscription that's lapsed past its grace period. This code is enforced only when the gateway has BILLING_ENFORCE set to true (the default once billing is configured); with it set to false the same non-entitled state is logged, not blocked — see Gateway ops: rollout.

{
  "Fault": {
    "Error": [{
      "code": "SUBSCRIPTION_REQUIRED",
      "Message": "This company's organization has no active TenkeyBridge subscription.",
      "Detail": "This company's organization has no active TenkeyBridge subscription. See https://docs.tenkeybridge.com/guide/billing.html#subscription-required"
    }],
    "type": "ValidationFault"
  },
  "time": "2026-08-28T00:00:00.000Z",
  "tkb": {
    "code": "SUBSCRIPTION_REQUIRED",
    "causes": [
      "The company's organization has no active TenkeyBridge subscription — the trial ended (or more than one realm is connected on the trial plan, which is capped at one), or a production subscription's payment lapsed and stayed unpaid past the 7-day grace period."
    ],
    "fixes": [
      "Subscribe or manage billing for the organization in the TenkeyBridge portal.",
      "On a trial, each organization may connect at most one realm — upgrade to a paid plan to connect more."
    ],
    "docsUrl": "https://docs.tenkeybridge.com/guide/billing.html#subscription-required"
  }
}

Fix it the same way regardless of which cause applies: subscribe or bring the organization's billing current in the portal (next section).

Managing billing in the portal

Open an organization in the portal and go to Billing — see Portal: Billing for the full walkthrough. In short: any member can view the plan and 30-day usage; an admin or owner gets one action button that adapts to the org's current state — Subscribe (opens Stripe Checkout) when there's no active subscription, Manage billing (opens the Stripe Billing Portal — update the card, change the plan, cancel, or view invoices) once there is one, and a Contact sales link instead of either button for an Enterprise account.

If billing isn't configured on the gateway at all, the page says so ("Billing is not configured on this gateway.") instead of offering a button.

Enterprise

Enterprise plans are tailored and sold off-platform — there's no self-service Checkout for them, and POST .../billing/checkout for an account already on the Enterprise plan returns 409 enterprise_plan rather than starting a Stripe session. To move an organization onto Enterprise, email sales@tenkeybridge.com.