> ## Documentation Index
> Fetch the complete documentation index at: https://storekit.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# POS Troubleshooting

> Diagnose and resolve common POS integration issues in storekit including missing orders, menu sync errors, mapping problems, and connection timeouts.

export const PosTroubleshooter = () => {
  const [step, setStep] = useState(0);
  const [answers, setAnswers] = useState({});
  const flow = [{
    question: "What type of issue are you experiencing?",
    options: [{
      label: "Can't connect to POS",
      value: 'connection',
      next: 1
    }, {
      label: "Menu sync not working",
      value: 'sync',
      next: 4
    }, {
      label: "Orders not appearing in POS",
      value: 'injection',
      next: 7
    }, {
      label: "Connection drops randomly",
      value: 'intermittent',
      solution: 'intermittent_connection'
    }]
  }, {
    question: 'Have you double-checked your credentials?',
    options: [{
      label: 'Yes, credentials are definitely correct',
      value: 'creds_ok',
      next: 2
    }, {
      label: 'No / Not sure',
      value: 'creds_unknown',
      solution: 'verify_credentials'
    }]
  }, {
    question: 'Is your POS system currently online?',
    options: [{
      label: 'Yes, I can use it normally',
      value: 'pos_online',
      next: 3
    }, {
      label: 'No / Having issues with POS itself',
      value: 'pos_offline',
      solution: 'pos_offline'
    }]
  }, {
    question: 'Does your POS provider require any special setup for API access?',
    options: [{
      label: 'Yes, I\'ve enabled API access',
      value: 'api_enabled',
      solution: 'firewall_check'
    }, {
      label: 'Not sure / Haven\'t checked',
      value: 'api_unknown',
      solution: 'enable_api_access'
    }]
  }, {
    question: 'What happens when you try to sync?',
    options: [{
      label: 'Nothing happens / Sync button doesn\'t work',
      value: 'no_sync',
      solution: 'check_connection_first'
    }, {
      label: 'Sync runs but products are missing',
      value: 'missing_products',
      next: 5
    }, {
      label: 'Sync completes but prices are wrong',
      value: 'wrong_prices',
      solution: 'tax_settings'
    }]
  }, {
    question: 'Are the missing products active in your POS?',
    options: [{
      label: 'Yes, they\'re active and visible',
      value: 'products_active',
      next: 6
    }, {
      label: 'No / Some are disabled',
      value: 'products_inactive',
      solution: 'activate_products'
    }, {
      label: 'Not sure how to check',
      value: 'check_unknown',
      solution: 'product_status'
    }]
  }, {
    question: 'Are the products assigned to a menu/category in your POS?',
    options: [{
      label: 'Yes, all assigned correctly',
      value: 'assigned',
      solution: 'menu_type_mismatch'
    }, {
      label: 'No / Some aren\'t assigned',
      value: 'not_assigned',
      solution: 'assign_products'
    }, {
      label: 'Not sure',
      value: 'assigned_unknown',
      solution: 'product_status'
    }]
  }, {
    question: 'Do orders appear in your storekit dashboard?',
    options: [{
      label: 'Yes, orders are in the dashboard',
      value: 'in_dashboard',
      next: 8
    }, {
      label: 'No, orders are missing everywhere',
      value: 'no_orders',
      solution: 'order_not_placed'
    }]
  }, {
    question: 'Do you see any error messages on the order in the dashboard?',
    options: [{
      label: 'Yes, there\'s an error shown',
      value: 'has_error',
      next: 9
    }, {
      label: 'No error, just not in POS',
      value: 'no_error',
      solution: 'check_pos_terminal'
    }]
  }, {
    question: 'What type of error do you see?',
    options: [{
      label: 'PLU/product code error',
      value: 'plu_error',
      solution: 'fix_plu_codes'
    }, {
      label: 'Connection/timeout error',
      value: 'connection_error',
      solution: 'injection_connection'
    }, {
      label: 'Validation error',
      value: 'validation_error',
      solution: 'validation_error'
    }, {
      label: 'Other / Not sure',
      value: 'other_error',
      solution: 'contact_support'
    }]
  }];
  const solutions = {
    verify_credentials: {
      title: 'Verify Your Credentials',
      icon: '🔑',
      steps: ['Go to your POS provider\'s admin panel', 'Locate your API credentials (API key, secret, site ID)', 'Copy them fresh - don\'t retype manually', 'Check for extra spaces at the start or end when pasting', 'Ensure credentials haven\'t expired or been regenerated', 'Try the connection again with fresh credentials'],
      severity: 'warning'
    },
    pos_offline: {
      title: 'POS System Offline',
      icon: '📴',
      steps: ['Check your POS terminal is powered on', 'Verify the POS has internet connectivity', 'Check your POS provider\'s status page for outages', 'Restart your POS terminal if needed', 'Try connecting once your POS is working normally'],
      note: 'storekit can\'t connect if your POS system itself is offline.',
      severity: 'error'
    },
    enable_api_access: {
      title: 'Enable API Access',
      icon: '🔓',
      steps: ['Log into your POS provider\'s admin portal', 'Look for "API Access", "Integrations", or "Third-party apps" settings', 'Enable API access for your account', 'Generate new API credentials if required', 'Some providers require you to contact them to enable API access'],
      note: 'Many POS systems require API access to be explicitly enabled before integrations work.',
      severity: 'warning'
    },
    firewall_check: {
      title: 'Check Network/Firewall',
      icon: '🔥',
      steps: ['Ensure your network allows outbound HTTPS connections', 'Check if a firewall is blocking API calls', 'Whitelist storekit\'s servers if required', 'Try from a different network (e.g., mobile hotspot) to test', 'Contact your IT team if on a corporate network'],
      severity: 'warning'
    },
    intermittent_connection: {
      title: 'Fix Intermittent Connection',
      icon: '📡',
      steps: ['Check your internet stability - run a speed test', 'Look for patterns - do failures happen at specific times?', 'Some POS systems restart overnight for maintenance', 'Check if you\'re hitting API rate limits (too many requests)', 'Consider a backup internet connection for reliability', 'Check your POS provider\'s status page for known issues'],
      severity: 'warning'
    },
    check_connection_first: {
      title: 'Check Connection Status',
      icon: '🔌',
      steps: ['Go to Store Settings > Integrations', 'Check if your POS shows as "Connected"', 'If disconnected, click to reconnect', 'Re-enter your credentials if prompted', 'Test the connection before attempting sync', 'Once connected, try the menu sync again'],
      severity: 'warning'
    },
    tax_settings: {
      title: 'Fix Tax/Price Mismatch',
      icon: '💰',
      steps: ['Check if your POS prices include or exclude VAT/tax', 'Go to storekit Settings and verify tax settings match', 'Ensure tax rates are the same in both systems', 'Check for currency or decimal place differences', 'Re-sync the menu after correcting settings'],
      note: 'Price mismatches are almost always caused by tax-inclusive vs tax-exclusive settings.',
      severity: 'info'
    },
    activate_products: {
      title: 'Activate Products in POS',
      icon: '✅',
      steps: ['Log into your POS system', 'Find the products that aren\'t syncing', 'Enable/activate them (look for "Active" or "Published" toggle)', 'Ensure they\'re visible for online ordering if that\'s an option', 'Save changes in your POS', 'Run menu sync again in storekit'],
      severity: 'info'
    },
    product_status: {
      title: 'Check Product Configuration',
      icon: '📋',
      steps: ['In your POS, products need to be: active/enabled, assigned to a category/menu, and visible for the correct channel', 'Check each missing product meets these criteria', 'Some POS systems have separate "online" vs "in-store" visibility', 'Verify the correct menu/price list is selected in storekit settings', 'Run menu sync after making changes'],
      severity: 'info'
    },
    assign_products: {
      title: 'Assign Products to Menu',
      icon: '📁',
      steps: ['In your POS, find the unassigned products', 'Add them to a category or menu group', 'Products outside of categories often won\'t sync', 'Save changes in your POS', 'Run menu sync again in storekit'],
      severity: 'info'
    },
    menu_type_mismatch: {
      title: 'Check Menu Type Settings',
      icon: '📑',
      steps: ['Some POS systems have multiple menu types (dine-in, takeaway, delivery)', 'Verify storekit is syncing from the correct menu type', 'Check your integration settings for menu selection', 'Ensure products are on the menu type being synced', 'Contact support if you\'re unsure which menu to use'],
      severity: 'info'
    },
    order_not_placed: {
      title: 'Order May Not Have Completed',
      icon: '❓',
      steps: ['Ask the customer if they received a confirmation email', 'Check your storekit dashboard Orders page', 'Search by time, customer name, or email', 'If not found, the order likely wasn\'t completed', 'Customer may have abandoned at payment', 'Check for any payment failures in your payment provider'],
      severity: 'info'
    },
    check_pos_terminal: {
      title: 'Check POS Terminal',
      icon: '🖥️',
      steps: ['Verify your POS terminal is powered on', 'Check the terminal has network connectivity', 'Some POS systems queue orders - check for a pending queue', 'Try placing a test order directly in the POS', 'Restart the POS terminal if it seems unresponsive', 'Check if the correct location/terminal is selected in storekit'],
      severity: 'warning'
    },
    fix_plu_codes: {
      title: 'Fix PLU/Product Codes',
      icon: '🏷️',
      steps: ['PLU errors mean storekit can\'t find the product in your POS', 'Go to Menu in your storekit dashboard', 'Find the product(s) mentioned in the error', 'Check the PLU/product code matches exactly what\'s in your POS', 'Update any incorrect codes', 'Don\'t forget to check modifier PLUs too'],
      note: 'Even a small typo in a PLU code will cause the item to fail.',
      severity: 'warning'
    },
    injection_connection: {
      title: 'Order Injection Connection Issue',
      icon: '🔗',
      steps: ['Check your POS integration is still connected', 'Verify your POS terminal is online and accessible', 'Connection errors often mean the POS was temporarily unavailable', 'Try re-sending the order from the order details page', 'If persistent, check your network stability'],
      severity: 'warning'
    },
    validation_error: {
      title: 'Fix Validation Error',
      icon: '⚠️',
      steps: ['Validation errors mean the POS rejected the order data', 'Common causes: missing required fields, invalid modifiers, price mismatches', 'Check if the products in the order still exist in your POS', 'Verify modifier configurations match between systems', 'Re-sync your menu to update product data', 'Contact support with the order ID for specific help'],
      severity: 'warning'
    },
    contact_support: {
      title: 'Contact Support',
      icon: '💬',
      steps: ['Note down the order ID from your dashboard', 'Take a screenshot of the error message', 'Check which products/items are affected', 'Contact storekit support with these details', 'Also check with your POS provider if it\'s a POS-side error'],
      severity: 'info'
    }
  };
  const reset = () => {
    setStep(0);
    setAnswers({});
  };
  const handleAnswer = option => {
    const newAnswers = {
      ...answers,
      [step]: option.value
    };
    setAnswers(newAnswers);
    if (option.solution) {
      setStep(-1);
      setAnswers({
        ...newAnswers,
        solution: option.solution
      });
    } else if (option.next !== undefined) {
      setStep(option.next);
    }
  };
  const currentSolution = answers.solution ? solutions[answers.solution] : null;
  return <div className="not-prose">
      {}
      {step >= 0 && !currentSolution && <div className="space-y-4">
          {step > 0 && <button onClick={reset} className="text-sm text-blue-600 dark:text-blue-400 hover:underline flex items-center gap-1">
              ← Start over
            </button>}
          
          <div className="p-4 rounded-xl border border-zinc-200 dark:border-zinc-700 bg-zinc-50 dark:bg-zinc-800/50">
            <h3 className="text-lg font-semibold text-zinc-900 dark:text-white mb-4">
              {flow[step].question}
            </h3>
            <div className="space-y-2">
              {flow[step].options.map((option, idx) => <button key={idx} onClick={() => handleAnswer(option)} className="w-full p-3 rounded-lg border border-zinc-200 dark:border-zinc-600 hover:border-blue-500 dark:hover:border-blue-500 hover:bg-blue-50 dark:hover:bg-blue-900/20 transition-all text-left text-zinc-900 dark:text-white">
                  {option.label}
                </button>)}
            </div>
          </div>
        </div>}

      {}
      {currentSolution && <div className="space-y-4">
          <button onClick={reset} className="text-sm text-blue-600 dark:text-blue-400 hover:underline flex items-center gap-1">
            ← Start over
          </button>

          <div className={`p-4 rounded-xl border-2 ${currentSolution.severity === 'error' ? 'border-red-300 dark:border-red-800 bg-red-50 dark:bg-red-900/20' : currentSolution.severity === 'warning' ? 'border-yellow-300 dark:border-yellow-800 bg-yellow-50 dark:bg-yellow-900/20' : 'border-blue-300 dark:border-blue-800 bg-blue-50 dark:bg-blue-900/20'}`}>
            <div className="flex items-start gap-3">
              <span className="text-3xl">{currentSolution.icon}</span>
              <div className="flex-1">
                <h3 className="text-lg font-semibold text-zinc-900 dark:text-white">
                  {currentSolution.title}
                </h3>
                
                <ol className="mt-4 space-y-2">
                  {currentSolution.steps.map((s, idx) => <li key={idx} className="flex gap-3">
                      <span className="flex-shrink-0 w-6 h-6 rounded-full bg-zinc-200 dark:bg-zinc-700 flex items-center justify-center text-sm font-medium text-zinc-700 dark:text-zinc-300">
                        {idx + 1}
                      </span>
                      <span className="text-zinc-700 dark:text-zinc-300">{s}</span>
                    </li>)}
                </ol>

                {currentSolution.note && <div className="mt-4 p-3 rounded-lg bg-white/50 dark:bg-black/20 text-sm text-zinc-600 dark:text-zinc-400">
                    💡 {currentSolution.note}
                  </div>}
              </div>
            </div>
          </div>

          <div className="p-4 rounded-xl border border-zinc-200 dark:border-zinc-700 bg-white dark:bg-zinc-800">
            <h4 className="font-medium text-zinc-900 dark:text-white mb-2">Still having issues?</h4>
            <p className="text-sm text-zinc-600 dark:text-zinc-400">
              Contact support with your store name, the order ID (if applicable), and screenshots of any error messages.
            </p>
          </div>
        </div>}
    </div>;
};

