Troubleshooting

Solutions to common issues you might encounter while using FirearmCart. Find your issue below and follow the steps to resolve it.

Store & Access Issues

Can't Log In

Symptoms: Unable to access your FirearmCart admin

Solutions:

  1. Verify credentials

    • Check email address is correct
    • Check caps lock isn't on
    • Try typing password in a text editor first

  2. Reset password

    • Click "Forgot password" on login page
    • Check email (including spam folder)
    • Follow reset link

  3. Two-factor authentication issues

    • Verify device time is synced
    • Use backup codes if available
    • Contact support if locked out

  4. Account locked

    • Wait 15 minutes after multiple failed attempts
    • Contact support if still locked

Store Not Loading

Symptoms: Your storefront shows error or blank page

Solutions:

Issue Solution
Blank page Check theme is published
Error message Note error, check logs
Slow loading Check for large images
SSL error Verify domain settings

Steps to diagnose:

  1. Try accessing in incognito/private mode
  2. Try a different browser
  3. Check if admin panel loads
  4. Review recent changes made
  5. Contact support with details

Admin Panel Slow

Symptoms: FirearmCart admin is loading slowly

Solutions:

  1. Browser issues

    • Clear browser cache
    • Disable browser extensions
    • Try different browser

  2. Network issues

    • Check internet connection
    • Try different network
    • Verify not using VPN that slows connection

  3. System issues

    • Check system status page
    • Report if issue persists

Product Issues

Products Not Appearing on Store

Symptoms: Products visible in admin but not on storefront

Solutions:

Check Solution
Status Ensure product is set to "Active"
Availability Check "Available for sale" is enabled
Inventory Verify stock quantity > 0 (if tracking)
Collections Ensure product is in visible collection
Pricing Confirm price is set

Steps:

  1. Open product in admin
  2. Check "Status" section → set to Active
  3. Check "Availability" → enable for online store
  4. Check inventory settings
  5. Save and refresh storefront

Images Not Uploading

Symptoms: Product images fail to upload

Solutions:

Issue Solution
File too large Resize to under 20MB
Wrong format Use JPEG, PNG, GIF, or WebP
Slow connection Wait for upload to complete
Browser issue Try different browser

Best practices:

  • Optimize images before upload
  • Use JPEG for photos (smaller size)
  • Use PNG for graphics with transparency
  • Recommended: 2048x2048px maximum

Inventory Not Syncing

Symptoms: Inventory levels not updating from distributor

Solutions:

  1. Check integration status

    • Navigate to Settings > Integrations
    • Verify connection is active (green status)
    • Check last sync timestamp

  2. Re-sync manually

    • Click "Sync now" on integration
    • Wait for sync to complete
    • Check for error messages

  3. Verify credentials

    • API credentials may have expired
    • Re-enter credentials
    • Test connection

  4. Check distributor status

    • Distributor API may be down
    • Check distributor's status page
    • Try again later

Product Variants Not Working

Symptoms: Variants not displaying or pricing incorrectly

Solutions:

  1. Check variant configuration

    • Each variant needs price set
    • Each variant needs inventory
    • Options must be properly defined

  2. Variant limits

    • Maximum 100 variants per product
    • Maximum 3 option types
    • Simplify if exceeding limits

  3. Display issues

    • Check theme supports variants
    • Clear cache
    • Test in incognito mode

Order Issues

Payment Not Processing

Symptoms: Customers unable to complete checkout

Solutions:

Error Cause Solution
Card declined Customer's bank issue Customer contacts bank
Gateway error Processor connection issue Check API credentials
Timeout Slow connection Customer retry
Not configured Missing payment setup Complete payment setup

Steps to diagnose:

  1. Check Settings > Payments for status
  2. Verify payment processor connection
  3. Review recent transactions for patterns
  4. Check processor dashboard for errors
  5. Test with a small transaction

Order Stuck in Processing

Symptoms: Order not moving to next status

Solutions:

  1. Payment pending

    • Check if payment completed
    • View transaction in processor dashboard
    • Mark paid manually if confirmed

  2. FFL selection needed

    • Firearm order awaiting FFL
    • Contact customer for FFL selection
    • Customer selects FFL in their account

  3. Manual review required

    • Check order flags
    • Review for fraud indicators
    • Approve or cancel as appropriate

