Time-based Billing
Time-based billing charges customers for actual time they spend with billable content. It fits streaming, reading, and listening experiences where value scales with engagement rather than a flat membership fee.
How it works
The flow is straightforward in concept:
The user connects a payment method (for example through
tiun.start()on your paywall).A session starts and tiun begins metering time against your configured interval and price.
The user is billed for time spent according to your product settings (interval fee, optional caps).
The session ends when they leave the experience, you stop billable content, or payment fails—after which access returns to your unpaid or locked state.
You configure the product itself in the dashboard (interval, fee, limits); the SDK and events connect that configuration to your app’s UI and routing.
Session lifecycle and states
A session moves through distinct states. The diagram below summarizes transitions at a glance.
Locked
No active billing session yet, or access is not granted. The user typically sees a paywall or must connect payment before paid content runs.
Active
Billing session is in progress; eligible content can be marked as billable and time accrues according to your rules.
Ended / Invalid
Session is closed or payment failed — no further billing for that visit. The user returns to the locked state and may need to start again.
paywallHide transitions from Locked to Active; paywallShow transitions from Active to Ended/Invalid. From there, the cycle can restart.
Paywall events
Time-based access is signaled through paywall events:
paywallShow
User should not have paid access—show paywall, upsell, or locked state.
paywallHide
User has access for paid content according to the current session—reveal premium UI.
Wire your screens to these events so the experience stays aligned with whether tiun considers the session billable and allowed.
Content management
The SDK needs to know what the user is viewing so tiun can meter and bill correctly. Use tiun.setContent() whenever the user navigates to different material—on every route or section change that affects what counts as billable.
You pass a content type that describes how tiun should treat the current view:
active
Paid, billable content—time accrues per your product rules.
inactive
Free or non-billable content—metering is not applied as for paid slices.
paused
Billable surface is temporarily not accruing (for example an interstitial or a deliberate pause).
Keeping setContent() accurate across navigation prevents incorrect charges and keeps paywall state trustworthy.
Media types
How tiun interprets “active” engagement depends on media type:
Text (default)
Often tied to visibility and scroll—reading in view counts as engagement; leaving the viewport can pause or stop metering depending on your setup.
Audio
Stays active while playing even if the app is backgrounded or the screen is locked—suited to podcasts and music.
Video
Follows play and pause—billing tracks actual playback rather than only page presence.
Choose the media type that matches the asset so sessions reflect real usage.
Content ID
You can supply a content ID with your content updates so analytics and reporting tie charges and sessions to specific articles, episodes, or assets. Use stable identifiers your team can recognize in dashboards and exports.
Server-side verification
For sensitive flows, you may need to verify sessions or access on your backend, not only in the browser. See Verifying access for how to validate entitlements server-side and keep APIs aligned with tiun.
For an end-to-end walkthrough, see Build a time-based paywall.
Last updated
Was this helpful?