Choosing a plan and subscribing
List the plans your workspace may subscribe to and what each one charges, subscribe your workspace to the plan you choose, and confirm the subscription.
This guide shows how to choose a plan for your workspace and subscribe to it through the Billing API. You will list the plans open to your workspace and read what each one costs and includes, then subscribe your workspace and confirm the result.
Every operation on this page reads or changes the data of the workspace named by your access token. You never pass a workspace ID, so a request can't subscribe a workspace that the token doesn't name.
Prerequisites
You need an access token whose workspace_id claim names the workspace. The Billing my* operations, the operations named with the prefix my such as myAvailablePlans and mySubscribe, read that claim. Without it, they refuse the request. See Authentication to learn how the API identifies the workspace.
To check that the token names a workspace and that Billing accepts it, run this query and list the subscriptions that the workspace already has:
query CurrentSubscriptions {
billing {
mySubscriptions(filter: { status: ACTIVE }, first: 10) {
nodes {
id
planId
branchId
subscribedAt
trialExpiresAt
}
total {
count
}
}
}
}Response for a workspace that has no subscription:
An empty list is a valid response. A PERMISSION_DENIED error instead means that the token has no workspace claim. See Error handling.
How plans and subscriptions work
This guide uses 2 important concepts: plans and subscriptions. Plans and Subscriptions document every field.
A plan is what a workspace pays for: a fee per billing period, plus a price for the usage of each metered product. A plan may have branches, which are variants of the plan with their own price. Billing offers a branch as its own row, next to the base plan or in its place, so you choose a row, not a plan and then a branch. myAvailablePlans lists every row currently open to your workspace. An archived plan, a plan outside its active dates, or a plan reserved for other workspaces won't be there.
A subscription is the link between a workspace and one row: the plan and the branch when the row is a branch. A subscription is ACTIVE until it is cancelled. Cancelling and switching aren't part of this API. Contact Navixy at [email protected] to perform them.
Example scenario: A fleet operator moves to a larger plan
TransLog GmbH runs delivery trucks out of Hamburg. On July 1, 2026, their workspace has no active subscription: Navixy cancelled the Basic plan that the workspace started on, at TransLog's request. TransLog has more devices than Basic includes, so their administrator chooses a plan that covers more devices through the API. To subscribe the workspace, follow these steps:
Read the plans open to the workspace
myAvailablePlans returns every row the workspace may subscribe to, with the subscription that the workspace already has on each. The list isn't paginated, because a workspace sees a small catalogue.
Run this query:
Response:
The workspace sees 3 rows: the Basic plan, the Fleet Pro plan, and one branch of Fleet Pro for large fleets. A branch row has the same planId as its base plan and its own branchId. No row has a subscription, because the workspace has no active subscription. When it has one, that row has a subscription.
Render each row with its price and limits
Read what each row costs and what it includes. Every amount of a row is in the row's currency. These fields set the price, and the items set the limits:
periodFeeis the fee per billing period, in the minor units ofcurrency. Every billing period is one month. Divide by 100 for a currency with 2 decimal places:4900is $49.00. This value is the sum of the fees of every product in the plan. When a branch sets its own fee for a product, that fee replaces the base plan's fee for the product.trialDaysis the length of the trial that a new subscription gets. A trial is granted once per plan: a workspace that already had a trial on Fleet Pro or on one of its branches will resubscribe without a trial.Each entry of
itemsprices one metric.includedLimitis the usage included in the fee.quotais a soft limit on usage: usage may exceed it, and Billing doesn't block it.warningThresholdslists the percentages of the quota that quota warnings use.pricingModelsays how usage above the included limit is priced.SUBSCRIPTIONmeans the fee covers it and there is no per-unit charge.FLATchargesusagePricing.priceper unit, in minor units: in the example, $3.00 per device above the 10 included.TIEREDandVOLUMEprice usage byusagePricing.tiers. Plans define each model.
In the example, Basic includes 5 devices at no charge, with a quota of 5. Fleet Pro costs $49.00 per month, includes 10 devices, and charges $3.00 for each device above that, with a quota of 500. Its fee also covers registered assets, with no per-unit charge.
The large fleet branch costs $149.00 per month, includes 50 devices, and charges $2.00 for each device above that, with a quota of 1,000. The branch row lists only the items that the branch changes, so it shows the device item alone. A subscription to the branch uses the branch's fee and device item, and the base plan's asset item. For a fleet of more than 43 devices, the branch costs less than the base plan.
Billing applies the fee and the prices on the invoice of each billing period: the fee, and the usage above the included limit at the plan's price. The invoice total is charged to the balance. See Reading invoices to learn what an invoice charges. The quota doesn't limit usage: Billing accepts usage above the quota, and the Billing API returns no warning when usage reaches a threshold. See Coming soon on the overview.
Subscribe your workspace to the plan you chose
mySubscribe subscribes the workspace named by the token. The input takes the row's planId and, for a branch row, its branchId. Leave branchId out to subscribe to the base plan.
TransLog has 11 devices. On the base plan, that's $49.00 plus $3.00 for 1 device above the included 10, which costs less than the branch. TransLog chooses the Fleet Pro row, so the mutation leaves out branchId. Run this mutation:
Response:
The subscription starts at once and has a trial that ends 14 days later. expiresAt is the end date of the branch when the subscription is on a branch that has one, otherwise null. The trial makes the fee free until July 15, so the first invoice, issued on August 1, charges the fee only for the part of July after the trial. See Reading invoices to read that invoice.
Before Billing accepts the subscription, it checks the row. The plan, or the branch, must be one that myAvailablePlans offers the workspace. The branch must belong to the plan. And no product of the plan may be covered by an active workspace subscription. A workspace has one active subscription per product, and this API doesn't replace one. Read the rows from myAvailablePlans in the same session and send planId and branchId as they came, so that the first 2 checks pass. For the third, see Error handling.
Confirm the subscription
Read the active workspace subscriptions again. The new subscription is first, because the list is ordered by SUBSCRIBED_AT descending by default:
Response:
The new subscription is the only active one. Run myAvailablePlans again, and the Fleet Pro row now has a subscription, while the Basic row and the branch row have none. A subscription to the base plan doesn't mark the branch row as taken.
Listing past subscriptions
mySubscriptions returns cancelled subscriptions too. Omit the status filter to list both, or filter by planId to show the history of one plan:
Response:
The filter has 2 fields, planId and status, and they combine with AND. The list orders by SUBSCRIBED_AT only. See Pagination for the cursor rules.
mySubscriptions returns subscriptions that myAvailablePlans doesn't show. A subscription to a plan that was archived later, or whose active dates have passed, is absent from the catalogue but still in effect. To show what the workspace is on, read mySubscriptions, not the subscription field of the catalogue rows.
Error handling
The Billing operations return errors in the shared format. See Error handling for the response structure and the general codes.
PERMISSION_DENIED
The token has no workspace_id claim, or the claim isn't a workspace ID.
Request a token issued for the workspace.
VALIDATION_ERROR
The plan or the branch isn't a row that myAvailablePlans offers the workspace: it is archived, outside its active dates, reserved for other workspaces, or the branch belongs to another plan.
Read myAvailablePlans again and send planId and branchId from one of its rows.
VALIDATION_ERROR
A product of the plan is covered by an active subscription of the workspace. This API doesn't replace it.
Read the active subscription from mySubscriptions. To cancel or switch it, contact Navixy at [email protected].
VALIDATION_ERROR
The workspace_id claim names a workspace that this deployment doesn't have.
Request a token for a workspace of this deployment.
When an active subscription already covers a product of the plan, the mutation returns this error. For example, a second subscription to Fleet Pro, while the subscription from the scenario is active, returns this error:
How to handle a product conflict
Read the subscription IDs in detail and look them up in mySubscriptions. Your workspace already has a subscription that covers a product of the plan you chose. To move to the new plan, contact Navixy at [email protected]: switching and cancelling a subscription aren't in this API. To avoid the error, check mySubscriptions(filter: { status: ACTIVE }) before you subscribe.
See also
Plans: Learn how the rows of the catalogue, their items, and the pricing vocabulary work.
Subscriptions: Learn how mySubscribe, mySubscriptions, and the subscription type work.
Reading balance and statement: Read the workspace's prepaid balance and the entries that changed it.
Billing errors: Learn how the Billing operations report a missing entity and which fields their errors have.
Authentication: Learn how the token names the workspace that every operation acts in.
Last updated
Was this helpful?