Donation Integration

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.

<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.

<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 — 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:

<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:

<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).
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:

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.