Custom HTML

Use this path for static sites, hand-coded landing pages, CMS templates, and any builder that lets you paste custom HTML. Start with one button that opens one published offer, then add inline checkout, promos, identity, or test mode after the first click works.

Note. Use the SDK primitives directly The Numi share-code generator exposes three canonical install patterns: data-plandalf-present, data-plandalf-mount, and hosted links. Custom HTML pages use the first two.

The path

1. Load the organization SDK

   Add the SDK script from your organization host on pages that contain a checkout button, inline checkout, or promo widget.

2. Add one buying action

   Put data-plandalf-present on a button or link and use the offer slug as the value.

3. Choose the frame only when needed

   Keep the default modal first. Add data-plandalf-frame, data-plandalf-size, or data-plandalf-mode after the basic button works.

4. Test the full path

   Open checkout, complete a test session, and verify redirects, invoices, webhooks, and automations.

Minimal install

<script src="https://acme.plandalf.dev/js/plandalf-sdk.js" async></script>

<button data-plandalf-present="pro-plan">
  Buy Pro
</button>

<div data-plandalf-mount="pro-plan" style="min-height: 480px"></div>

Add options

Use attributes when the behavior belongs to the element. Use JavaScript when you need to compute values from page state, analytics, or logged-in user context.

Supported HTML attributes

• data-plandalf-present (offer slug): Opens the offer in a frame when the element is clicked.

• data-plandalf-mount (offer slug): Renders the offer inline inside that element.

• data-plandalf-frame (modal | slideout | bottom | fullscreen): Controls the presentation frame for trigger buttons.

• data-plandalf-size (compact | standard | wide | fullscreen): Controls the frame size for trigger buttons.

• data-plandalf-apply-promo (promo slug): Applies active promo-tier pricing to the offer.

• data-plandalf-mode (live | test | preview): Routes the checkout through the selected environment.

Programmatic control

When a page needs custom logic, load the SDK before your code and use the plandalf object directly. The blocking script in this example makes the order explicit; simple attribute-based buttons can keep the async script above.

<script src="https://acme.plandalf.dev/js/plandalf-sdk.js"></script>
<script>
plandalf.ready(() => {
  document.querySelector("[data-buy-pro]").addEventListener("click", () => {
    plandalf.present("pro-plan", {
      frame: "slideout",
      mode: "test"
    });
  });
});
</script>

Tip. Keep promo widgets separate from promo pricing Use data-plandalf-promo on a standalone element to render a countdown or promo widget. Use data-plandalf-apply-promo on present or mount elements to apply the promo price to checkout.

For a complete configuration example, create two prices on one checkout item, then map them to the promo’s timed and fallback tiers. The illustrated replay shows USD 25 before the deadline and USD 50 after reopening checkout. Payment verification remains a separate required step.

Add a countdown

Create a promo using the illustrated setup guide. Confirm that its organization has a public SDK host and use that same host on your HTML page. Record the campaign identifier, tier deadlines and expiry destination. The editor’s Live label does not by itself prove that the public countdown is available. Put the widget on a test page before connecting it to a buying action.

This example mounts the real countdown and keeps the visitor on the page while you inspect it. Replace the organization host and promo slug. Load the SDK once per page.

<div id="countdown"></div>
<script>
var plandalf = plandalf || function () {
  (plandalf.q = plandalf.q || []).push(arguments);
};
plandalf('ready', sdk => {
  sdk.promo('early-bird', {
    target: '#countdown',
    redirect: false
  });
});
</script>
<script src="https://acme.plandalf.dev/js/plandalf-sdk.js" async></script>

Use a short deadline in a dedicated test promo. Watch it reach the next tier, then reload in the same browser: a relative deadline should retain that visitor’s original start time. Test the final expiry state too. A permanent final tier has no running deadline; check its checkout price separately.

