View as Markdown

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 product is active and has at least one active price.
  • The product has the expected product handle.
  • Your site calls ezsubscriptions.hasAccess("product-handle").
  • Your site calls ezsubscriptions.showPaywall({ product: "product-handle" }) when access is not allowed.
  • The script runs inside ezsubscriptions.cmd.

The product value must be the product handle from your Ezoic dashboard, not the public display name. An unknown or inactive product handle 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 product handle that the purchase 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.
  • Your custom button's click handler runs inside a widget cmd callback.
  • amountCents is an integer number of cents.
  • amountCents is at least the configured minimum donation amount.

Example:

ezsubscriptions.openDonation({ amountCents: 2500 });

2500 means $25.00. openDonation() loads your donation settings on first use, so no setup call is needed.

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

First, have the subscriber sign in the normal way:

  1. Use the site's Log in link (or the paywall's "Already subscribed?" link) to open the sign-in screen for the site's authentication mode.
  2. On Ezoic visitor accounts, sign in with email and password (or Continue with Google, if enabled). On bring your own login, sign in through the site's own login.

If they still can't get in — for example on a new device, or if they bought as a guest — fall back to the one-time email sign-in link:

  1. Request a fresh login link from the paywall.
  2. Check their email for the latest link and use the newest one, since links expire and are single-use.
  3. Or sign in directly at https://subscriber.ezoic.com.