Billing tools
One tool reading an organization’s plan and how much of each allowance is left. It requires a signed-in person who is a member of the organization; a machine credential is refused. It reads and never changes anything: no plan change, no checkout.
get_organization_billing
Section titled “get_organization_billing”Get an organization’s billing plan and usage, the same figures the dashboard’s billing page shows.
| Name | Type | Required | Notes |
|---|---|---|---|
organization_id | string | yes |
Returns: { account: { lifecycle, subscription } | null, usage }, read through Organization.usageAndLimits.
| Field | Type | Notes |
|---|---|---|
lifecycle | object | { state, refusal }. state is one of ACTIVE, TRIAL, PAYMENT_GRACE, ON_HOLD, CANCEL_AT_PERIOD_END, CHECKOUT_PROCESSING, NO_SUBSCRIPTION or BILLING_UNAVAILABLE. refusal is the error code a costed action is refused with right now, or null when costed actions are open. |
subscription | object | null | { planDisplayName, planCode, source, status, cadence, currentPeriodStart, currentPeriodEnd, trialEnd, accessUntil, pendingPlanVersionId }. null with no subscription. |
usage | object | null | { meters }, with one usage meter per allowance: { entitlementKey, limit, consumed, reserved, available, periodStart, resetAt }. meters is an empty array when there are no current periods. usage is null when the meters could not be read. |
BILLING_UNAVAILABLE means the subscription could not be read, not that there is none.
After a tool is refused for quota, find the meter in usage.meters whose entitlementKey the refusal names: its
available is what is left, and its resetAt is when the allowance renews.
Returns an error block reading Organization "<id>" not found when no organization matches. Any
other refusal, such as one for an organization you are not a member of, comes back as an error
block carrying the Binclusive API’s message.