Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.
ReferenceBeta

Plans

Reference for the plans your workspace can subscribe to: the myAvailablePlans query and the types that describe a plan's products, metrics, and prices.

The plans and branches the caller's workspace may subscribe to, with the subscription it already holds on each, and the catalog and pricing vocabulary a plan is built from: product domains, metrics, pricing models, and tiers.

Queries

myAvailablePlans

Lists the plans and branches the caller's own workspace may subscribe to, with the subscription it already holds on each.

The workspace is not an argument. It is the one the caller's token names, so this operation cannot be pointed at a tenant the token does not name. A token carrying no workspace claim is refused rather than answered: see Authentication.

Unpaginated: the answer is bounded by the catalogue a single workspace can see.

myAvailablePlans: [BillingAvailablePlan!]!

Output types:

BillingAvailablePlan

A plan or branch available to a workspace. When branchId is null this is a base plan; when set it represents a branch override.

Field
Type
Description

planId

ID!

The base plan ID.

branchId

ID

The branch ID (null for base plans).

title

String!

Human-readable title.

description

String

Optional description.

currency

ISO 4217 currency.

periodFee

What the plan charges per billing period regardless of usage, in currency. The sum of its per-schema fees — a branch's overrides where it sets them, the base plan's fee elsewhere.

trialDays

Int

Must be a positive integer if provided; null means no trial.

items

Pricing items. For base plans — plan items; for branches — branch override items.

subscription

The workspace's own subscription to this exact plan and branch, or null when it holds none. Only an ACTIVE subscription counts: a cancelled one must not render as subscribed. Matched on the pair — a subscription to a branch does not mark the base plan as taken, and the reverse.


Objects

BillingProductDomain

A billable product in the billing catalog.

Implements: Node, Versioned

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking.

code

Machine-readable product code.

title

String

Optional human-readable title.

description

String

Optional description.

isActive

Boolean!

Whether this product is active.

isBillable

Boolean!

Whether this product may take part in plans. True by default. When false, no new plan may include the product. Plans that already include it stay in force, but an update that resends their pricing schemas is refused.

productUrl

String

The product's user-facing address: an absolute http or https URL. Null when not set.

internalPath

String

The product's internal path: an absolute http or https URL, or a path starting with a single '/'. Null when not set.


BillingMetric

A billable metric.

Implements: Node, Versioned

Field
Type
Description

id

ID!

A globally unique identifier. This ID is opaque and should not be parsed by clients.

version

Int!

The version number for optimistic locking.

code

Machine-readable metric code.

title

String

Optional human-readable title.

description

String

Optional description.

unit

String

Optional measurement unit (for example: count, GB, requests).

isActive

Boolean!

Whether this metric is active.


BillingUsagePricing

Final usage pricing for a plan item. Fields depend on the parent pricingModel.

Field
Type
Description

price

Price per unit in minor currency units (FLAT model).

tiers

Pricing tiers (TIERED and VOLUME models).

pricingDimension

String

Attribute used to select the pricing tier, for example: device_count (VOLUME).

pricingDimensionAggregation

How pricing dimension values are aggregated (VOLUME).


BillingUsagePricingTier

A tier in a plan's tiered or volume pricing.

Field
Type
Description

from

Float!

Lower bound of the tier (inclusive).

to

Float

Upper bound of the tier: exclusive for TIERED, where the next tier starts, and inclusive for VOLUME; null means unlimited.

price

Price for this tier in minor currency units.


BillingAvailablePlan

A plan or branch available to a workspace. When branchId is null this is a base plan; when set it represents a branch override.

Field
Type
Description

planId

ID!

The base plan ID.

branchId

ID

The branch ID (null for base plans).

title

String!

Human-readable title.

description

String

Optional description.

currency

ISO 4217 currency.

periodFee

What the plan charges per billing period regardless of usage, in currency. The sum of its per-schema fees — a branch's overrides where it sets them, the base plan's fee elsewhere.

trialDays

Int

Must be a positive integer if provided; null means no trial.

items

Pricing items. For base plans — plan items; for branches — branch override items.

subscription

The workspace's own subscription to this exact plan and branch, or null when it holds none. Only an ACTIVE subscription counts: a cancelled one must not render as subscribed. Matched on the pair — a subscription to a branch does not mark the base plan as taken, and the reverse.


BillingAvailablePlanItem

A pricing item in the available-plans list. For base plan items branchItemId is null; for branch overrides it is set and planItemId references the base plan item.

Field
Type
Description

planItemId

ID!

The base plan item ID.

branchItemId

ID

The branch item ID (null for base plan items).

metric

The metric being priced.

aggregationFunction

How metric values are aggregated.

includedLimit

Float

Free usage included in the period fee.

quota

Float

Soft usage limit.

warningThresholds

[Int!]

Percentage thresholds for quota warnings.

pricingModel

The pricing model.

usagePricing

Usage pricing details (base or custom override).


Enums

BillingAggregationFunction

Function used to aggregate metric values over a billing period.

Values: SUM, MAX, MIN, AVG, LAST, MEDIAN


BillingPricingModel

The pricing model for a metric.

Value
Description

FLAT

Fixed price per unit.

TIERED

Usage is split across tiers; each tier has its own price.

VOLUME

All usage is priced at the tier the total falls into.

SUBSCRIPTION

Included in the subscription fee; no per-unit charge.


See also

Last updated

Was this helpful?