Can't Fulfill Order

Symptoms: Fulfill button not working or error when fulfilling

Solutions:

Issue Solution
No items to fulfill Already fulfilled
Missing shipping info Edit order, add address
Carrier error Check shipping integration
Out of stock Restock or cancel items

Customer Didn't Receive Order Confirmation

Symptoms: Customer says they didn't get email

Solutions:

  1. Verify email address

    • Check for typos in order
    • Confirm email is correct

  2. Check spam folder

    • Ask customer to check spam/junk
    • Add your domain to safe senders

  3. Resend notification

    • Open order
    • Click "Resend notification"
    • Confirm email sent

  4. Email deliverability

    • Check email settings
    • Verify sender domain
    • Review email logs

Payment Issues

Refund Failed

Symptoms: Error when processing refund

Solutions:

Error Cause Solution
Exceeds original Refunding more than paid Check amount
Already refunded Duplicate refund attempt Review refund history
Processor error Gateway issue Retry or check processor
Card expired Original card no longer valid Issue store credit

Steps:

  1. Verify refund amount is correct
  2. Check previous refunds on order
  3. Confirm with payment processor
  4. Try again or use alternative method

Payment Processor Disconnected

Symptoms: Payments failing, processor shows disconnected

Solutions:

  1. Re-authenticate

    • Navigate to Settings > Payments
    • Click on processor
    • Re-enter credentials
    • Test connection

  2. Check credentials

    • Verify API key hasn't expired
    • Confirm credentials match processor dashboard
    • Generate new keys if needed

  3. Processor account issue

    • Check processor dashboard for alerts
    • Verify account is in good standing
    • Contact processor support

Transaction Fees Seem Wrong

Symptoms: Fees higher than expected

Solutions:

  1. Review rate schedule

    • Check contract with processor
    • Verify rate tier
    • International cards often higher

  2. Check transaction types

    • Card-present vs card-not-present
    • Debit vs credit
    • Rewards cards

  3. Contact processor

    • Request fee breakdown
    • Ask about rate optimization
    • Review recent statements

Shipping Issues

Shipping Rates Not Showing

Symptoms: Checkout shows no shipping options

Solutions:

Check Solution
Shipping zones Ensure customer's location is covered
Rates configured Add rates to zones
Product weight Ensure products have weights
Shipping profiles Check profile assignments

Steps:

  1. Navigate to Settings > Shipping
  2. Review shipping zones
  3. Confirm customer's location is in a zone
  4. Check rates exist for that zone
  5. Verify products have shipping weights

Wrong Shipping Rates

Symptoms: Rates too high or too low

Solutions:

  1. Check product weights

    • Open affected products
    • Verify weight is accurate
    • Update if incorrect

  2. Check product dimensions

    • Dimensional weight may apply
    • Update package dimensions
    • Use actual dimensions

  3. Review rate configuration

    • Check rate calculation method
    • Verify carrier rates are current
    • Test with known dimensions

ShipStation Not Syncing Orders

Symptoms: Orders not appearing in ShipStation

Solutions:

  1. Check connection status

    • Navigate to Settings > Integrations
    • Find ShipStation
    • Verify connected (green status)

  2. Check sync settings

    • Verify order types selected
    • Check status filters
    • Confirm store is selected

  3. Re-authorize

    • Disconnect ShipStation
    • Reconnect with fresh authorization
    • Test sync

  4. Check ShipStation

    • Verify store appears in ShipStation
    • Check ShipStation logs
    • Contact ShipStation support

Theme Issues

Theme Changes Not Appearing

Symptoms: Changes made but not visible on storefront

Solutions:

Issue Solution
Not published Publish theme changes
Cache Clear browser cache
Developer mode Check if changes expired (1 hour)
Wrong theme Verify editing live theme

Steps:

  1. Confirm you're editing the live theme
  2. Click "Save" after making changes
  3. Clear browser cache (Ctrl+Shift+Delete)
  4. View in incognito mode
  5. Check if developer mode expired

Visual Editor Not Loading

Symptoms: Editor shows blank or error

