docs

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 heliumOS token. They authenticate with your mobile app, and your backend calls heliumOS 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.

Account lock (SIM-swap / port-out protection)

Every subscriber carries a locked_status, either unlocked (the default) or user_initiated_lock. Set it with the locked boolean on create or update:

PATCH /v1/subscribers/{id}
  { "locked": true }   # lock;  false to unlock

Relay your subscriber's "lock my account" request here from your backend using your operator API key. In the operator dashboard, only the owner role can toggle the lock; other roles that can edit a profile cannot lock or unlock. While a subscriber is user_initiated_lock, the platform refuses the carrier number-portability and SIM-mobility actions an account takeover would use, returning 409 subscriber_locked:

  • SIM swap (POST /v1/sims/{id}/swap)
  • MSISDN change (POST /v1/sims/{id}/change_msisdn)
  • SLO product / WPS changes (POST /v1/sims/{id}/products, /wps)
  • Setting, generating, or clearing the port-out PIN (/v1/sims/{sim_id}/port_out_pin)

Everything else, including profile edits, plan and add-on changes, billing, and port-in, is unaffected: a locked account can still be managed, it just can't have its number or SIM moved off. Locking and unlocking fire the subscriber.locked / subscriber.unlocked webhook events.

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 on BILLING: no renewal charge until resumed, and service keeps running (suspend the SIMs to stop service)
  • 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.