Configure the SDK — Plandalf docs

Most projects only need plandalf.present(offer). Add options when you need control over the checkout environment, frame, customer, or campaign context.

Configuration surfaces

The same concepts appear in JavaScript options, declarative HTML attributes, and global configuration.

Per-call JavaScript

plandalf.present("pro-plan", { frame: "slideout", mode: "test" })

Use this when a button or app event should decide checkout behavior at click time.

Declarative HTML

<button data-plandalf-present="pro-plan" data-plandalf-frame="slideout">

Use this in page builders, CMS blocks, and static pages where you want minimal JavaScript.

Global configuration

plandalf("configure", { continuity: "tab", metadata: { source: "pricing" } })

Use this for defaults shared across all checkout calls on the page.

Per-call identity

plandalf.present("pro-plan", { user: customerJwt })

Use this when a single checkout should run with a specific customer identity.

Present an offer

const result = await plandalf.present("pro-plan", {
  // Use a slideout when checkout should feel attached to the current page.
  frame: "slideout",
  // Test mode creates sessions without charging real payment methods.
  mode: "test",
  // Wide gives multi-step or add-on heavy offers more horizontal room.
  size: "wide"
});

Options reference

Option	Values	Use it for
`frame`	`modal`, `slideout`, `bottom`, `fullscreen`, `embedded`	How checkout appears.
`mode`	`test`, `live`, `preview`	Which environment the session uses.
`size`	`compact`, `standard`, `wide`, `fullscreen`, or `{ w, h }`	Frame dimensions.
`promo`	promo slug	Apply active promo-tier pricing to this offer.
`user`	JWT or email	Per-call customer identity override.
`continuity`	`false`, `tab`, `browser`	Whether draft sessions can resume.
`session`	`cks_...` or `null`	Resume a specific session token or force a fresh session.
`properties`	object	Prefill checkout fields and pass custom form context.
`metadata`	object	Pass Stripe-bound attribution metadata.
`confirmClose`	boolean or function	Add close confirmation for longer flows.

Frame versus mode

frame controls presentation.

// Frame controls how checkout is displayed.
plandalf.present("pro-plan", { frame: "modal" });
plandalf.present("pro-plan", { frame: "bottom" });
plandalf.present("pro-plan", { frame: "fullscreen" });

mode controls environment.

// Mode controls which Plandalf environment creates the checkout session.
plandalf.present("pro-plan", { mode: "test" });

Use frame for presentation and mode for environment.

Declarative attributes

The same public option names map to data-plandalf-* attributes.

<!-- The SDK opens this published offer when the button is clicked. -->
<button
  data-plandalf-present="pro-plan"
  data-plandalf-frame="slideout"
  data-plandalf-mode="test"
  data-plandalf-size="wide"
  data-plandalf-apply-promo="early-bird"
>
  Buy now
</button>

Global configuration

Use the queue form before the SDK loads.

<script>
  // Configure defaults once; individual present() calls can still override them.
  plandalf("configure", {
    // Resume draft sessions in this browser tab.
    continuity: "tab",
    properties: {
      // Pass page context into checkout and downstream events.
      source: "pricing-page"
    },
    metadata: {
      // Read late-loading attribution values when checkout starts.
      tolt_referral: () => window.tolt_referral
    }
  });
</script>

Per-call values on present() override matching global values.

Global configuration explained

continuity: "tab"

Lets a draft checkout resume in the current browser tab without making every checkout on the site browser-wide.

properties: { source: "pricing-page" }

Prefills or passes form context into checkout. Per-call properties override these defaults.

metadata: { tolt_referral: () => window.tolt_referral }

Reads attribution data lazily when checkout starts, which helps when an affiliate script loads after the Plandalf script.

Close confirmation

plandalf.present("application", {
  confirmClose: async () => {
    // Return true to close the frame, or false to keep checkout open.
    return window.confirm("Leave checkout?");
  }
});

Return true to allow close and false to keep the frame open.

Configuration surfaces

Present an offer

Options reference

Frame versus mode

Declarative attributes

Global configuration

Global configuration explained

Close confirmation

Related docs

Move from SDK setup to the commerce surface.