Troubleshooting

Use this guide when the onsite script, paywall, checkout, donation dialog, SEO markup, or subscriber portal does not behave as expected.

Script Does Not Load 🔗

Check that the script is present on the page:

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

Then check:

  • Browser console errors.
  • Network errors for https://sm.ezoic.com/min.js.
  • Ad blockers or privacy extensions.
  • Content Security Policy restrictions.
  • Whether the script is included on the page where subscriptions should work.

Paywall Does Not Appear 🔗

For publisher-managed access, confirm:

  • Payment setup is active.
  • The offer is live.
  • The tier has the expected access key, and the offer has the expected offer key.
  • Your site calls ezsubscriptions.hasAccess("access-key").
  • Your site calls ezsubscriptions.showPaywall({ offer: "offer-key" }) when access is not allowed.
  • The script runs inside ezsubscriptions.cmd.

The offer value must be the offer key from your Ezoic dashboard. It is not the access key and not the public display name. An unknown or inactive offer key renders nothing.

Visitor Paid But Still Sees The Paywall 🔗

Ask the visitor to refresh the page. If that does not work:

  • Have the visitor use the "Already subscribed?" or login link in the paywall.
  • Confirm checkout completed instead of remaining pending.
  • Confirm your site waits for access verification before revealing full content.
  • Confirm the code checks the same access key that the purchased tier grants.

Full Content Is Visible In Page Source 🔗

If full article content is shipped in the initial HTML, technically advanced visitors may be able to inspect it even if it is visually hidden.

For stronger protection:

  1. Serve only teaser content initially.
  2. Call ezsubscriptions.hasAccess(...).
  3. Fetch or render the protected body only after access is allowed.

The widget provides access checks, paywall UI, checkout, and login. Your site still controls how protected content is delivered.

Paywalled-Content Markup Fails Validation 🔗

For gated article pages, confirm:

  • The page has isAccessibleForFree: false.
  • The page has a hasPart object.
  • hasPart.cssSelector matches the gated content container, such as .paywalled-content.
  • JSON-LD appears in the rendered HTML.
  • Google's Rich Results Test can read the markup.

If the page already has article JSON-LD, merge the paywall fields into that object rather than creating conflicting duplicate article records.

Gated Page Disappeared From Search 🔗

Check for common indexing mistakes:

  • Accidental noindex.
  • robots.txt blocking the URL.
  • Incorrect canonical tags.
  • Server-side gating that blocks crawler access.
  • User-agent-only crawler handling.

Do not cloak content. Follow Google's paywalled-content structured data guidance.

Stripe Checkout Does Not Load 🔗

If your site uses a strict Content Security Policy, allow Stripe. Use Stripe's official Content Security Policy guidance as the source of truth.

Common allowlist entries include:

  • script-src https://js.stripe.com https://*.js.stripe.com
  • frame-src https://js.stripe.com https://*.js.stripe.com https://hooks.stripe.com
  • connect-src https://api.stripe.com https://*.stripe.com
  • img-src https://*.stripe.com

Also check browser console errors and confirm payment setup is active.

Donation Button Does Nothing 🔗

Confirm:

  • Donations are enabled in the Ezoic dashboard.
  • The page calls ezsubscriptions.showDonations() before ezsubscriptions.openDonation(...).
  • Your custom button runs after the widget cmd callback.
  • amountCents is an integer number of cents.
  • amountCents is at least the configured minimum donation amount.

Example:

await ezsubscriptions.showDonations();
ezsubscriptions.openDonation({ amountCents: 2500 });

2500 means $25.00.

Subscriber Cannot Remove A Card 🔗

A saved card may be tied to an active subscription. The subscriber should add or select another card for that subscription first, or cancel the subscription before removing the card.

Subscriber Cannot Log In 🔗

Ask the subscriber to:

  1. Check their email for the latest magic link.
  2. Use the newest link, because links expire and are single-use.
  3. Try signing in at https://subscriber.ezoic.com.

If the subscriber is trying to access content on a different device, they may need to request a fresh login link from the paywall.