`plandalf.gate()`

Check access and present its fallback offer when needed.

Implemented by the browser object; parameter and return types follow the delegated class declaration.

Workspace snapshot: the inspected SDK has local changes. Source links identify its base commit and may differ from this working copy. Verify the SDK build you deploy before relying on unreleased behavior.

Call this after plandalf.ready(). The browser wrapper can return undefined before initialization.

Signature

plandalf.gate(
  name: string,
  sync?: GateSyncCallback,
  opts?: Partial<FlowOpenOptions>,
): Promise<GateResult>

Arguments

Name	Type	Meaning
`name`	`string`	Name registered with `addGate()`.
`sync?`	`GateSyncCallback`	Optional callback to refresh entitlements after purchase. The browser wrapper declares this argument as `any` and passes it to the typed class method.
`opts?`	`Partial`<`FlowOpenOptions`>	Flow options for the fallback offer. The browser wrapper declares this argument as `any` and passes it to the typed class method.

Example

gate.js

plandalf.ready(async () => {
  plandalf.addGate('export', 'upgrade', () => false)
  const result = await plandalf.gate('export')
  if (result.access) {
    // Ask your server to perform the protected action.
  }
})

Fallback flow options

The opts object accepts these FlowOpenOptions fields.

Field	Type	Meaning
`confirmClose?`	() => `boolean` \| `Promise`<`boolean`>	Merchant-supplied "are you sure?" gate. Resolved `true` allows the close to proceed, `false` keeps the frame open. Replaces the previous boolean + label/title strings combo. Off when omitted.
`context?`	`Record`<`string`, `unknown`>	Initial values for the flow context.
`continuity?`	`ContinuityScope`	Per-call continuity override.
`frame?`	`FrameMode`	Frame modality. Was previously `mode` — renamed because `mode` now means the test/live/preview environment (see below).
`metadata?`	`Record`<`string`, `string`>	Per-call Stripe-customer metadata. Eager string values only — for window-global lookups use the page-global PlandalfConfig.metadata thunk form. Wins over PlandalfConfig.metadata on overlap.
`mode?`	`"test"` \| `"live"` \| `"preview"`	Session mode request. See checkout modes for test authorization and integration requirements.
`price?`	`string` \| `string`[]	Plandalf price lookup key(s) to sell, using this offer as the checkout design. Replaces the offer's own items — e.g. a MemberPress membership page passes the price linked to that membership. Declarative: `data-plandalf-price="gold-monthly,gold-setup-fee"`.
`promo?`	`PromoContext`	Resolved promotion context. The current `present()` implementation also resolves a promo slug string at runtime.
`properties?`	`Record`<`string`, `unknown`>	Per-call form-field prefill defaults. Wins over PlandalfConfig.properties on overlap. See specs/sdk-checkout-config.md.
`session?`	`string` \| `null`	Session continuity token (`cks_…`). Pass explicitly to resume a specific session server-side — cross-device handoff, email "continue your checkout" links, anywhere the merchant has a token in hand. Pass `null` to force a fresh session and skip any stored token. Omit entirely to let the SDK auto-detect.
`sessionId?`	`string`	Reuse an existing session UUID instead of creating a fresh one. Used by the auto-resume path to finalize against the ORIGINAL session after a redirect-based auth bounce — creating a new session would lose the draft upsell invoice that needs settling.
`size?`	`FlowSize` \| { `h`: `string`; `w`: `string`; }	Size of the modal panel. Either a named preset OR an explicit `{ w, h }` object for one-off cases. Defaults to 'standard'.
`templateId?`	`string`	Lower-level template selector. The method supplies `templateSlug` from its slug argument, so this does not select the offer here.
`templateSlug?`	`string`	Can override the slug argument in the current implementation. Pass the desired slug as the method argument instead.
`user?`	`string`	Customer JWT for THIS call only — overrides the SDK-wide identity from `plandalf.setUser()` or the `user` init option. Useful for "buy as customer" admin tooling, impersonation flows, or offers that need a different identity than the global one. The value is the raw JWT string.

Existing subscriptions

The inspected workspace SDK does not declare a subscription selector in FlowOpenOptions or MountOptions. A price lookup key selects what to sell. The inspected backend can derive a subscription target from a signed customer JWT and default the checkout intent to upgrade; that is a separate contract from a per-call SDK option. See customer identity. Before documenting an upgrade journey, verify the deployed route, subscription ownership checks, and the resulting provider subscription in an isolated sandbox. This reference does not sign off that journey.

Checkout modes

Use mode: "test" or mode: "live" to request a session environment. environment is the supported legacy name. The inspected SDK session endpoint permits test mode when the offer has test mode enabled or the caller is an authenticated member of its organization; otherwise it selects live mode. It does not use a JWT mode claim or test-domain setting for this decision.

Connect the organization's Stripe test integration first. Without it, payment selection falls back to live Stripe even for a test session. Check the actual selected payment connection and processor sandbox before submitting payment; the requested mode or a test session label is insufficient. The SDK session endpoint does not enable preview. Verify these contracts against the deployed build before replay.

Supported compatibility options

The current runtime still reads these older fields.

Field	Type	Meaning
`animation?`	`"slide"` \| `"fade"` \| `"none"`	Frame entrance animation.
`backdrop?`	`boolean`	Whether to render a backdrop behind the frame.
`closeButton?`	`boolean`	Whether to show the frame close button.
`closeOnBackdrop?`	`boolean`	Whether a backdrop click closes the frame.
`confirmLeaveLabel?`	`string`	Leave button text in the built-in close confirmation.
`confirmMessage?`	`string`	Message in the built-in close confirmation.
`confirmStayLabel?`	`string`	Stay button text in the built-in close confirmation.
`confirmTitle?`	`string`	Title in the built-in close confirmation.
`duration?`	`number`	Frame animation duration in milliseconds.
`environment?`	`"test"` \| `"live"`	Test or live session routing. The newer per-call name is `mode`.
`height?`	`string`	Explicit frame height.
`onClose?`	(`reason`) => `void`	Callback when the presented flow closes. Await the handle for the final result.
`onComplete?`	(`result`) => `void`	Callback on flow completion. Await the handle for the final result.
`onError?`	(`error`) => `void`	Callback on flow failure. A rejected handle can also be caught.
`position?`	`"left"` \| `"right"`	Frame position, left or right.
`width?`	`string`	Explicit frame width. This takes precedence over a size preset.

Declared without current effect

Field	Type	Meaning
`dragToClose?`	`boolean`	Collected into frame config, but not passed to the rendered frame.
`headless?`	`boolean`	Declared in the type, but the checkout implementation does not read it.

Returns

Promise<GateResult>

Behaviour

The sync callback can refresh entitlements after purchase. The returned GateResult describes whether access was granted.

All plandalf methods