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 · 30 days · unlimited test API usage
Production	$44.99 per company file / month	Unlimited production API usage
Enterprise	Tailored	Volume pricing for many company files · priority support · contact sales

Enterprise pricing is arranged directly and isn't sold through Stripe Checkout. Connecting many company files, or want volume pricing before you commit? Email sales@tenkeybridge.com with roughly how many company files you expect and we'll quote a per-file rate.

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.

A trial lasts 30 days from when the organization was created, with no usage cap during that window: test API traffic is unlimited for the one connected realm. TenkeyBridge emails the organization's owner(s) twice — a reminder 7 days before the trial ends, and a notice once it has — and the portal shows a countdown banner over the same window, which stays up and turns red once the trial has ended. Once the trial ends, /v3 calls return 402 SUBSCRIPTION_REQUIRED (below) until the organization subscribes. Subscribing at any point 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 (30 days after the organization was created), the trial has more than one realm connected (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"
  }
}

When the cause is specifically a trial that ran out, Message and Detail instead read "This company's organization's TenkeyBridge trial has ended." (with the same docsUrl suffix on Detail) — naming the trial expiry distinctly from the generic "no active subscription" case above.

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.