Solutions:

  1. Browser issues

    • Clear cache and cookies
    • Disable browser extensions
    • Try different browser

  2. Theme issues

    • Check theme for Liquid errors
    • Revert recent code changes
    • Reset to default theme temporarily

  3. Connection issues

    • Check internet connection
    • Try different network
    • Retry in a few minutes

Developer Mode Expired

Symptoms: Code changes reverted, "Developer mode expired" message

Solutions:

Developer mode changes expire after 1 hour if not published.

  1. Recovery options

    • Changes may be in browser history
    • Check for local backups
    • Re-make changes if needed

  2. Next time

    • Publish changes before 1 hour
    • Or save code locally as backup
    • Use version control for major changes

  3. Extend session

    • Make a small change to reset timer
    • Publish intermediate changes
    • Save frequently

Integration Issues

Distributor Integration Not Working

Symptoms: Products not syncing from Lipseys/RSR

Solutions:

  1. Check credentials

    • Verify API credentials are current
    • Some credentials expire periodically
    • Generate new credentials if needed

  2. Check permissions

    • Verify API access is enabled on distributor side
    • Confirm account has necessary permissions
    • Contact distributor for access issues

  3. Check sync settings

    • Review what's configured to sync
    • Try manual sync
    • Check error logs

  4. Distributor status

    • Check if distributor API is operational
    • Review any maintenance notices
    • Try again during business hours

Duplicate Products After Sync

Symptoms: Same products appear multiple times

Solutions:

  1. SKU matching

    • Ensure SKUs are unique
    • Check if products existed before sync
    • Use SKU matching instead of title

  2. Clean up duplicates

    • Identify duplicate products
    • Delete extras (keep one)
    • Re-sync with correct settings

  3. Prevent future duplicates

    • Configure proper matching fields
    • Use distributor SKUs
    • Don't mix manual and synced products

Performance Issues

Store Loading Slowly

Symptoms: Pages take long time to load

Solutions:

Issue Solution
Large images Compress and resize images
Too many products Paginate or filter collections
Complex theme Simplify customizations
Many apps/scripts Remove unused integrations

Optimization steps:

  1. Run speed test (Google PageSpeed)
  2. Identify largest resources
  3. Compress images under 500KB
  4. Limit products per page to 24
  5. Remove unused code

Admin Panel Timing Out

Symptoms: Admin operations fail or take too long

Solutions:

  1. Large operations

    • Break bulk operations into smaller batches
    • Import fewer products at once
    • Export in date ranges

  2. Browser issues

    • Clear cache
    • Use fewer browser tabs
    • Close other applications

  3. Network issues

    • Check connection stability
    • Try wired instead of WiFi
    • Avoid VPN if possible

Error Messages

Common Error Codes

Error Meaning Solution
404 Page not found Check URL, verify page exists
500 Server error Refresh, contact support if persists
503 Service unavailable Wait and retry
Gateway timeout Request took too long Retry, simplify request
Rate limited Too many requests Wait 1 minute, retry

"Something Went Wrong"

Symptoms: Generic error message

Solutions:

  1. Try again

    • Wait a few seconds
    • Retry the operation
    • Often temporary

  2. Clear cache

    • Clear browser cache
    • Try incognito mode
    • Try different browser

  3. Note details

    • When did it occur?
    • What were you doing?
    • Is it reproducible?

  4. Contact support

    • Provide error details
    • Include screenshots
    • Describe steps to reproduce

"Session Expired"

Symptoms: Logged out unexpectedly

Solutions:

  1. Log back in

    • Normal after inactivity
    • Re-enter credentials

  2. Browser settings

    • Ensure cookies are enabled
    • Don't use "never remember" settings
    • Disable aggressive privacy extensions

  3. Frequent expiration

    • Check for conflicting sessions
    • Verify 2FA time sync
    • Contact support if persists

Getting More Help

Before Contacting Support

Gather this information:

  • Account email
  • Store URL
  • Error messages (exact text or screenshot)
  • Steps to reproduce
  • When it started
  • What you've already tried

Useful Information to Include

Type Details
Browser Chrome, Firefox, Safari, Edge + version
Device Desktop, laptop, tablet, phone
Operating system Windows, Mac, iOS, Android
Screenshots Error messages, unexpected behavior
Timeline When did issue start

Contact Options

See Contact Us for all support channels and response times.