## Diagnostic Tool

Answer a few questions to diagnose your issue:

<PosTroubleshooter />

***

This guide covers common issues with POS integrations and how to resolve them.

## Connection Issues

### Integration Won't Connect

**Symptoms:**

* "Connection failed" error when setting up
* Unable to save integration settings
* Test connection fails

**Solutions:**

1. **Verify credentials**
   * Double-check API keys, secrets, and site IDs
   * Ensure no extra spaces in copied credentials
   * Confirm credentials haven't expired

2. **Check POS status**
   * Verify your POS system is online
   * Ensure cloud connectivity is enabled
   * Check for POS system outages

3. **Network issues**
   * Confirm your venue has internet connectivity
   * Check firewall settings aren't blocking API calls
   * Try from a different network if possible

4. **Contact your POS provider**
   * Verify API access is enabled on your account
   * Request new credentials if existing ones don't work

### Connection Drops Intermittently

**Symptoms:**

* Integration works sometimes but not always
* Orders occasionally fail to inject
* Sync completes sometimes but fails others

**Solutions:**

1. **Check internet stability**
   * Unstable connections cause intermittent failures
   * Consider a backup internet connection

2. **Review POS uptime**
   * Some POS systems restart overnight
   * Check if failures correlate with maintenance windows

3. **Monitor API limits**
   * Some POS systems have rate limits
   * Reduce sync frequency if hitting limits

