Plans & addons

An operator's plan catalog is built on top of heliumOS's carrier profiles — bundles of SLOs (data caps, throttle tiers, voice/SMS allowances) that a carrier makes available to MVNOs. T-Mobile profiles are shipped with the platform; you pick from them and price.

Carrier profiles vs plans

A plan is { carrier_profile_id, price, currency, billing_period, name, change_policy, addons[] }.

Addons

Addons extend a plan with optional SLOs (e.g. extra hotspot data, international calling). They're attached to a subscription, not to a plan — one plan can support many addon combinations.

POST /v1/subscriptions/{id}/addons
  addon_id, effective_at?

Plan changes

A subscription's plan is mutable. The plan's change_policy controls proration:

• immediate — effective now, prorated
• next_period — effective at next billing date, no proration
• end_of_term — effective at contract end (rare; for committed terms)

Plan changes that downgrade SLOs are subject to carrier validation — see the T-Mobile SLO catalog in the operator's carrier profile reference.

Coupons on prepaid terms

A plan can bill a prepaid term — several months charged upfront as one invoice — instead of a month at a time. Pass a coupon or a promotion_code on POST /v1/subscriptions, or on a plan change, and it is forwarded to the payment provider untouched whatever the plan's term. heliumOS never compares a coupon's duration against the term, and never limits how many discounts you stack.

A coupon's duration counts invoices, not service months. A coupon set to repeat for three months discounts every invoice raised inside that three-month window. On a six-month plan that is the whole term charge — six months of service at the discounted rate, not three. A one-time coupon behaves the same way: it discounts the entire next term invoice. On a monthly plan the same coupon discounts three monthly invoices, which is usually what the operator pictured when authoring it.

Size a coupon against the invoice you expect it to land on. When you want the discount to follow service months instead of billing dates, use a fixed amount sized to the term, or sell the plan monthly.