> For the complete documentation index, see [llms.txt](https://docs.tiun.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.tiun.io/guides/one-time-purchases/repeatable-one-time-purchases.md).

# Repeatable one-time purchases

This guide walks through wiring up a repeatable one-time purchase — a buy button that passes a reference ID, checkout, and gating content per purchase. Login and logout are not covered here; see [authenticating your user](https://docs.tiun.io/guides/authentication/authenticate-your-user.md) for those.

A regular one-time product is bought **once per customer**. A repeatable one is bought **any number of times**, and each purchase is tied to a **reference ID** from your app — the article, booking, or order it's for. Use it for things customers buy again and again: single articles, sessions, tickets, or reports.

***

## 1. Create a repeatable product

In the dashboard, create a product with the **One-time** pricing model, set its **Price**, and turn on **Repeat purchases**. The price is charged **each time** a customer buys it.

Optionally, turn on **Limited access** so each purchase lasts a set number of days, weeks, months, or years from the day of purchase. When it's off, every purchase keeps its access forever.

The full walkthrough is in [creating your first product](https://docs.tiun.io/guides/getting-started/creating-first-product.md); copy the product ID when you're done. For how the two settings combine, see [Products](https://docs.tiun.io/reference/generic/products.md#one-time-purchase) in Reference.

***

## 2. Install and initialize the SDK

Install `@tiun/sdk` 0.11.0 or later and call `tiun.init` once at app startup. The [Quickstart](https://docs.tiun.io/quickstart.md) has the full install commands.

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

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

***

## 3. Add a buy button

Keep product IDs in one place so buy buttons, gating logic, and analytics all reference the same source. The JS will throw on typos instead of failing silently.

```javascript
const TIUN_PRODUCTS = {
  article: 'p-live-article',
};
```

Wire the button to `tiun.checkout()` with the product ID **and** a `referenceId` — your own ID for what this purchase is for:

```javascript
function onClickBuy(articleId) {
  tiun.checkout({
    productId: TIUN_PRODUCTS.article,
    referenceId: articleId, // e.g. 'article-1042'
  });
}
```

Pick a reference ID that already exists in your app — an article or content ID when each purchase unlocks one item, or a booking or order ID when each purchase is its own transaction. Use the same ID every time you mean the same thing: it's how you'll look the purchase up later.

Each reference ID can be bought **once per customer** while its access lasts. If a customer opens checkout again with a reference ID they still have access to, checkout shows an "already purchased" screen instead of charging them. So once a purchase is confirmed (see [step 5](#5-check-access-and-gate-content)), show the item instead of its buy button.

{% hint style="warning" %}
**A reference ID is required for repeatable products, and only for them.** If you open checkout without one, the overlay shows a configuration error instead of the payment step, and nothing is charged. Passing one on any other product — a subscription, a time-based product, or a one-time product with Repeat purchases off — shows a configuration error too. Use 1–200 characters: letters, digits, hyphens, underscores, or dots. No spaces.
{% endhint %}

***

## 4. Re-check access on every change

`userChange` fires whenever the user or their access changes: on page load, login, logout, and with `event: 'checkout'` whenever access is gained or lost. That includes buying this product with a new reference ID, and a purchase made in another tab, once the customer comes back to this one.

So re-check the item on **every** `userChange`:

```javascript
tiun.on('userChange', () => loadArticle(currentArticleId));
```

What `loadArticle` does depends on where you check the purchase — see the next step.

***

## 5. Check access and gate content

For a regular one-time product or a subscription, you check `productAccess` on the user object. **That doesn't work for a repeatable product:** `productAccess` lists product IDs, so it can't tell you **which reference ID** the customer bought — this article, but not the next one.

You can check a purchase in two places:

* **In the browser**, with `tiun.checkProductAccess()`. No backend needed: the SDK asks tiun, and you show the item or its buy button.
* **On your server**, with the product access API. A good fit if you already have a backend, or want a more secure setup where the content stays on your server until the purchase is confirmed. Use it for anything you fulfil yourself, such as downloads or orders.

You can also combine them: check in the browser for the page, and on the server for the content it loads.

### Check in the browser

Check the purchase with `tiun.checkProductAccess()`. Pass the product **and** the same `referenceId` you passed to checkout. Needs `@tiun/sdk` 0.12.0 or later (`@tiun/react-native-sdk` 0.5.0 in React Native):

```javascript
async function loadArticle(articleId) {
  const { hasAccess } = await tiun.checkProductAccess('p-live-article', {
    referenceId: articleId,
  });

  if (hasAccess) {
    showArticle(articleId);
  } else {
    showSalesPage(articleId);
  }
}
```

When the user isn't logged in, or hasn't bought this reference ID, it resolves to `{ hasAccess: false, access: null }` — no error to handle. When they have, `access` holds the purchase, including its `referenceId` and `activatedAt`.

**Showing many items at once**, like a list of articles? Call `tiun.listProductAccess()` once and look up each item in the result, instead of calling `checkProductAccess()` per item. It returns every active purchase with its reference ID — also what you need for a "My purchases" page:

```javascript
const access = await tiun.listProductAccess();
const purchased = new Set(
  access
    .filter((entry) => entry.productId === 'p-live-article')
    .map((entry) => entry.referenceId),
);

articles.forEach((article) => renderTeaser(article, purchased.has(article.id)));
```

See [Core Methods / Products](https://docs.tiun.io/sdk/web-sdk/core-methods.md#products) for the full API.

### Check on your server

Your frontend requests the item with a verification token, and your backend asks tiun about the product **and** the reference ID together, then returns the content — or `403` when the customer hasn't bought it:

```javascript
async function loadArticle(articleId) {
  const token = await tiun.getUserVerificationToken();

  if (!token) {
    showSalesPage(articleId);
    return;
  }

  const res = await fetch(`/api/articles/${articleId}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (res.status === 403) {
    showSalesPage(articleId);
    return;
  }

  showArticle(await res.json());
}
```

The backend side — verifying the token and calling the product access API with the reference ID — is covered in [verifying repeatable purchases server-side](https://docs.tiun.io/guides/one-time-purchases/verify-server-side.md). The same API can also **list every purchase** of a user, for example to render a "My purchases" page.

If your backend keeps its own record of purchases, it can also update it from the [`product_access.add` and `product_access.remove` webhooks](https://docs.tiun.io/guides/webhooks/receive-webhooks.md), which carry the reference ID. Your server then checks its own database instead of calling tiun on every request — but confirm each webhook with the product access API before you trust it.

The server's answer covers **both** decisions: whether to return the content, and what the page shows.

***

## 6. Add login and logout

Returning customers need to sign in to get their purchases back on a new browser or after logging out. The setup is covered in [authenticating your user](https://docs.tiun.io/guides/authentication/authenticate-your-user.md) — once that's wired up, the same `userChange` handler reloads the item, and your backend finds their existing purchases by reference ID.

***

## 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 IDs (prefixed `p-live-`).
3. Switch your backend to the live API base URL and a live API key.

See [setting up your environment](https://docs.tiun.io/guides/getting-started/set-up-environment.md) for the full sandbox / live workflow.

***

## Full example

The repeatable purchase integration in one place (login / logout wiring lives in the Auth guide, the backend check in the server-side guide):

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

const TIUN_PRODUCTS = {
  article: 'p-live-article',
};

let currentArticleId = 'article-1042';

tiun.on('userChange', (data) => {
  if (!data.isAuthenticated) {
    showSalesPage(currentArticleId);
    return;
  }

  loadArticle(currentArticleId);
});

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

async function loadArticle(articleId) {
  const token = await tiun.getUserVerificationToken();

  if (!token) {
    showSalesPage(articleId);
    return;
  }

  const res = await fetch(`/api/articles/${articleId}`, {
    headers: { Authorization: `Bearer ${token}` },
  });

  if (res.status === 403) {
    showSalesPage(articleId);
    return;
  }

  showArticle(await res.json());
}

function buyArticle(articleId) {
  tiun.checkout({
    productId: TIUN_PRODUCTS.article,
    referenceId: articleId,
  });
}
```

***

For framework-specific implementations, see [React](https://docs.tiun.io/sdk/web-examples/react.md), [Vue](https://docs.tiun.io/sdk/web-examples/vue.md), and [Nuxt](https://docs.tiun.io/sdk/web-examples/nuxt.md) in the SDK reference. In React Native, `checkout({ productId, referenceId })` from `useTiun()` works the same way.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.tiun.io/guides/one-time-purchases/repeatable-one-time-purchases.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
