Build a Time-based Paywall

This guide walks you through a complete time-based billing integration — from creating a product to managing sessions and content types. By the end, you'll have a working paywall where users pay for the time they spend with your content.

---

1. Create a time-based product

In the tiun.business dashboard, go to Products and click Create product. Select Time-based Billing and configure:

• Interval — how often the user is charged (e.g. every 1 minute)

• Interval fee — the amount per interval (e.g. EUR 0.22)

• Monthly limit — maximum charge per month (e.g. EUR 12)

Save and copy the Product ID.

For more on product types, see Products.

---

2. Install and initialize the SDK

npm install @tiun/sdk

import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en', // set to your site's language
});

---

3. Start with the paywall visible

In time-based billing, the default state is "locked" — the user doesn't have access until they connect a payment method. Start your app with the paywall showing and premium content hidden.

---

4. Listen for paywall events

tiun tells your app when to show or hide the paywall through two events:

tiun.on('paywallShow', (data) => {
  showPaywall();
  hidePremiumContent();
});

tiun.on('paywallHide', (data) => {
  hidePaywall();
  showPremiumContent();
});

paywallShow fires when the user doesn't have access — either they haven't connected a payment method yet or their session has ended.

paywallHide fires when the user has access and a session is active. The payload includes a sessionId you can use for server-side verification.

For more on paywall events, see Time-based Billing.

---

5. Start a billing session

On your paywall, add a button that opens the connect overlay. This connects the user's payment method and starts their session.

function onClickGetAccess() {
  tiun.start();
}

After the user connects, paywallHide fires and the user has access.

---

6. Manage content on route changes

Tell tiun what the user is viewing so it can meter and bill correctly. Call setContent() on every route or page change.

function onRouteChange(path) {
  const isPaid = isPaidContent(path);

  tiun.setContent({
    type: isPaid ? 'active' : 'inactive',
    contentId: path
  });
}

Type	When to use
'active'	Paid content — session is running and billing
'inactive'	Free content — session pauses, no billing
'paused'	Temporarily paused (e.g. user paused a video)

When content is 'inactive', the session pauses and the user is not billed. When it switches back to 'active', the session resumes.

---

7. Handle media types

For audio or video content, set the mediaType so tiun can manage sessions appropriately — for example, keeping a podcast session active while the screen is locked.

tiun.setContent({
  type: 'active',
  contentId: 'episode-42',
  mediaType: 'audio'
});

Media type	Behavior
'text'	Default. Tracks page visibility and scroll.
'audio'	Stays active during background and locked-screen playback.
'video'	Follows video play/pause state.

---

8. Go live

Production is the default environment — if you never set sandbox: true, you're already live.

If you've been testing in sandbox:

1. Remove sandbox: true from your SDK init (or just don't include it)

2. Use your production product ID (prefixed with p-live-)

See Sandbox Setup and Test Flows for details on the sandbox environment.

---

Full example

Here's the complete integration in one place:

import { tiun } from '@tiun/sdk';

tiun.init({
  snippetId: 'YOUR_SNIPPET_ID',
  language: 'en',
});

tiun.on('paywallShow', (data) => {
  showPaywall();
  hidePremiumContent();
});

tiun.on('paywallHide', (data) => {
  hidePaywall();
  showPremiumContent();
});

function getAccess() {
  tiun.start();
}

function onRouteChange(path) {
  const isPaid = isPaidContent(path);

  tiun.setContent({
    type: isPaid ? 'active' : 'inactive',
    contentId: path
  });
}

---

For framework-specific implementations, see React, Vue, and Nuxt in the SDK reference.

If your backend needs to verify sessions before serving premium content, see Verify Sessions Server-side.