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

Ezoic Subscriptions handles the donation checkout and payment flow. You decide where to invite readers to contribute.

## 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 current dashboard donation flow uses USD.

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.

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

## 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>
```

To attach these callbacks to declarative `[data-ezoic-donate]` buttons, set them once as page-wide defaults with `showDonations({ onSuccess, onCancel, onError })`. See the [JavaScript API Reference](/docs/subscriptions/api-reference/) for details.

## 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. Go to donation settings.
3. Turn on **Enable donations**.
4. Set the donation label, such as `Support our work`.
5. Set the minimum donation amount in USD.
6. 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 settings 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/).