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

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:

1

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.

2

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:

  • periodFee is the fee per billing period, in the minor units of currency. Every billing period is one month. Divide by 100 for a currency with 2 decimal places: 4900 is $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.

  • trialDays is 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 items prices one metric. includedLimit is the usage included in the fee. quota is a soft limit on usage: usage may exceed it, and Billing doesn't block it. warningThresholds lists the percentages of the quota that quota warnings use.

  • pricingModel says how usage above the included limit is priced. SUBSCRIPTION means the fee covers it and there is no per-unit charge. FLAT charges usagePricing.price per unit, in minor units: in the example, $3.00 per device above the 10 included. TIERED and VOLUME price usage by usagePricing.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.

3

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.

4

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.

Code
When it occurs
Resolution

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

Last updated

Was this helpful?