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

# JavaScript API

> Programmatic control of Cuprice widgets

After `embed.js` loads, a global `window.Cuprice` object is available with methods for controlling widgets programmatically. This is especially useful in SPA frameworks.

## Methods

### `Cuprice.refresh()`

Re-scans the DOM for new `data-cuprice-id` or `data-cuprice-billing` containers and initializes any that haven't been loaded yet.

```javascript theme={null}
// After dynamically adding a Cuprice container
document.getElementById("pricing").innerHTML =
  '<div data-cuprice-id="abc123"></div>';
window.Cuprice.refresh();
```

> [!NOTE]
>
> In most cases you don't need this — `embed.js` uses a MutationObserver to automatically detect new containers added to the DOM.

### `Cuprice.reset(element)`

Removes a widget from a container and allows re-initialization. Useful when you need to swap a Share ID.

```javascript theme={null}
const el = document.querySelector("[data-cuprice-id]");
window.Cuprice.reset(el);
el.setAttribute("data-cuprice-id", "NEW_SHARE_ID");
window.Cuprice.refresh();
```

### `Cuprice.destroy()`

Removes all event listeners and disconnects the MutationObserver. Call this when your page or component unmounts.

```javascript theme={null}
// React cleanup
useEffect(() => {
  // ... setup
  return () => {
    if (window.Cuprice) window.Cuprice.destroy();
  };
}, []);
```

### `Cuprice.origin`

Returns the detected Cuprice origin URL (read-only).

```javascript theme={null}
console.log(window.Cuprice.origin);
// "https://app.cuprice.io"
```

## Events

### `cuprice:plan-selected`

Dispatched on `document` when a customer selects a plan in the billing widget.

```javascript theme={null}
document.addEventListener("cuprice:plan-selected", function(e) {
  console.log(e.detail.planId);         // number
  console.log(e.detail.planName);       // string
  console.log(e.detail.billingInterval); // "month" | "year"
  console.log(e.detail.shareId);        // string
});
```

### `cuprice:checkout`

Dispatched on `document` when a buyer picks a plan and the project's embed behavior is **postMessage** (set under **Integration > Payment**). It fires for the pricing embed and the billing widget alike. See [Checkout Link](https://docs.cuprice.io/payments/checkout-link.md#redirect-or-postmessage).

```javascript theme={null}
document.addEventListener("cuprice:checkout", function(e) {
  console.log(e.detail.payload);    // the checkout payload: plan, features, pricingBreakdown, metadata
  console.log(e.detail.handoffUrl); // your checkout link with the query parameters, or null
  console.log(e.detail.shareId);    // string
});
```

The payload fields are described in [Checkout Flow](https://docs.cuprice.io/payments/checkout-flow.md#the-checkout-payload).

## Explicit origin

If origin detection fails (e.g., behind a CDN), set it explicitly:

```html theme={null}
<script
  src="https://app.cuprice.io/embed.js"
  data-cuprice-origin="https://app.cuprice.io"
  async
></script>
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.