## Menu Sync Issues

### Menu Not Syncing

**Symptoms:**

* Sync button does nothing
* Products don't appear after sync
* Sync runs but menu is empty

**Solutions:**

1. **Check integration is connected**
   * Go to Store Settings > Integrations
   * Verify the POS shows as connected

2. **Verify menu in POS**
   * Ensure products are active/published
   * Check products are assigned to categories
   * Confirm the menu type is correct

3. **Try manual sync**
   * Use the sync button in the Menu section
   * Wait for sync to complete fully
   * Check for error messages

### Products Missing After Sync

**Symptoms:**

* Some products sync but others don't
* Modifiers are missing
* Categories are incomplete

**Solutions:**

1. **Check product status in POS**
   * Products must be active/enabled
   * Products need to be assigned to a menu
   * Check product visibility settings

2. **Review menu structure**
   * Products outside categories may not sync
   * Some integrations only sync specific menu types
   * Verify the correct menu is selected

3. **Check for sync errors**
   * Review any error messages after sync
   * Individual products may fail while others succeed

### Prices Are Wrong

**Symptoms:**

* Synced prices don't match POS
* Prices are doubled or halved
* Tax appears incorrectly

**Solutions:**

1. **Tax settings mismatch**
   * Check if POS prices include tax
   * Verify storekit tax settings match
   * Ensure tax rates are configured correctly

