Troubleshooting
Solutions for common issues with widget installation, button detection, subscriber identification, and gateway connections.
Widget not loading?
Start by verifying the embed snippet is placed before the closing </body> tag in your site's HTML. Open your browser's developer console (F12) and look for errors related to the SubJolt script. The most common cause is a Content Security Policy (CSP) that blocks external scripts — you may need to add the SubJolt script domain to your CSP's script-src directive. Ad blockers and privacy extensions can also prevent the widget from loading. Test in an incognito window with extensions disabled to rule this out. If you recently updated your site, clear your browser cache and any server-side caches (CDN, Cloudflare, etc.) since stale cached pages won't include the new script tag. For tag manager deployments, verify the tag is published and its trigger is firing on the correct pages.
Platform-specific installation tips
On Squarespace, use the site-wide Code Injection panel (Settings > Developer Tools > Code Injection) rather than per-page code injection, which only applies to individual pages. On Wix, set your custom code to load in the Body - End position with All Pages selected — Wix's editor sometimes defaults to Head placement, which can cause timing issues. On BigCommerce, use the Script Manager (Storefront > Script Manager) and set the placement to Footer. For Kajabi and Teachable, paste the code in the Footer section of your site's code snippet settings.
Cancel button not detected?
If SubJolt isn't intercepting your cancel button, the button selector configured during setup may no longer match the actual button on your page. This commonly happens after site redesigns, theme updates, or changes to your billing portal. Re-run the setup wizard from your account menu — the button detection step will scan your cancel page and update the selector. If auto-detection doesn't find the button (for example, in SPAs where the button renders after user interaction), you can set a manual CSS selector in the setup wizard. Make sure the cancel URL in your configuration matches the exact page where the cancel button appears. For single-page applications, the button must be present in the DOM when the widget scans — if it's behind a modal or loaded lazily, the manual selector approach is more reliable.
Subscriber not identified?
SubJolt identifies subscribers using information available on your cancel page to match them against your payment gateway's records. If a subscriber isn't being identified, first verify that the cancel URL in your configuration is correct — SubJolt only performs identification on that specific page. The page must contain subscriber-related information (like a subscription ID, customer ID, or email) that SubJolt can match against your gateway. If you're using a billing portal, check that the subscriber is logged in when they reach the cancel page, since identification depends on context available in the page. For persistent issues, verify your gateway connection is active by checking the settings editor. If the gateway is disconnected or the credentials have expired, SubJolt can't look up subscribers even when the page context is correct. Log in to your dashboard for step-by-step help with identification setup.
Gateway connection issues?
Gateway connections can fail when credentials expire, get revoked, or lose required permissions. For OAuth gateways (Stripe, Shopify), connections break if you revoke SubJolt's access from your gateway's dashboard or if your gateway account changes significantly (like switching Stripe accounts). Re-run the setup wizard to reconnect — the OAuth flow will request fresh credentials. For API key gateways (Chargebee, Recharge, Recurly), verify your API key is still valid and hasn't been rotated. Check that the key has the required permissions — read and write access to subscriptions and customers. If you recently updated your API key in your gateway's dashboard, enter the new key in the SubJolt setup wizard. The settings editor shows your current gateway connection status so you can quickly confirm whether the connection is active.
Testing before going live?
Use the Preview page in your SubJolt dashboard to test every cancel flow path before it reaches real subscribers. Preview loads your site and simulates the full widget experience — reason selection, feedback screens, save offers, and confirmation — without making any real API calls to your payment gateway. No subscriptions will be cancelled, paused, or modified during preview. Walk through each cancellation reason to verify the correct flow steps appear in the right order. Check that offer copy reads well and that the theming matches your site. If you've configured reason-specific flows, test each reason individually. After going live, you can return to Preview anytime to test changes before they affect real subscribers. The Preview page uses your current saved configuration, so any recent edits in the settings editor are immediately reflected.
Save actions not executing?
If a subscriber accepts a retention offer but the action doesn't apply to their subscription, start by checking your gateway connection. Open the settings editor and verify the connection status is active — an expired token or revoked API key prevents SubJolt from reaching your gateway. Next, confirm the subscriber's subscription is in an active state. Some gateways reject modifications to subscriptions that are already past due, in a trial period, or scheduled for cancellation through another channel. If the connection is active and the subscription is eligible, the issue may be with the specific offer configuration — for example, a plan downgrade pointing to a plan ID that no longer exists in your gateway. Check your offer settings and verify the referenced plan IDs match your current gateway catalog. For persistent issues, contact support with the subscriber's details and we'll trace the action through our logs.
Troubleshooting FAQ
Still stuck?
Our support team is ready to help diagnose and fix any issues.