Helium MVNEdocs

Subscribers & subscriptions

A subscriber is the end-user record you create on behalf of your operator. A subscription links a subscriber to a plan and is the billable unit — one subscriber can hold multiple subscriptions over their lifetime.

Subscribers

POST /v1/subscribers
  email, name, phone?, metadata?

Subscribers are environment-scoped. The same email can exist in sandbox and live independently. Subscribers have addresses (shipping

  • service) attached via POST /v1/subscribers/{id}/addresses.

Subscribers are records, not auth principals. End-users never hold a Helium MVNE token. They authenticate with your mobile app, and your backend calls Helium MVNE server-to-server.

POST /v1/subscribers/:subscriber_id/payment_sessions mints the short-lived Stripe PaymentSheet bundle for the mobile on-device card-add flow; it has no admin surface.

Subscriptions

POST /v1/subscriptions
  subscriber_id, plan_id, addons?, activation?

The subscription lifecycle is:

  • draft — created, not yet billable
  • pending_activation — awaiting SIM activation / port completion
  • active — billable, receives usage
  • past_due — payment failure
  • paused — operator-initiated hold
  • canceled — terminal

Transitions fire subscription.* webhook events; see Webhooks and the Event catalog.

Common flows

  • New activation: create subscriber → create subscription → order SIM → activate.
  • Port-in: create subscriber → create subscription → submit port request; the subscription stays pending_activation until the carrier confirms the MSISDN transfer.
  • Plan change: PATCH /v1/subscriptions/{id} with a new plan_id. Prorations and effective dates are handled server-side per the plan's change_policy.