# Donation Integration

Source: https://docs.ezoic.com/docs/subscriptions/donations/


Donations let readers support your work without buying a subscription. A donation does not unlock pages, grant a product, or change what content a visitor can see.

## Open A Donation Dialog

There's no setup call. Add a trigger and the widget loads your donation settings the first time it's used. You can open the donation checkout two ways:

- a **declarative button** — any element with `data-ezoic-donate`, no JavaScript; or
- **`openDonation()`** from your own click handler.

`openDonation()` opens the donation checkout and `closeDonation()` closes it. Both work as soon as the widget script has loaded — no other call is required.

## Add A Support Button

The simplest scripted integration is a "Support our work" button that opens the donation picker, where the reader chooses how much to give. Call `openDonation()` with no preset amount.

```html
<button type="button" id="support-button">Support our work</button>

<script>
  window.ezsubscriptions = window.ezsubscriptions || {};
  ezsubscriptions.cmd = ezsubscriptions.cmd || [];
  ezsubscriptions.cmd.push(function () {
    document.getElementById("support-button").addEventListener("click", function () {
      ezsubscriptions.openDonation();
    });
  });
</script>
<script src="https://sm.ezoic.com/min.js" async defer></script>
```

## Preset A Donation Amount

If you want a button to preselect an amount — for example a "Give $25" tier — pass `amountCents`. The reader can still change it in the picker.

```html
<button type="button" id="give-25">Give $25</button>

<script>
  window.ezsubscriptions = window.ezsubscriptions || {};
  ezsubscriptions.cmd = ezsubscriptions.cmd || [];
  ezsubscriptions.cmd.push(function () {
    document.getElementById("give-25").addEventListener("click", function () {
      ezsubscriptions.openDonation({ amountCents: 2500 });
    });
  });
</script>
<script src="https://sm.ezoic.com/min.js" async defer></script>
```

`amountCents` is a preset amount in cents. For example:

- `500` means `$5.00`.
- `2500` means `$25.00`.
- `10000` means `$100.00`.

Currency is not passed to `openDonation`. The picker presents the currency the visitor sees — see [Currencies](#currencies) — and `amountCents` is interpreted in that currency's smallest unit.

If `amountCents` is missing, invalid, or below the minimum configured in the dashboard, the widget falls back to the normal donation picker. The backend still enforces the minimum amount.

## Currencies

By default the donation picker presents your donation's currency (USD unless you change it), and checkout automatically presents a local-currency equivalent to international visitors. The converted amounts follow the exchange rate, so they are rarely round numbers, and the buyer pays a small conversion fee on top; visitors can always switch back to your listed currency at checkout. Automatic currency conversion is on by default; you can turn it off in the Ezoic dashboard's Subscriptions area under **Settings → Ways buyers pay → Adaptive Pricing**.

**Recommended:** set your own price points per market with **additional currencies** in the donation settings — each currency gets its own minimum and suggested amounts (for example ₹199 / ₹499 / ₹999 for visitors in India instead of a converted $5 / $10 / $25). A visitor whose region matches one of your currencies sees and pays those amounts in that currency — no conversion, no conversion fee. Everyone else gets the default currency with automatic local-currency presentment at checkout.

## Declarative Button Option

You can also mark a button with attributes and let the widget handle the click:

```html
<button data-ezoic-donate data-ezoic-amount-cents="2500">
  Support our work
</button>

<script src="https://sm.ezoic.com/min.js" async defer></script>
```

The `data-ezoic-amount-cents` value follows the same cents format as `openDonation({ amountCents })`. Omit it to open the picker with no preset amount. Add `data-ezoic-product-id` with a donation product ID to target a specific donation — the declarative equivalent of `openDonation({ productId })`; rarely needed, since a site has one active donation.

## React To A Completed Donation

Pass `onSuccess`, `onCancel`, or `onError` to `openDonation()` to react to a donation — for example to reveal a thank-you message:

```html
<button type="button" id="support-button">Support our work</button>
<p id="donate-thanks" hidden>Thanks for your support!</p>

<script>
  window.ezsubscriptions = window.ezsubscriptions || {};
  ezsubscriptions.cmd = ezsubscriptions.cmd || [];
  ezsubscriptions.cmd.push(function () {
    document.getElementById("support-button").addEventListener("click", function () {
      ezsubscriptions.openDonation({
        onSuccess: function () {
          document.getElementById("donate-thanks").hidden = false;
        },
      });
    });
  });
</script>
<script src="https://sm.ezoic.com/min.js" async defer></script>
```

Callbacks only work through `openDonation()`. A declarative `[data-ezoic-donate]` button can't carry `onSuccess`, `onCancel`, or `onError` — to run code after a donation, open it from your own click handler with `openDonation({ onSuccess })` as shown above.

## Dashboard Prerequisite

Before the onsite donation API can open checkout, donations must be enabled for the site:

1. Open the Ezoic Subscriptions area in the Ezoic dashboard.
2. Open the **Products** page.
3. Turn on **Enable donations**.
4. Set the donation label, such as `Support our work`.
5. Set the minimum donation amount and suggested amounts.
6. Optionally add additional currencies with their own minimums and suggested amounts (see [Currencies](#currencies)).
7. Save settings.

Donations are pay-what-you-want above the minimum amount you set. A site has one active donation at a time. To change the label or minimum amount later, edit the donation on the Products page and save — there's no need to turn donations off first.

## Closing The Dialog

Donation checkout is dismissible. If your UI needs to close it programmatically, call:

```javascript
ezsubscriptions.closeDonation();
```

This only affects the donation dialog. It does not close or bypass the paid-access paywall for subscriber content.

For full `openDonation()`, `closeDonation()`, and callback details, see [JavaScript API Reference](/docs/subscriptions/api-reference/).