Skip to main content
Most issues with MerchantAI fall into a small number of categories: something wasn’t indexed correctly, a script didn’t load as expected, or a configuration setting needs adjusting. The sections below walk through the most common problems and their fixes. Work through the relevant steps before reaching out to support — in most cases, you’ll be unblocked quickly.

​
Agent Setup

If pages from your site aren’t appearing in your knowledge base after a crawl, check the following:
  1. Confirm the URL is publicly accessible. The MerchantAI crawler cannot access pages behind a login, staging password, or VPN. Verify you can open the URL in an incognito browser without signing in.
  2. Trigger a manual re-crawl. Go to Knowledge → Website in your dashboard and select Re-crawl. This forces a fresh pass and updates the indexed content.
  3. Check your robots.txt. If your site’s robots.txt blocks unknown crawlers, add the MerchantAI crawler user-agent to the allow list.
Pages added or updated after your last crawl won’t appear automatically — trigger a manual re-crawl after significant content changes.
If your Shopify catalogue isn’t appearing in the knowledge base after installation, follow these steps:
  1. Check permissions. During Shopify app installation you’re prompted to approve required permissions. If any were declined, the sync cannot complete. Review the app’s permission status in your Shopify admin.
  2. Trigger a manual re-sync. In your MerchantAI dashboard, navigate to Knowledge → Shopify and select Re-sync.
  3. Reinstall the app if the issue persists. Remove MerchantAI from your Shopify admin and reinstall from the App Store. This resets the OAuth token and resolves most persistent sync failures.
If your dashboard appears empty or a workspace isn’t visible after logging in:
  • Confirm you’re using the correct sign-in method. If you signed up via Shopify, you must log in using the same Shopify account — not a separate email/password combination.
  • Check for duplicate accounts. You may have created the workspace under a different email address.
  • Contact support. If you’re confident you’re using the right account and the workspace still isn’t visible, contact the support team with your sign-up email.

​
Widget & Deployment

If the MerchantAI widget doesn’t show up on your website after installation:
  1. Verify script placement. The snippet must be placed before the closing </body> tag on every page where you want the widget to appear.
  2. Check the browser console for errors. Open your browser’s developer tools and look for script errors related to widget.merchantai.io.
  3. Review your Content Security Policy (CSP). If your site uses a CSP header, add widget.merchantai.io to the script-src directive.
If you’re using a tag manager (e.g. Google Tag Manager), make sure the MerchantAI snippet fires on all relevant pages and is not blocked by trigger conditions.
If the widget loads but messages receive no reply:
  • Message limit reached. If you’ve hit your monthly message allocation, the agent stops responding until the next billing period. Check your usage in the dashboard. Upgrading your plan restores your allocation immediately.
  • Empty or unapproved knowledge base. The agent requires at least one approved source. Go to Knowledge and confirm at least one source has been crawled and approved.
The MerchantAI widget loads asynchronously and should not block page rendering. If you’re experiencing slowdowns:
  • Check for conflicts with other chat tools. If another chat widget is running on the same page, try disabling it temporarily to isolate the issue.
  • Review third-party script load order. Heavy analytics or personalisation scripts that load synchronously before </body> can delay all subsequent scripts.

​
Knowledge & Answers

If the agent is surfacing prices, product details, or policies that no longer reflect your store:
  • Trigger a manual re-crawl or re-sync from the Knowledge dashboard.
  • Check Shopify webhook delivery. Go to your Shopify admin and confirm webhooks are being delivered without errors. Failed webhooks mean automatic updates aren’t reaching MerchantAI.
If the agent can’t answer a question that’s clearly covered in your content:
  1. Source approval status. Navigate to Knowledge and confirm the page, file, or Q&A pair is marked as approved. Unapproved sources are excluded from the agent’s knowledge.
  2. Confidence threshold setting. If the threshold is set too high, the agent may decline to answer even with relevant content. Review and adjust in Configuration → Guardrails.
If the agent is engaging with a topic you intended to block, check Configuration → Guardrails → Topic controls:
  • Confirm the topic is in your blocklist. Re-add it and save if needed.
  • Check keyword spelling and variants. Keyword-based blocks are matched exactly. If the topic can be expressed multiple ways (e.g. “refund”, “refunds”, “money back”), add each variant explicitly.
For broad topic categories, use topic-level controls rather than individual keywords — they’re more reliable and easier to maintain.

​
Handover & Contacts

If your team isn’t getting email notifications when a conversation is escalated:
  1. Verify the configured address. Go to Configuration → Handover and confirm the email address is correct.
  2. Check spam and junk folders. Transactional emails from MerchantAI may be filtered by your provider.
  3. Check domain-level email filtering. Ask your IT team to whitelist transactional emails from MerchantAI’s sending domain if needed.
If no leads or conversations are appearing in your Contacts inbox:
  • Plan eligibility. Lead capture and the Contacts inbox are available on the Pro plan and above. Upgrade to Pro to enable this feature.
  • Lead capture configuration. Lead capture must be explicitly enabled. Go to Configuration and confirm that lead capture is toggled on.

​
Billing

Paid plan trials run for exactly 14 days from the moment you subscribe. Your card is charged automatically on day 15 if you haven’t cancelled. To check when your trial started, go to Settings → Billing in your dashboard.
If you signed up via Shopify, billing is managed through your Shopify admin. Check your Shopify billing page for the charge details.
Downgrades are applied at the end of your current billing cycle, not immediately. You retain all features of your existing plan until the cycle ends. This is by design — you keep access to what you paid for until the period expires.
If none of the steps above resolve your issue, contact the MerchantAI support team from the Help menu in your dashboard. Include a description of the problem, your workspace ID, and any relevant error messages or screenshots.