JavaScript SDK

The Fungies JavaScript SDK provides a programmatic way to open checkout experiences in your web application.

Installation

npm install @fungies/fungies-js

Versioning

The SDK follows semantic versioning: breaking changes bump the major version, and minor and patch releases stay backwards compatible.

Pin at least the major version. On the CDN that is @fungies/fungies-js@0, as in the snippets on this page; from npm, install a range that stays within it. Avoid @latest — it would pull a future major into production without warning. The current published version is 0.7.3.

Initialization

import { Fungies } from "@fungies/fungies-js";

// Initialize the SDK
Fungies.Initialize({
  enableDataAttributes: true, // default: true
});

Opening Checkout

Overlay Mode

Opens checkout in a full-screen modal overlay:

Fungies.Checkout.open({
  checkoutUrl: "https://yourstore.fungies.io/checkout-element/your-checkout-id",
  settings: {
    mode: "overlay",
  },
});

Embed Mode

Renders checkout inside a target DOM element:

Fungies.Checkout.open({
  checkoutUrl: "https://yourstore.fungies.io/checkout-element/your-checkout-id",
  settings: {
    mode: "embed",
    frameTarget: "checkout-container", // ID of the target element
  },
});

<div id="checkout-container"></div>

Checkout Options

Option	Type	Description
`checkoutUrl`	`string`	Required. The checkout URL from your Fungies dashboard
`settings.mode`	`"overlay"` \| `"embed"`	Display mode for the checkout
`settings.frameTarget`	`string`	DOM element ID for embed mode
`customerEmail`	`string`	Customer email (deprecated, use `billingData.email`)
`billingData`	`object`	Prefilled billing information (see below)
`discountCode`	`string`	Discount code to apply
`quantity`	`number`	Quantity for every adjustable offer on the element
`items`	`array`	Accepted but not applied — see Quantity
`customFields`	`object`	Custom field values

Billing Data Object

Prefill customer billing information:

Fungies.Checkout.open({
  checkoutUrl: "...",
  settings: { mode: "overlay" },
  billingData: {
    email: "customer@example.com",
    firstName: "John",
    lastName: "Doe",
    country: "US", // ISO 3166-1 alpha-2 code
    state: "CA", // State/province code
    city: "Los Angeles",
    zipCode: "90001",
  },
});

Field	Type	Description
`email`	`string`	Customer email address
`firstName`	`string`	Customer first name
`lastName`	`string`	Customer last name
`country`	`string`	Country code (ISO 3166-1 alpha-2, e.g., `US`, `GB`, `PL`)
`state`	`string`	State or province
`city`	`string`	City name
`zipCode`	`string`	Postal/ZIP code

Quantity

A checkout element sells the offers it was created with. You cannot add offers to it at open time — create a different element for a different set of offers.

quantity applies to every offer on the element whose quantity is adjustable; offers with a fixed quantity stay at 1.

Fungies.Checkout.open({
  checkoutUrl: "...",
  settings: { mode: "overlay" },
  quantity: 2,
});

items is accepted but currently has no effect — per-offer quantities are not applied, and passing an offerId that is not on the element neither adds it nor raises an error. Use quantity instead, and do not build a cart on top of items expecting it to work.

Custom Fields

Pass custom field values to the checkout:

Fungies.Checkout.open({
  checkoutUrl: "...",
  settings: { mode: "overlay" },
  customFields: {
    user_id: "usr_123",
    server_region: "US-West",
  },
});

Closing Checkout

Programmatically close the checkout:

Fungies.Checkout.close();

Listening to checkout events

The SDK listens for messages from the checkout iframe and dispatches DOM events on document. This happens automatically when you call Fungies.Initialize() or use the data-auto-init script attribute — no extra setup is required.

Use these events to run your own logic after a purchase (redirect to a thank-you page, refresh entitlements, show a confirmation modal, etc.).

Event	When it fires
`fungies:checkout:complete`	The customer completed checkout successfully
`fungies:checkout:close`	The checkout was closed (by the customer or after completion)

Import event name constants from the package (recommended):

import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

Fungies.Initialize();

document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, () => {
  window.location.href = "/thank-you";
});

document.addEventListener(DOM_CHECKOUT_EVENTS.CLOSE, () => {
  console.log("Checkout closed");
});

With the CDN script tag, register listeners after the SDK loads:

<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@0"
  defer
  data-auto-init
></script>
<script>
  document.addEventListener("fungies:checkout:complete", () => {
    window.location.href = "/thank-you";
  });
</script>

In React, attach listeners in a useEffect and remove them on unmount:

import { useEffect } from "react";
import { DOM_CHECKOUT_EVENTS, Fungies } from "@fungies/fungies-js";

function App() {
  useEffect(() => {
    Fungies.Initialize();

    const onComplete = () => {
      window.location.href = "/thank-you";
    };

    document.addEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    return () => {
      document.removeEventListener(DOM_CHECKOUT_EVENTS.COMPLETE, onComplete);
    };
  }, []);

  return (
    <button
      onClick={() =>
        Fungies.Checkout.open({
          checkoutUrl:
            "https://yourstore.fungies.io/checkout-element/your-checkout-id",
          settings: { mode: "overlay" },
        })
      }
    >
      Buy
    </button>
  );
}

DOM Scanning

If you dynamically add checkout buttons after page load, trigger a manual scan:

Fungies.ScanDOM();

Complete Example

import { Fungies } from "@fungies/fungies-js";

// Initialize
Fungies.Initialize();

// Open checkout with all options
document.getElementById("buy-button").addEventListener("click", () => {
  Fungies.Checkout.open({
    checkoutUrl: "https://yourstore.fungies.io/checkout-element/abc123",
    settings: {
      mode: "overlay",
    },
    billingData: {
      email: currentUser.email,
      firstName: currentUser.firstName,
      lastName: currentUser.lastName,
      country: currentUser.country,
    },
    discountCode: "SUMMER20",
    quantity: 1,
    customFields: {
      user_id: currentUser.id,
    },
  });
});

JavaScript SDK

On this page