Unlocking articles

This page describes the unlock process from both sides: what readers do, and what publishers can configure and debug.

For readers

1. You reach a wall. It states the price and, in most cases, why the article is being charged for. An article can remain free until it reaches a number of reads, a rating, or a certain age.

2. You continue to Paperwall. The link opens paperwall.io with the article already selected, and includes a route back to the page you came from.

3. You pay for that article. Payment is per article, not a subscription. You buy tickets, which are a prepaid balance, and spend them on individual articles. If you already hold a balance, this takes one step.

Free articles can be unlocked without an account. Paid articles require an account and a saved card.

4. You return to the article, unlocked. The wall is gone. On Ghost sites, the full post is retrieved and added to the page, because Ghost did not send it to your browser originally.

5. You can rate the article. Only readers who have paid may rate, which is what makes ratings usable as a pricing signal. Ratings can determine whether the next reader is charged.

What the payment covers

Access to that article, linked to your account. It persists after you close the tab. It is not a subscription and does not renew. No further charge is made unless you unlock another article.

For publishers

The same process, described in the parts you can configure or debug.

Visit. On an article page, your integration queries the API about the current URL. The response contains the article, its report of visits, reads, and ratings, and flags for preview and promo mode. Pages that match none of your postUrls patterns never reach this step.

Session. If the reader should be walled, an article session is created. The price is fixed to that session, so a reader who begins at one price is not re-priced if you edit the article while they are paying.

Redirect. The wall's call to action points at paperwall.io/redeem, carrying the article, the session, and a redirect back to the reader's page.

Redemption. Paperwall charges the reader and marks the session as purchased. This requires both the site and the article to be LIVE. A site in PREVIEW can display its wall to your team but cannot take payment.

Return. The reader returns and the integration re-checks the session, which now reports as purchased. The wall state becomes show_article.

Rating. Available once the session records a purchase.

Testing before publishing

Set the site to PREVIEW. The wall then appears only to members of your Paperwall team, so you can complete the process on your live site without readers seeing it. Set an article's cost to 0 to test the unlock path without using a card.

When an unlock does not persist

Check the following:

• The reader returned to the same URL. The return redirect uses the URL they left from. A wall rendered on a different canonical URL will not match the session.
• The site is LIVE. Redemption is refused in any other state.
• On Ghost, the admin key is valid. An article that unlocks but shows no text almost always indicates a key problem. See Ghost.
• In a single-page application, resetOnNav() is called. Without it, the application retains the state from before the reader left.