> For the complete documentation index, see [llms.txt](https://navixy.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://navixy.com/docs/navixy-graphql-api/products/billing/api-reference/plan.md).
# Plans
Reference for the plans a workspace may subscribe to: the myAvailablePlans query, the BillingAvailablePlan and BillingAvailablePlanItem types, and the product domains, metrics, and pricing vocabulary
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](/docs/navixy-graphql-api/authentication.md).
Unpaginated: the answer is bounded by the catalogue a single workspace can see.
```graphql
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` | [Currency](/docs/navixy-graphql-api/core-api-reference/common.md#currency)! | [ISO 4217](https://www.iso.org/standard/4217.html) currency. |
| `periodFee` | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)! | 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` | \[[BillingAvailablePlanItem](#billingavailableplanitem)!]! | Pricing items. For base plans — plan items; for branches — branch override items. |
| `subscription` | [BillingWorkspaceSubscription](/docs/navixy-graphql-api/products/billing/api-reference/subscription.md#billingworkspacesubscription) | 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](/docs/navixy-graphql-api/core-api-reference/common.md#node), [Versioned](/docs/navixy-graphql-api/core-api-reference/common.md#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` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#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](/docs/navixy-graphql-api/core-api-reference/common.md#node), [Versioned](/docs/navixy-graphql-api/core-api-reference/common.md#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` | [Code](/docs/navixy-graphql-api/core-api-reference/common.md#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` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long) | Price per unit in minor currency units (FLAT model). |
| `tiers` | \[[BillingUsagePricingTier](#billingusagepricingtier)!] | Pricing tiers (TIERED and VOLUME models). |
| `pricingDimension` | `String` | Attribute used to select the pricing tier, for example: device\_count (VOLUME). |
| `pricingDimensionAggregation` | [BillingAggregationFunction](#billingaggregationfunction) | 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` | [Long](/docs/navixy-graphql-api/core-api-reference/common.md#long)! | 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` | [Currency](/docs/navixy-graphql-api/core-api-reference/common.md#currency)! | [ISO 4217](https://www.iso.org/standard/4217.html) currency. |
| `periodFee` | [Money](/docs/navixy-graphql-api/core-api-reference/common.md#money)! | 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` | \[[BillingAvailablePlanItem](#billingavailableplanitem)!]! | Pricing items. For base plans — plan items; for branches — branch override items. |
| `subscription` | [BillingWorkspaceSubscription](/docs/navixy-graphql-api/products/billing/api-reference/subscription.md#billingworkspacesubscription) | 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` | [BillingMetric](#billingmetric)! | The metric being priced. |
| `aggregationFunction` | [BillingAggregationFunction](#billingaggregationfunction)! | 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` | [BillingPricingModel](#billingpricingmodel)! | The pricing model. |
| `usagePricing` | [BillingUsagePricing](#billingusagepricing)! | 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`
***
### 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
* [Pagination](/docs/navixy-graphql-api/pagination.md)
* [Filtering and sorting](/docs/navixy-graphql-api/filtering-and-sorting.md)
* [Error handling](/docs/navixy-graphql-api/error-handling.md)
* [Optimistic locking](/docs/navixy-graphql-api/optimistic-locking.md)
* [Limits](/docs/navixy-graphql-api/limits.md)
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.
Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:
```
GET https://navixy.com/docs/navixy-graphql-api/products/billing/api-reference/plan.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.