redirect: false disables automatic navigation for this check. To test a deadline funnel, follow the illustrated redirect replay to configure tier destinations and repeat with redirects enabled. A standalone countdown does not change the checkout price. Follow the linked promo guide to apply the same promo to the buying action, then verify the amount before and after the deadline.

Track affiliate referrals

Set up an active program and use its dedicated test partner from the affiliate quickstart. Copy that partner’s link to your HTML page. The default referral parameter is via; use your program’s configured parameter if it differs.

1. Open the partner link in a fresh browser session. The organization SDK must run on this landing page.
2. Optionally show the captured partner with the code below. Add the callback to the same SDK setup block as your other features.
3. Open the Plandalf checkout from that page and complete a verified sandbox purchase.
4. Match the paid invoice to the partner’s sale and commission in Plandalf. For subscriptions, also test a renewal and refund. Replaying the same payment event must not create another commission.

<div id="partner"></div>
<script>
plandalf('ready', sdk => {
  sdk.referral({ target: '#partner', theme: 'light' });
});
</script>

The badge shows captured attribution. It does not prove that a sale or commission was recorded. With a Plandalf checkout, use its native attribution path; do not also report the same sale through a custom sales adapter.

Verify checkout and delivery

Before submitting payment, verify the connected processor account and price are in its sandbox. A mode: 'test' option alone is not enough. Use a controlled buyer and the processor’s official test inputs.

An HTML embed supplies the buying surface. If your product requires an email, course account or another external action, configure and verify that delivery separately. For a custom destination, start with the webhook reference. Keep failures tied to the original session or invoice; inspect its status before submitting another payment.

Replay the HTML button, one step at a time

These screenshots were captured from the real HTML fixture on 8 October 2026. They cover public configuration, SDK readiness, opening and closing checkout, page reload and reopening. The replay used the local organization SDK; it does not establish release readiness, a fresh referral, a payment or fulfilment.

From this repository, serve the fixture and open http://127.0.0.1:4335/:

python3 -m http.server 4335 --bind 127.0.0.1 --directory scripts/integration-factory/fixtures/html

You need your own configured test offer and public organization SDK URL. The fixture directory contains the real HTML, JavaScript and stylesheet used here. No promo was configured in this replay; countdown and price-transition steps require separate verification.

1. Open the HTML example

Open the fixture URL. The grey text in the empty fields is placeholder text, not saved configuration. Only enter public SDK configuration here; the example puts it in the URL.

2. Enter your public SDK URL

Paste the public organization SDK URL into Organization SDK URL. The screenshot uses flindev.numi.test, a local development host; use your own organization URL.

3. Enter your offer slug

Paste the checkout’s offer slug into Offer slug. For this button-only replay, leave Promo slug and Test partner code empty, and leave Apply this promo to the test checkout unchecked. Placeholder text does not mean a value has been entered.

4. Run the example

Choose Run example. Wait for Organization SDK loaded and an enabled Open test checkout button. The screenshot displays a retained Plandalf test referral from earlier browser state; this run did not capture a new referral.

5. Open checkout

Choose Open test checkout. Wait for the actual checkout. Verify the product, recurrence and total against your offer. This existing local offer showed Plandalf Checkouts Monthly, billed monthly, with $25.00 due today. Provider sandbox verification remains separate; no payment was submitted.

6. Close the checkout

Use the checkout’s close/back control at the upper right. Confirm the page and its checkout button remain usable.

7. Reload the page

Reload using the browser. Confirm Organization SDK loaded returns and the checkout button is enabled. The public configuration remains in the fixture URL; no credentials are stored there.

8. Open checkout after reload

Choose Open test checkout again. Confirm the actual offer opens once with the same product, billing period and amount. Close it when finished. Reopening a form does not verify payment, customer access or delivery.

Related docs

• Configure the SDK — See frame, mode, promo, identity, metadata, and close behavior.

• Add to your site — Choose button, inline checkout, hosted checkout, or direct link patterns.

• Embedded promos — Render promo widgets and connect them to offer pricing.

Integration overview

See Plandalf with HTML for the integration overview.