2. **Currency issues**
   * Confirm currency settings match
   * Check for decimal place differences

3. **Re-sync after changes**
   * Prices won't update until you sync
   * Trigger a manual sync after price changes in POS

## Order Injection Issues

### Orders Not Appearing in POS

**Symptoms:**

* Customer receives confirmation
* Order shows in storekit dashboard
* Order never appears in POS

**Solutions:**

1. **Check integration status**
   * Verify integration is enabled
   * Check for disconnection warnings

2. **Review order in dashboard**
   * Look at order details for errors
   * Check POS injection status field

3. **Verify POS is online**
   * Check terminal is powered on
   * Confirm network connectivity
   * Try placing an order directly in POS

4. **Check PLU codes (manual linking)**
   * Ensure all items have valid PLUs
   * Verify PLUs exist in POS system

5. **Check for email notifications**
   * If order injection fails, you'll receive an email notification
   * The email includes the specific error reason and order details
   * Check your venue email address is configured correctly

### Orders Appearing Late

**Symptoms:**

* Orders arrive in POS minutes/hours late
* Pre-orders arrive at wrong times
* ASAP orders are delayed

**Solutions:**

1. **Check injection settings**
   * Review pre-order injection timing
   * Verify ASAP orders are set to immediate

2. **Network latency**
   * Slow connections delay injection
   * Check overall network performance

