Access Checks & Paywalls

Checking access

Call checkAccess() to evaluate whether the current visitor can view the current page.

import { checkAccess } from '@latch/sdk';

const result = await checkAccess();

You can also pass a specific URL:

const result = await checkAccess('https://example.com/article/premium-post');

AccessResult

interface AccessResult {
  granted: boolean;
  reason?: string;
  paywallRule?: {
    id: string;
    type: string;
    action: {
      productIds: string[];
      message?: string;
      meterLimit?: number;
      template?: string;
    };
  };
  meterRemaining?: number;
}

Field	Description
granted	true if the reader has access
reason	Current grant reasons: subscribed, free_content, metered_remaining, registered, error_fallback
paywallRule	Matching rule metadata when a rule matched
meterRemaining	Remaining free views after the current granted metered request, or 0 on a metered denial

Built-in paywall behavior

If checkAccess() returns a denial and you did not pass onPaywall, the SDK renders its built-in paywall.

Available templates:

Template	Behavior
modal	centered overlay
bottom-bar	fixed bottom banner
inline	inserted into paywallSelector or appended to body

modal and bottom-bar include Subscribe and dismiss controls. inline currently renders only a Subscribe button.

Note

The built-in Subscribe button only does something if you pass onCheckout to init(). Otherwise the SDK logs a debug message and closes the paywall.

Custom paywall UI

If you want your own UI, pass onPaywall:

import { init } from '@latch/sdk';

init({
  apiKey: 'pk_...',
  apiUrl: 'https://your-latch-api',
  onPaywall: (result) => {
    showMyPaywall(result);
  },
});

When onPaywall is set, the SDK does not render its built-in paywall.

Metered behavior

For a metered rule:

1. requests within the limit are granted
2. the request that reaches the limit is still granted with meterRemaining: 0
3. later matching requests are denied with meterRemaining: 0

Soft paywalls

Soft paywalls currently return granted: true with a matching paywallRule. That means the SDK will not auto-render the built-in paywall from checkAccess() for soft rules. Your integration can inspect the returned rule and decide whether to show a prompt.

Error handling

The SDK fails open. On API or network failure, it returns:

{ granted: true, reason: 'error_fallback' }