# Configure the SDK
Configure frame style, test mode, size, promos, identity, session continuity, metadata, properties, and close behavior.
Source: /docs/sdk/configure
Last modified: 2026-06-18
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

```js
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.

```js
// 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.

```js
// 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.

```html
<!-- 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.

```html
<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

```js
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.

## Related docs

- [Session continuity](/docs/sdk/session-continuity)
- [Identify customers](/docs/sdk/identity)
- [Live events](/docs/sdk/events)
- [Embedded promos](/docs/timers/embedded-promos)