3. **POS queue issues**
   * Some POS systems queue incoming orders
   * Check POS settings for order processing

### Items Missing from Orders

**Symptoms:**

* Order appears but items are missing
* Modifiers don't show
* Partial order in POS

**Solutions:**

1. **PLU mapping issues**
   * Missing PLUs cause items to fail
   * Check all products and modifiers have PLUs

2. **Product mismatch**
   * Item may have been deleted from POS
   * Re-sync menu to update mappings

3. **Modifier configuration**
   * Verify modifiers are linked correctly
   * Check modifier group settings

### Wrong Items on Orders

**Symptoms:**

* POS shows different items than ordered
* Quantities are wrong
* Modifiers applied to wrong items

**Solutions:**

1. **PLU codes incorrect**
   * Wrong PLU maps to wrong product
   * Audit PLU mappings against POS

2. **Duplicate PLUs**
   * Same PLU used for multiple products
   * Ensure PLUs are unique

3. **Recent menu changes**
   * Products may have been remapped
   * Re-sync and verify mappings

## Discount & Loyalty Issues

### Discounts Not Applying

**Symptoms:**

* Loyalty discounts don't appear
* Promotional pricing not working
* Customer balance not reflected

**Solutions:**

1. **Verify discount is active**
   * Check promotion is enabled in POS
   * Confirm date range is current
   * Verify terms are met

