> For the complete documentation index, see [llms.txt](https://docs.younium.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.younium.com/sales-and-product-led-growth/paywall.md).

# Paywall

## 1. Overview

Younium Paywall turns a page on your own website into a checkout. A visitor compares your plans, fills in their company and billing details, pays by card, and comes back to a thank-you page — and Younium has created the account, activated the subscription, raised and posted the invoice, emailed it, and recorded the payment before they get there. Nobody in sales has to touch it.

A paywall is built and maintained in Younium, under **Sales → Paywall**, and embedded on your site as a small block of HTML. Everything the visitor sees — which products appear, how the plans are described, what the checkout asks for, the colours, the terms they accept, where they land afterwards — comes from that configuration, so changing the offer is a change in Younium rather than a change to your website.

Not every visitor is ready to buy. A paywall can end with a **Contact Sales** card instead of a price, which collects an enquiry and delivers it to your inbox, to HubSpot, or to any system listening on a webhook. Paywall sits alongside [Self Service](https://docs.younium.com/sales-and-product-led-growth/self-service.md), which serves customers you already have, and [CPQ](https://docs.younium.com/sales-and-product-led-growth/cpq.md), which serves deals your sales team runs.

***

## 2. Core Concepts

### Paywall

A paywall is one configured offer: a set of products, the cards that present them, the currencies and billing periods a buyer can choose, the checkout questions, the branding, and the sites allowed to show it. Each paywall belongs to a legal entity, and a tenant can run as many as it needs — one per campaign, market or audience.

### Card

A **card** is how one charge plan is presented to the buyer: the plan's name, a subtitle, a features list under a heading of your choosing, and its price. Cards sit side by side so a visitor can compare plans. A card whose charge plan is priced per unit also offers a quantity, stepped in whatever increment you set.

A paywall shows cards for every charge plan of every product on it, so the number of cards is decided by the catalogue rather than set by hand.

### Checkout session

Each attempt to buy is a session. It begins when the buyer submits the checkout form, and it carries the purchase through creating the draft order, paying, and everything Younium does afterwards. The checkout page follows the session as it runs, which is why the buyer sees progress rather than a frozen form, and why a purchase that fails can say so immediately.

### Contact Sales card

An optional extra card, shown last and without a price, for buyers who need to talk to someone. It has its own title, subtitle, features list and SLA note, and its own form.

### Lead

A submission of the Contact Sales form. A lead records who asked, what they asked about, and which card and billing period they were looking at when they asked. Leads are delivered to the destinations you enable and kept in the paywall's own log for 30 days.

***

## 3. Building a Paywall

A paywall needs a name, at least one product, a terms and conditions link, and at least one site allowed to show it. Everything else refines the offer.

Before a paywall can be shown or bought, your order settings must have a default term type, and a default **Invoice template** must be set in either the order settings or the account settings. Setting it in one of them is enough: accounts created by the paywall take the account settings default, and the order falls back to the order settings default. If neither is set, Younium reports "Default invoice template is not set."

**Products and cards.** A paywall offers one product, and each active charge plan of it becomes a card. The product must be a Full product or a Multiple charge plans product. A Multiple charge plans product must have exactly one charge on each plan, because each card sells a single charge; a Full product's plans can carry several charges. Every plan must include at least one recurring charge, so that the purchase is a subscription. Paywalls saved with several products or other product types before this rule continue to work for buyers. A product with no active charge plan contributes nothing and says so. Because buyers compare cards side by side, every charge plan on the paywall must be priced in a shared currency — Younium refuses to save a paywall whose plans have no currency in common, and flags any product it cannot price at all, because a buyer would otherwise meet a card with no price on it.

Each card is edited on its own: a subtitle, a heading for the features list, the features themselves, and the quantity step for plans sold per unit. A card with no text of its own is marked as such while you are editing, since it will otherwise reach buyers bare.

**Discount.** A paywall can carry an annual discount percentage, applied when the buyer chooses annual billing. It depends on order discounts being switched on in the order settings; until they are, Younium says so rather than offering a setting that would not apply.

### Settings

| Setting                        | Description                                                                                                                                          | Default |
| ------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ------- |
| **Name**                       | How the paywall is identified in Younium. Required                                                                                                   | —       |
| **Annual Discount Percentage** | Percentage taken off when the buyer chooses annual billing, between 0 and 100. Available only when order discounts are enabled in the order settings | None    |
| **Terms and Conditions URL**   | The terms the buyer confirms before paying. Required                                                                                                 | —       |
| **Whitelisted Domains**        | The sites allowed to show this paywall — see section 9. Required                                                                                     | —       |
| **Test mode**                  | Lets the paywall be tried end to end without Stripe — see section 9                                                                                  | Off     |

***

## 4. The Checkout

The checkout asks for what Younium needs to raise a subscription and invoice the buyer, and no more. Most of it is fixed, because an invoice cannot be produced without it.

| Always asked       |                  |
| ------------------ | ---------------- |
| Company legal name | Billing email    |
| Street, Street 2   | Zip, City, State |
| Country            |                  |

Three further questions are yours to switch on:

| Setting                 | Description                                                                                                     | Default |
| ----------------------- | --------------------------------------------------------------------------------------------------------------- | ------- |
| **Organization number** | Asks the buyer for their organisation number                                                                    | Off     |
| **VAT number**          | Asks the buyer for their VAT registration number                                                                | Off     |
| **VIES validation**     | Checks the VAT number against the EU VIES service as the buyer types. Available only while **VAT number** is on | Off     |

With VIES validation on, the buyer sees the result against the field as they type: checking, valid, not valid, or that it could not be verified. The last of these is its own outcome rather than a failure — VIES is an external service, and it being unreachable does not mean the number is wrong.

**Custom fields.** Any account or order custom field can also be collected at checkout and written to the record Younium creates. Keep the list short: Younium warns past four, because each question is one more thing between a willing buyer and a completed purchase.

**Paying.** The buyer accepts the terms, chooses a quantity where the card offers one, and pays by card through Stripe. Younium creates the account and a draft order first, then hands the buyer to Stripe's payment page; the rest happens when Stripe confirms the payment.

**Test mode.** A paywall can be switched to test mode so that you can try the whole purchase before Stripe is connected. In test mode the checkout runs only from the preview in the paywall editor; an embedded paywall on your site shows "This paywall is in test mode and cannot be bought yet." and its purchase button is disabled, so turn test mode off before you publish. The preview of a live paywall stays read-only and shows "Purchases are disabled in preview." Younium does not require any Stripe setup for a test-mode paywall, and no card is taken. The buyer's account, subscription and invoice are created and the invoice is posted and emailed as in a live purchase, and a payment for the full invoice amount, without fees, is recorded when the Stripe settings name a payment method. If they do not, the invoice stays unpaid.

A test-mode subscription uses invoice as its payment method rather than Stripe. Once the payment step is done, Younium cancels the subscription at the end of the period the test invoice covers, so your invoice runs do not bill the test buyer again. If that cancellation fails, the purchase still completes and the subscription must be cancelled by hand.

**Afterwards.** The buyer lands on a thank-you message you write, or is sent to a URL of your own — an onboarding flow, a download, a getting-started guide.

### Settings

| Setting                    | Description                                                         | Default |
| -------------------------- | ------------------------------------------------------------------- | ------- |
| **Thank You Message**      | What the buyer reads after a completed purchase                     | —       |
| **Use Thank You Redirect** | Sends the buyer to a URL of your own instead of showing the message | Off     |
| **Thank You Redirect URL** | Where they are sent. Required while the redirect is on              | —       |

***

## 5. What a Completed Purchase Creates

Once Stripe confirms the payment, Younium completes the purchase without further input:

| In order | What Younium does                                         |
| -------- | --------------------------------------------------------- |
| 1        | Activates the subscription from the draft order           |
| 2        | Generates the invoice for it                              |
| 3        | Posts the invoice                                         |
| 4        | Emails the invoice to the billing email given at checkout |
| 5        | Records the payment against the posted invoice            |

In a [test mode](#test-mode) purchase the payment is recorded without a Stripe fee, using the payment method set in your Stripe settings. Without a payment method there, no payment is recorded and the invoice stays unpaid, though the purchase still completes.

The buyer's checkout page follows this as it happens, so a failure at any step is reported rather than leaving them on a page that has stopped saying anything. A purchase that fails before the buyer reaches Stripe never charges them.

The account, the subscription, the invoice and the payment are ordinary Younium records from this point on. They can be amended, credited and reported on like any other, and they raise the same events (section 10).

***

## 6. Abandoned Checkouts

Buyers leave. A checkout that reaches Stripe and is never paid would otherwise leave an account and a draft order behind for a purchase that never happened, so Younium clears them up.

A checkout counts as abandoned **two hours** after its draft order was created. Younium then closes the Stripe payment page so it cannot be paid late, deletes the draft order, and deletes the account the checkout created — but only if nothing else has come to depend on it. An account that has since been used elsewhere is kept, and only the draft order goes.

Where a checkout fails before the buyer ever reaches a payment page, the draft and its account are removed straight away rather than waiting out the two hours.

> **Note on what abandonment does not touch:** Only the account the checkout itself created is in scope, and only while nothing else references it. A buyer who abandons a checkout against an account you already had keeps that account intact.

***

## 7. The Contact Sales Card

Switching on **Contact sales** adds a final card with no price. It is for the buyer whose answer is "call me" — the enterprise deal, the unusual volume, the procurement process that will not go through a card payment.

**What the card says.** The card has its own title, subtitle, features list and heading, written the same way a plan card is. An SLA note sits alongside them for whatever commitment you want to make about how quickly someone will reply.

**What it asks.** The form is yours to shape. Seven fields are available — work email, first name, last name, company, phone, seats and a free-text note — and for each you choose whether it appears, what it is called, whether it is required, and where it sits in the order. Email is always asked for and always required, since a lead with no way to reply is not a lead.

### Where leads go

Enable as many destinations as you need. Delivery is queued and retried rather than attempted once, so an outage at the far end delays a lead instead of losing it. Whatever happens downstream, the buyer gets their confirmation immediately.

| Destination            | What it does                                                                                                                                                                                |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Email notification** | Sends the lead to the **Sales email** address, which is required while this destination is on                                                                                               |
| **HubSpot**            | Creates the contact, and the deal where your HubSpot settings ask for one. Needs HubSpot connected and configured first; Younium shows whether it is ready and links to the settings if not |
| **Webhook**            | Publishes a paywall lead created event to every webhook subscribed to it. This is the route for Salesforce or any other system                                                              |

**HubSpot field mapping.** Which lead field lands in which HubSpot property is set once in the HubSpot settings and used by every paywall. A paywall can override individual fields for itself where one campaign needs to populate something different; fields with no override follow the tenant's mapping, and clearing an override returns that field to it.

**What a lead carries.** A lead holds only what the buyer entered in the form, plus the page they sent it from. It does not record the plan, currency or billing period of the cards shown beside the Contact Sales card, because the buyer did not choose those. Seats are kept only when the form asks for them. The email notification lists the enabled form fields and the page, and HubSpot offers no field mapping for plan, currency or billing period; any mapping previously set for them is ignored. A HubSpot deal is named after the company (or the email address where there is no company) followed by the paywall's name, so deals from different paywalls are easy to tell apart.

**The lead log.** Each paywall keeps a log of the leads it has collected and how delivery went for each destination. Leads are deleted **30 days** after they arrive, so the log is a working view rather than a record to rely on — a lead that matters belongs in the system its destination delivers it to.

***

## 8. Appearance

A paywall takes five colours, set as hex values or made transparent.

### Settings

| Setting              | Description                         |
| -------------------- | ----------------------------------- |
| **Base Color**       | The card header and primary surface |
| **Accent Color**     | Buttons and highlights              |
| **Background Color** | The surface the cards sit on        |
| **Light Grey Color** | Secondary surfaces and dividers     |
| **Base Font Color**  | Text on the base colour             |

Younium checks the combination as you set it and warns where text would be hard to read against the surface behind it, including the case of text set to transparent, which disappears entirely. The warnings do not stop you saving — a deliberate choice stays yours to make — but they catch the common accident of a palette that looks right in the picker and cannot be read on the page.

***

## 9. Embedding the Paywall

A paywall is embedded as two lines of HTML: a script, and a `<paywall-main>` element carrying a token that identifies the paywall. Younium generates both for you from the paywall itself — **Get JavaScript Code** — so there is nothing to assemble by hand.

A second form of the same snippet is offered for content management systems that strip unfamiliar elements out of pasted HTML, which builds the element in script instead. Both produce the same paywall.

**Preview.** A paywall can be previewed from Younium before it is live anywhere. The preview is the real checkout against the real configuration, with purchasing disabled, so you can walk the whole flow without creating an account or taking a payment. A paywall in test mode is the exception: from the preview you can complete a test purchase, which takes no card payment but creates a real order and invoice. See section 4 for what happens when a paywall in test mode is embedded on a site.

### Test mode

**Test mode** lets you run the complete checkout before Stripe is connected, or without taking a real payment. Instead of sending the buyer to Stripe, the checkout shows a **Simulate payment** page with the subtotal, tax and total the buyer would have paid. Everything else is real: Younium creates the account, activates the subscription, posts the invoice and emails it, and records a payment when the Stripe settings name a payment method (see section 5).

Test purchases can be made only from the preview in Younium, and only by a user who can edit paywalls. A paywall in test mode that is embedded on your site shows "This paywall is in test mode and cannot be bought yet." and its purchase button is disabled. A checkout started before test mode was switched off cannot be completed without payment. Switch test mode off before you publish the paywall.

**Whitelisted domains.** A paywall only loads on sites you list. Younium checks the site making the request against that list and refuses anything else, which is what stops a working paywall being lifted onto a site you do not control.

Each entry is an `https://` origin — scheme and host, no path, no query string, no trailing slash — and Younium rejects anything else when you save. Plain `http://` is not accepted at all, so the checkout can never run on an unencrypted page. List the www and non-www forms separately if your site answers on both; they are different origins, and only what is listed will load.

***

## 10. Events

A completed purchase raises the platform's ordinary webhook events, in the order Younium performs the work. Anything already subscribed to them picks up paywall purchases without further configuration.

| Event                  | Raised when                                                                                      |
| ---------------------- | ------------------------------------------------------------------------------------------------ |
| Account created        | The buyer's account is created                                                                   |
| Subscription activated | The subscription is activated from the draft order                                               |
| Invoice posted         | The invoice for the purchase is posted                                                           |
| Payment posted         | The payment is recorded against it. Not raised for a test mode purchase that recorded no payment |

The Contact Sales card raises one event of its own, when its **Webhook** destination is enabled:

| Event                | Raised when                            |
| -------------------- | -------------------------------------- |
| `PaywallLeadCreated` | A buyer submits the Contact Sales form |

Subscribe to it under **Settings → Webhooks** like any other.


---

# 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.younium.com/sales-and-product-led-growth/paywall.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.
