Widget not showing on my storefront
The most common reason is that the app block hasn't been added to your theme yet.
To fix this:
- Open CompareKit and go to the Setup page
- Click Open theme editor for either the Product Compare or Collection Compare block
- In the Shopify theme editor, make sure the app block is added to the correct template
- Click Save in the theme editor
Remember that you need to add blocks to both your product page template and your collection page template if you want the widget on both page types.
If you've added the block but it's still not visible, check that it hasn't been hidden in the theme editor — look for the eye icon next to the block name.
For more details on the initial setup, see Getting Started with CompareKit.
"Comparison limit reached" message
This means your store has used all of its monthly comparison allowance. When this happens, new comparisons are blocked and customers see a friendly message instead.
To fix this:
- Go to the Plans page in CompareKit to check your current usage
- If you're at 100%, consider upgrading to a higher plan
- Alternatively, wait for your billing cycle to reset — your allowance renews automatically
If you're on the Starter or Pro plan, you can avoid comparison limits entirely by connecting your own AI API key (BYOK). See Customizing Your Compare Widget for setup instructions.
CompareKit sends email alerts at 80%, 95%, and 100% usage so you can plan ahead. Learn more in Understanding Your Comparison Limits & Billing.
Comparisons are low quality or missing details
The quality of comparison tables depends entirely on the product information available on your store. If comparisons feel thin or vague, the AI doesn't have enough data to work with.
To improve comparison quality:
- Add detailed product descriptions — Include materials, dimensions, weight, use cases, and key selling points
- Use product metafields — Structured specifications give the AI precise data to compare
- Be consistent across products — Use similar formats for specifications within the same category (e.g., always include "Weight" and "Dimensions" for furniture)
- Keep information up to date — Outdated or incorrect specs lead to inaccurate comparisons
The more complete and structured your product data is, the more useful the comparison tables will be.
Widget button appears but nothing happens when clicked
If the compare button shows up but doesn't open the widget panel:
- Check that the app is installed and active — Open CompareKit in your Shopify admin and confirm you see the dashboard
- Verify the app proxy is working — The widget communicates through Shopify's app proxy. If your store has custom proxy configurations, they may conflict
- Check your browser console — Open your browser's developer tools (F12) and look for error messages when clicking the button
- Try a different browser — Rule out browser extensions that might be blocking scripts
If the issue persists, contact support with your store URL and a screenshot of any console errors.
Variant dropdowns not appearing on product cards
Variant comparison is a setting that needs to be enabled, and products need to have multiple variants for the dropdowns to show.
To fix this:
- Go to the Customization page in CompareKit
- Under Widget behavior, make sure Enable variant comparison is turned on
- Save your changes
If the toggle is already on, check that the products you're comparing actually have multiple variants in Shopify. Products with only a single "Default Title" variant won't show a dropdown.
For more on this and other widget settings, see Customizing Your Compare Widget.
Warning about password-protected store
If you see a warning about your store being password-protected, it means CompareKit can't scrape your product pages for comparison data.
To fix this:
- Option 1: Switch the data source to Storefront API on the Customization page. The Storefront API works regardless of password protection.
- Option 2: Remove the password protection from your store if it's no longer needed.
The Storefront API is the recommended data source for most stores anyway, as it's faster and more reliable.
BYOK (own AI key) not working
If you've added your own AI API key but comparisons are failing or still showing as limited:
Make sure you're on the Starter or Pro plan. BYOK is not available on the Free or Development plan — even if you enter a key, it won't be used.
Common issues:
- Invalid API key — Double-check that you've copied the full key from your AI provider's dashboard. Keys are usually long strings starting with a provider-specific prefix (e.g.,
sk-for OpenAI). - Wrong provider selected — Make sure the provider dropdown matches the service your API key is from. An OpenAI key won't work if you've selected Gemini.
- Expired or revoked key — Log into your AI provider's dashboard and confirm the key is still active and has available credits/quota.
- Model override typo — If you've entered a custom model name, make sure it's spelled correctly and is available on your provider's plan. When in doubt, leave the model field blank to use the default.
To verify your setup, go to the Customization page and check that the provider, masked key (last 4 characters), and model all look correct.
Need more help?
If you're experiencing an issue not covered here, visit the Support page inside CompareKit to send us a message. Include your store URL and a description of the problem, and we'll get back to you as quickly as possible.