Candidate paywalls

Build candidate offer selection, embedded checkout, entitlement checks, and billing management.

Build the candidate job-access purchase flow. Offers are public, but checkout, checkout state, grants, and billing-portal access all belong to the signed-in candidate.

Prerequisites

board.context().features.candidatePaywall is true.
Candidate authentication and a completed candidate profile.
@stripe/stripe-js in the browser that mounts embedded checkout.
A server-owned session for every board.me.access request.

Load offers and the current grant

1// src/data/access.ts
2import type { FetchOptions } from '@cavuno/board';
3
4import { board } from '../lib/board';
5
6function session(accessToken: string): FetchOptions {
7  return {
8    cache: 'no-store',
9    headers: { authorization: `Bearer ${accessToken}` },
10  };
11}
12
13export async function loadAccessPage(accessToken: string) {
14  const [context, offers, grant] = await Promise.all([
15    board.context(),
16    board.paywall.offers(),
17    board.me.access.grant(session(accessToken)),
18  ]);
19
20  if (!context.features.candidatePaywall) return null;
21  return { offers: offers.data, grant };
22}

grant always resolves. No access is { hasAccess: false, … }, not an error. Use it for the rendering decision instead of inferring access from gatedCount or a previous checkout redirect.

Start embedded checkout

1export async function startAccessCheckout(
2  accessToken: string,
3  offerKey: string, // Use the selected offer.offerKey unchanged.
4) {
5  return board.me.access.checkout(
6    {
7      offerKey,
8      returnPath: '/account/access',
9      colorMode: 'light',
10    },
11    session(accessToken),
12  );
13}

The response is a mount kit containing sessionId, clientSecret, stripeAccountId, and publishableKey. In the browser, initialize Stripe.js with both the publishable key and connected account, then mount embedded checkout with the returned client secret.

1// src/browser/mount-access-checkout.ts
2import type { AccessCheckoutSession } from '@cavuno/board';
3import { loadStripe } from '@stripe/stripe-js';
4
5export async function mountAccessCheckout(
6  kit: AccessCheckoutSession,
7  selector: string,
8) {
9  const stripe = await loadStripe(kit.publishableKey, {
10    stripeAccount: kit.stripeAccountId,
11  });
12
13  if (!stripe) throw new Error('Stripe.js failed to load');
14
15  const checkout = await stripe.initEmbeddedCheckout({
16    clientSecret: kit.clientSecret,
17  });
18
19  checkout.mount(selector);
20  return () => checkout.destroy();
21}

Call the returned cleanup function when the checkout view unmounts.

Confirm access after checkout

1export async function confirmAccess(
2  accessToken: string,
3  sessionId: string,
4) {
5  const options = session(accessToken);
6  const checkout = await board.me.access.retrieveCheckout(
7    sessionId,
8    options,
9  );
10
11  if (checkout.status !== 'complete') return { checkout, grant: null };
12
13  const grant = await board.me.access.grant(options);
14  return { checkout, grant };
15}

An open checkout can be remounted with its returned clientSecret. An expired checkout needs a new session. Even after complete, unlock content only when a fresh grant returns hasAccess: true.

Open subscription management

1const portal = await board.me.access.portal(
2  { returnPath: '/account/access' },
3  session(accessToken),
4);
5
6// Redirect to portal.url with your framework.

Only recurring grants have a billing portal. Lifetime access does not.

Expected result

The page shows current public offers and the viewer’s grant. Checkout returns an embedded-checkout mount kit; a completed checkout followed by grant() returns the authoritative access decision.

Verify the result

Disabled paywalls do not render purchase routes or controls.
Offer labels and prices come from board.paywall.offers.
Checkout is unavailable without a signed-in candidate profile.
A browser return does not unlock content until grant.hasAccess is true.
Lifetime users never see a recurring-subscription management action.

Errors and edge cases

offers() returns an empty list when the paywall is disabled.
Past-due, unpaid, incomplete, canceled, and pending grants can all return hasAccess: false; render from both fields without inventing a local status.
returnPath must remain a safe relative path.
The SDK does not mount Stripe UI or process card details.

Production cautions

Never cache grants, checkout state, or portal URLs publicly.
Keep card handling inside Stripe’s embedded checkout.
Re-read the grant on every protected server render, not only in the browser.
Log API request IDs, not checkout secrets or session credentials.

Continue with Frontend infrastructure to make these routes canonical, indexable, and visually consistent.