Tax

heliumOS 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; heliumOS 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, heliumOS 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 heliumOS 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, heliumOS skips tax calculation for that customer's charges.
• tax_comped on plans — when true, tax is still calculated and still filed, but an equal credit line is added to the invoice so the subscriber pays none of it. You absorb the liability rather than waive it.

Exempt or comped?

These look identical on the customer's bill and are very different to your tax authority.

Use tax_exempt when the customer genuinely owes no tax — a government or reseller account with an exemption certificate on file.

Use tax_comped when the tax is owed and you have chosen to absorb it. The usual case is a free plan: telecom regulatory fees (E911, 911/988 surcharges, FCC recovery) are assessed per active line rather than on price, so a price_cents: 0 plan still generates real tax. Mark it exempt and you under-file; leave it alone and you bill a customer for a plan you told them was free.

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 heliumOS 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.

Related

• Plans & addons — where tax_code lives.
• Subscribers & subscriptions — tax_exempt and service addresses.
• Carrier connections — the same dashboard-managed, environment-scoped credential pattern.