> ## Documentation Index
> Fetch the complete documentation index at: https://docs.fungies.io/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Integrate Fungies checkout using the JavaScript SDK.

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

## Installation

<CodeGroup>
  ```bash npm theme={null}
  npm install @fungies/fungies-js
  ```

  ```bash yarn theme={null}
  yarn add @fungies/fungies-js
  ```

  ```bash pnpm theme={null}
  pnpm add @fungies/fungies-js
  ```

  ```html CDN theme={null}
  <script
    src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@latest"
    defer
    data-auto-init
  ></script>
  ```
</CodeGroup>

## Initialization

```javascript theme={null}
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:

```javascript theme={null}
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:

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

```html theme={null}
<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`                 | Product quantity                                           |
| `items`                | `array`                  | Items for multi-product checkout                           |
| `customFields`         | `object`                 | Custom field values                                        |

## Billing Data Object

Prefill customer billing information:

```javascript theme={null}
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                                           |

## Multi-Product Checkout

Specify quantities for multiple offers:

```javascript theme={null}
Fungies.Checkout.open({
  checkoutUrl: "...",
  settings: { mode: "overlay" },
  items: [
    { offerId: "offer-id-1", quantity: 2 },
    { offerId: "offer-id-2", quantity: 1 },
  ],
});
```

## Custom Fields

Pass custom field values to the checkout:

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

## Closing Checkout

Programmatically close the checkout:

```javascript theme={null}
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):

```javascript theme={null}
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:

```html theme={null}
<script
  src="https://cdn.jsdelivr.net/npm/@fungies/fungies-js@latest"
  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:

```tsx theme={null}
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:

```javascript theme={null}
Fungies.ScanDOM();
```

## Complete Example

```javascript theme={null}
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,
    },
  });
});
```