Interface: FlowOpenOptions

Defined in: packages/sdk/src/core/types.ts:530

Extends

• FlowStartOptions

FlowOpenOptions and its parent FlowStartOptions are active interfaces. Some migration comments in the TypeScript source are stale: the checkout runtime still reads older fields. The groups below reflect current behavior.

Properties

confirmClose?

optional confirmClose?: () => boolean | Promise<boolean>

Defined in: packages/sdk/src/core/types.ts:566

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.

Returns

boolean | Promise<boolean>

context?

optional context?: Record<string, unknown>

Defined in: packages/sdk/src/core/types.ts:499

Inherited from

FlowStartOptions.context

continuity?

optional continuity?: ContinuityScope

Defined in: packages/sdk/src/core/types.ts:540

Per-call continuity override.

frame?

optional frame?: FrameMode

Defined in: packages/sdk/src/core/types.ts:546

Frame modality. Was previously mode — renamed because mode now means the test/live/preview environment (see below).

metadata?

optional metadata?: Record<string, string>

Defined in: packages/sdk/src/core/types.ts:579

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?

optional mode?: "test" | "live" | "preview"

Defined in: packages/sdk/src/core/types.ts:553

Environment override: 'test' | 'live' | 'preview'. Was previously environment. The server uses this to route the session through the org's test or live integration; super-admin only.

promo?

optional promo?: PromoContext

Defined in: packages/sdk/src/core/types.ts:501

Inherited from

FlowStartOptions.promo

properties?

optional properties?: Record<string, unknown>

Defined in: packages/sdk/src/core/types.ts:572

Per-call form-field prefill defaults. Wins over PlandalfConfig.properties on overlap. See specs/sdk-checkout-config.md.

session?

optional session?: string | null

Defined in: packages/sdk/src/core/types.ts:537

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?

optional sessionId?: string

Defined in: packages/sdk/src/core/types.ts:515

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.

Inherited from

FlowStartOptions.sessionId

size?

optional size?: FlowSize | { h: string; w: string; }

Defined in: packages/sdk/src/core/types.ts:559

Size of the modal panel. Either a named preset OR an explicit { w, h } object for one-off cases. Defaults to 'standard'.

templateId?

optional templateId?: string

Defined in: packages/sdk/src/core/types.ts:491

Inherited from

FlowStartOptions.templateId

templateSlug?

optional templateSlug?: string

Defined in: packages/sdk/src/core/types.ts:490

Inherited from

FlowStartOptions.templateSlug

user?

optional user?: string

Defined in: packages/sdk/src/core/types.ts:498

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.

Inherited from

FlowStartOptions.user

Supported compatibility options

The checkout runtime still reads these options. Prefer the newer frame, size, mode, and awaitable result where they cover the same use case.

animation?

optional animation?: "slide" | "fade" | "none"

Defined in: packages/sdk/src/core/types.ts:599

Frame entrance animation.

backdrop?

optional backdrop?: boolean

Defined in: packages/sdk/src/core/types.ts:595

Whether to render a backdrop behind the frame.

closeButton?

optional closeButton?: boolean

Defined in: packages/sdk/src/core/types.ts:597

Whether to show the frame close button.

closeOnBackdrop?

optional closeOnBackdrop?: boolean

Defined in: packages/sdk/src/core/types.ts:596

Whether a backdrop click closes the frame.

confirmLeaveLabel?

optional confirmLeaveLabel?: string

Defined in: packages/sdk/src/core/types.ts:604

Leave button text in the built-in close confirmation.

confirmMessage?

optional confirmMessage?: string

Defined in: packages/sdk/src/core/types.ts:602

Message in the built-in close confirmation.

confirmStayLabel?

optional confirmStayLabel?: string

Defined in: packages/sdk/src/core/types.ts:603

Stay button text in the built-in close confirmation.

confirmTitle?

optional confirmTitle?: string

Defined in: packages/sdk/src/core/types.ts:601

Title in the built-in close confirmation.

duration?

optional duration?: number

Defined in: packages/sdk/src/core/types.ts:600

Frame animation duration in milliseconds.

environment?

optional environment?: "test" | "live"

Defined in: packages/sdk/src/core/types.ts:587

Test or live session routing. The newer per-call name is mode.

Overrides

FlowStartOptions.environment

height?

optional height?: string

Defined in: packages/sdk/src/core/types.ts:594

Explicit frame height.

onClose?

optional onClose?: (reason) => void

Defined in: packages/sdk/src/core/types.ts:606

Callback when the presented flow closes. Await the handle for the final result.

Parameters

reason

"complete" | "cancel" | "escape"

Returns

void

onComplete?

optional onComplete?: (result) => void

Defined in: packages/sdk/src/core/types.ts:605

Callback on flow completion. Await the handle for the final result.

Parameters

result

FlowResult

Returns

void

onError?

optional onError?: (error) => void

Defined in: packages/sdk/src/core/types.ts:607

Callback on flow failure. A rejected handle can also be caught.

Parameters

error

Error

Returns

void

position?

optional position?: "left" | "right"

Defined in: packages/sdk/src/core/types.ts:594

Frame position, left or right.

width?

optional width?: string

Defined in: packages/sdk/src/core/types.ts:594

Explicit frame width. This takes precedence over a size preset.

Declared without current effect

These fields are in the interface but are not forwarded to the active checkout frame.

dragToClose?

optional dragToClose?: boolean

Defined in: packages/sdk/src/core/types.ts:598

headless?

optional headless?: boolean

Defined in: packages/sdk/src/core/types.ts:500

Inherited from

FlowStartOptions.headless