2. **Customer qualification**
   * Check customer is enrolled in loyalty
   * Verify customer meets discount criteria
   * Confirm online orders are eligible

3. **Integration settings**
   * Some discounts need explicit enablement
   * Check discount sync settings

### Wrong Discount Amounts

**Symptoms:**

* Discount applied but amount is wrong
* Percentage calculated incorrectly
* Discount appears twice

**Solutions:**

1. **Check discount rules**
   * Verify discount calculation method
   * Check for stacking rules

2. **Tax interaction**
   * Confirm discount applies before/after tax
   * Check both systems use same method

## Email Notifications for Failed Syncs

storekit automatically sends email notifications when orders or payments fail to sync to your POS, ensuring you never miss critical information.

### Failed Order Notifications

When an order fails to sync to your POS, you'll receive an email that includes:

* **Order details** - Customer name, order ID, and payment method
* **Error reason** - Specific technical details about why the sync failed
* **Order items** - A summary of what was ordered (with images when available)
* **Quick actions** - Direct link to view the order in your dashboard

<Info>
  Failed order emails are sent even if the customer has already paid online, ensuring you never miss an order that needs manual attention.
</Info>

#### What to Do When You Receive a Failed Order Email

1. **Check the error reason** - The email includes specific details about why the sync failed
2. **View the order in dashboard** - Click the link in the email to see full order details
3. **Manually enter the order** - If needed, enter the order directly into your POS
4. **Contact support** - If the issue persists, our support team has already been notified and can help resolve it

### Bill Payment Failure Notifications

When a Pay at Table payment succeeds but fails to sync to your POS, you'll receive an email notification. This is critical because the customer has already paid, but your POS may not reflect it.

The notification includes:

* **Bill details** - Bill ID and venue name
* **Payment information** - Payment ID and transaction details
* **Error reason** - Specific technical details about why the sync failed
* **Reference IDs** - Both storekit and POS bill IDs for reconciliation
* **Quick actions** - Direct link to view the bill in your dashboard

<Warning>
  Bill payment failure emails indicate the customer has already paid successfully. You may need to manually reconcile this payment in your POS to avoid discrepancies.
</Warning>

#### What to Do When You Receive a Bill Payment Failure Email

1. **Check the error details** - The email includes specific information about why the sync failed
2. **View the bill in dashboard** - Click the link to see full payment details
3. **Manually reconcile in POS** - Mark the bill as paid in your POS if needed
4. **Contact support** - Our team is automatically notified and can help with recurring issues

### Ensuring You Receive Notifications

Make sure your venue email address is configured correctly:

1. Go to **Store Settings** in your dashboard
2. Navigate to **Store Details**
3. Verify your email address is correct
4. Add multiple email addresses if needed (the first address will receive notifications)

## Getting Help

If you've tried these solutions and still have issues:

1. **Gather information**
   * Note the specific error messages
   * Record the order ID(s) affected
   * Take screenshots if possible
   * Check for failed order email notifications

2. **Check POS provider status**
   * Look for system-wide issues
   * Contact POS support for their end

3. **Contact storekit support**
   * Provide order IDs and error details
   * Share integration settings (not credentials)
   * Forward any failed order email notifications

[Contact support](/getting-started/contact-support) for further assistance.