Helium MVNEdocs

Tax

Helium MVNE connects to your telecom-tax engine and applies the rates it returns to the charges it bills. Tax engines plug in as connectors: Avalara Communications Tax (CommTax) is the first connector available, with more on the way. You bring your own Avalara account; Helium MVNE provides the integration layer and the per-jurisdiction breakdown on every charge.

Like carrier credentials, the tax connection is configured from the operator dashboard. It's environment-scoped and resolved on every call, so sandbox and live each carry their own engine and credentials.

Sandbox vs live

  • Sandbox uses a built-in connector that returns a single flat-rate line — no account required, so tax-shaped responses work the moment you start building.
  • Live uses Avalara CommTax with your account's credentials (endpoint, account/license key, client profile). Add it from the dashboard; on save, Helium MVNE runs a verify round-trip and surfaces any credential issues before the connection goes active.

Classifying products

Tax engines price by what is being sold, so Helium MVNE keeps that classification as data on your catalog:

  • tax_code on plans and addons — the engine's product classification. For Avalara CommTax this is a transaction/service bundle pair: { "transaction": 20000, "service": 20001 } (an optional client_profile_id pins the CommTax client profile whose custom bundles apply). Defaults to a standard wireless-plan bundle.
  • tax_exempt on subscribers — when true, Helium MVNE skips tax calculation for that customer's charges.
POST /v1/plans
  name, carrier_profile_code, price_cents,
  tax_code?: { transaction, service, client_profile_id? }

PATCH /v1/subscribers/{id}
  tax_exempt: true

Quote vs. commit

When Helium MVNE bills a subscriber it calls the connector in two modes:

  • Quote during pricing previews and invoice assembly — calculates the breakdown (federal, state, local, regulatory) without recording a liability.
  • Commit when a charge settles — records the transaction so it rolls up into your operator's filing obligation for the period.

The returned per-jurisdiction lines attach to the invoice as individual tax line items. These run inside the billing path once a tax connection is active for the environment — there's nothing to call directly.