product-paywall
Put a small web prototype behind a paywall — part of it free, the full thing for one fixed price — with Stripe embedded Checkout, an emailed HMAC password, and a data API that refuses without it. Use
SKILL.mdskills/product-paywall/SKILL.md
GitHubFree slice, one price, the full thing
The build
- The static site ships only the free slice plus counts. The full data is served by a
function,
/api/data, which requires a password: a nonce plus an HMAC underACCESS_SECRET. - The password is minted at checkout.
/api/checkoutcreates an embedded Checkout Session and puts the password (or the nonce) in sessionmetadata; oncheckout.session.completeda webhook emails it (Mailgun, Postmark, SES...). A/api/session-statusendpoint lets the return page show it immediately, and apw_emailedmarker in metadata prevents double emails. - Env:
STRIPE_SECRET_KEY,STRIPE_WEBHOOK_SECRET,ACCESS_SECRET, mail provider keys. - Track
preview_open,checkout_openandpaidas analytics events. "Sales" means nothing without the step people stop at; many checkouts with no payments is a price signal. - The free slice proves value on the reader's own row, and the page opens pre-loaded with a real example. A blank tool loses an attention-poor visitor.
Webhook: one shared endpoint, not one per product
Stripe caps an account at 16 webhook endpoints. Past that, a new product gets none, and a
buyer who closes the tab before the return page loads never gets a password. So run one
router endpoint for every paywall: it verifies the signature, reads metadata.product,
and forwards to that product's webhook with a per-product secret. Each product's handler
accepts a comma-separated list of secrets.
metadata.productat checkout must equal the name registered in the router; the handler ignores any other product.- Don't create a fresh endpoint per product. Every slot used is one the next product
can't have, and two deliveries of one event can race the
pw_emailedmarker into a double email. - Probe it: send a signed fake event for an unpaid session and expect a
not ours or not paidreply — that proves both signature and routing, with no charge and no email.
Rules, each with its why
- Check repo visibility before calling it done. If the repo is public and its history
ever held the full data, the paywall is decorative. Make it private
(
gh repo edit --visibility private --accept-visibility-change-consequences). - One fixed price, one plain line. No badges, discounts or bundles. Set the price at about a tenth of what one use is worth to the buyer. Write the arithmetic and the date in the README under "Price", labelled a hypothesis, so it can be revised on evidence.
- Put the recipient token in the path (
/for/<token>/), not the query string. Vercel Analytics drops?queryand#hash; a path token is the only way to see which recipient opened it. - A personalised page with no record of the reader's own is not sendable. Hold it rather than showing them a generic example.
- Verify on the live site before reporting:
/api/datareturns 401 without a password.POST /api/checkoutreturns acs_live_client secret.- A comp password unlocks the full data.
- The analytics tags show up in a curl of the page.
- One page renders at 390 and 1440 wide.
- The paid bundle is NOT a static file: curl
/api/%5Ffull/full.json.gzand/api/_full%2Ffull.json.gz(and the plain path); each must be 307/404, never 200. A deploy that setsoutputDirectory: "."(or uploads the whole folder) makes every file a URL, and exact-path redirects miss the%5Fspelling. Fix: upload static files underpublic/, setoutputDirectory: "public"in both the deploy payload andvercel.json, and ship the bundle only via the function'sincludeFiles. Add a test that the bundle path 404s. Static downloads don't appear in function logs, so a leak can't be audited after the fact. - The host is a Stripe payment method domain (
GET /v1/payment_method_domains;POST domain_name=<host>if missing). Without it embedded Checkout silently hides Apple Pay and Google Pay, and phone buyers face a typed-card form and leave. - Make no real payment. The emailed password is then untested; say so.
- Done means committed, pushed and deployed. Check the commit and the live response, not an agent's message saying it's done.
Getting it to buyers
Pick the channel before writing the message. Whatever the channel: open on the reader's own record (their listing, filing, menu price or site), then one fact your data adds, then the link and the one price. Send one-to-one, in waves, verified addresses only, and read visits, checkouts and replies on day 3 before sending wave 2. Fewer than ~50 recipients across 3 segments is a probe, not a verdict.
Known gaps
- The price is a hypothesis until real buyers pay or don't.
- Test the full purchase -> webhook -> email path at least once with a real (refunded) payment before trusting it.