Charge for time-based sessions

This guide walks you through wiring up a time-based paywall — the user connects a payment method, opens premium content, and is billed for the time they spend with it. By the end, you'll have a paywall, a billing session, and content metering.

---

1. Create a time-based product

Create a time-based product in the dashboard and copy its product ID. The full walkthrough is in creating your first product — choose Time-based as the product type.

---

2. Install and initialize the SDK

Install @tiun/sdk and call tiun.init once at startup. The Quickstart has the full install commands.

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

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

---

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. Render your app with the paywall showing and premium content hidden. For the full mental model of how time-based access works, see Time-based / How it works in Reference.

---

4. Listen for paywall events

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

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

tiun.on('paywallHide', (data) => {
  hidePaywall();
  showPremiumContent();
  // data.sessionId is available for server-side verification
});

paywallShow fires when the user doesn't have access (no payment method yet, or session ended). paywallHide fires when access is granted and a session is active; the payload includes a sessionId you can pass to your backend for server-side session verification. For the full event contract, see Access in Reference.

---

5. Start a billing session

Add a button on your paywall that opens the connect overlay. tiun.start() collects 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. The full list of content types, media types (audio / video), and metering behavior lives in Protecting content in Reference.

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

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

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

---

7. Go live

If you've been testing in sandbox, set up live as a separate environment in the dashboard, then for production traffic:

1. Remove sandbox: true from your tiun.init (or set it to false).

2. Use your live snippet ID and live product ID (prefixed p-live-).

3. If you verify server-side, switch to the live API base URL and a live API key.

See setting up your environment for the full sandbox / live workflow.

---

Full example

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

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

tiun.on('paywallShow', () => {
  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 serves premium content, also see server-side session verification.