Appifire Technical Troubleshooting Playbook

You will triage widget, sync, order-lookup, and usage issues in a fixed order. That helps support tickets resolve faster.

Most incidents clear when the team follows one path. Capture the same facts every time.

Prerequisites

• Access to the merchant’s Shopify admin and Appifire app
• Ability to open the live storefront (and a private browser window)
• Billing page access for plan and usage checks
• For order issues: a sample order number the merchant agrees you may use

Fast triage (2 minutes)

Before deep debugging, capture:

1. Store domain
2. Exact issue (“widget missing”, “wrong answer”, “order lookup failed”, “replies blocked”)
3. Time observed (UTC)
4. Screenshot or short screen recording

Then run the matching play below. Do not jump between plays mid-ticket.

Steps by symptom

1) Widget not visible on storefront

Start with the fastest checks:

• Confirm Enable chat widget on storefront (or equivalent) is on in Settings.
• Confirm you are testing the active theme, not an old preview.
• Hard-refresh the storefront. Test in a private browser window.

If the widget is off in Settings, turn it on. No theme code change is required for that case.

If it is still missing:

1. Open another theme preview with the Appifire extension.
2. If it shows there, the live theme is blocking or not hosting the extension.
3. If it is missing everywhere, re-check install and theme app extension placement.

Edge case: Widget shows on desktop but not mobile. Re-check bubble position and theme mobile templates before escalating.

2) Product answers are stale or incomplete

Check the product path:

• Confirm the latest product sync finished.
• Confirm important fields exist in Shopify (description, variants, tags, status).
• Confirm a product edit in Shopify eventually updates chat answers.
• Ask the same question on a known good SKU and a bad SKU to compare.

Poor source product data causes poor answers even when chat is working.

Next action if still wrong: Fix catalog fields. Wait for re-ingest. Then retest. See improve product and order answers.

3) Order-status replies fail or are incorrect

For order troubleshooting:

• Verify order-read permissions exist.
• Test with clear references (#1001, order: 1001).
• Check whether chat is waiting for an order number in a follow-up turn.
• Confirm the order exists in Shopify admin for that shop.
• Confirm Shopify API responses succeed (no permission or 404 style failures).

If lookup fails, use clear fallback messaging. Send the shopper to support. Do not return a guessed status.

Edge case: Merchant canceled or unpaid orders. Confirm what Shopify shows. Then match chat to that truth.

4) Usage limit or credit issues

When merchants report blocked replies:

• Free plan: compare replies used this month to the monthly cap (500 AI replies/month on Free).
• Paid / wallet path: check remaining credit balance on Billing.
• After cancel: leftover wallet credit can still be used until it hits zero; top-ups need an active paid subscription.

Use the Billing page as the first source for merchant-facing status. For plan language, see billing and credits and the pricing guide.

5) Monthly reset confusion

If a merchant says Free usage did not reset:

• Confirm current UTC date and time vs the reset schedule (UTC day 1).
• Confirm the shop is on Free for free-counter reset behavior.
• Confirm they are looking at the current month’s counter, not a screenshot from last month.

The reset job is guarded. Calls on non-day-1 dates safely skip writes.

Escalate with complete ticket context

For every technical ticket, include:

1. Store domain
2. Symptom and exact error text
3. Time window (UTC)
4. Plan state (free or paid)
5. Last known working behavior

Optional but useful:

6. A sample order number used for testing
7. Browser and device
8. Whether the issue reproduces in private / incognito mode

Complete context cuts back-and-forth.

What success looks like

• Matching play run once in order
• Root cause named (settings, theme, catalog, permissions, billing, or true defect)
• Merchant given one clear next action
• Escalations include the full context list above

When this playbook is enough vs when you need another approach

Situation	Prefer
Widget hidden, sync stale, order lookup failing, usage blocked	This playbook
Answers are fine but tickets are still mostly WISMO or product FAQ volume	Ops fixes + ticket reduction guide
You need agent queues, SLAs, and omnichannel tickets	A helpdesk, not only storefront AI chat

Limits and non-goals

• This playbook does not replace Shopify theme debugging for custom Liquid conflicts
• It does not fix missing product specs in the catalog
• It does not grant order access without Shopify permissions
• Live Pro prices, included credits, and pack sizes: confirm on pricing and in-app Billing (Pro is $20/month; Free includes 500 AI replies/month)

Related guides

• Getting Started
• Installation checklist
• Improve product and order answers
• Billing and credits

Next action

Capture the four triage fields. Run the matching play once. Escalate only with the full context list.

Last verified: 2026-08-08 · Product reviewer: Appifire