WinterSky Inventory Management System

Complete Roadmap: QBO → New Inventory System → Knowify (via Zapier) → QBO

⚠️ Pitfalls & Critical Considerations

🚨 CRITICAL DECISION: Identifying Inventory-able Purchases

This is one of the key operational challenges. QuickBooks doesn't know which purchases should be tracked in your yard inventory, so you need a reliable way to flag them.

You MUST establish a tagging system:

Options for Flagging Inventory-able Items

Option 1: QBO Classes

✅ Pros:
  • Built into QuickBooks
  • Easy to query via API
  • Users already trained on classes
❌ Cons:
  • Requires user discipline
  • Easy to forget tagging

Option 2: Product/Item Names

✅ Pros:
  • Automatic detection
  • No user training needed
  • Pattern matching (keywords like "I-beam", "steel", "lumber")
❌ Cons:
  • Requires maintenance of keyword list
  • May miss items or catch false positives

Option 3: Vendor-Based

✅ Pros:
  • Simple rule: certain vendors = always inventory
  • Works if you have dedicated material suppliers
❌ Cons:
  • Not granular enough if vendors sell mixed items
  • New vendors need configuration

Option 4: Custom QBO Field

✅ Pros:
  • Most explicit and accurate
  • Clear yes/no checkbox
  • Easy to query
❌ Cons:
  • Requires QBO Plus or Advanced subscription
  • User training required
  • Can be forgotten

💡 RECOMMENDED APPROACH: Hybrid System

Automated detection + Manual review queue

  1. Auto-flag candidates: System uses product names, vendors, or classes to suggest purchases
  2. Admin review queue: Flagged purchases appear in dashboard with "Import to Inventory?" option
  3. One-click import: Admin reviews and approves in bulk
  4. Learning system: Track which items get approved/rejected to improve auto-flagging over time

This gives you automation with a safety net!

Additional Critical Pitfalls

1. QBO API Rate Limits

  • Limit: QBO throttles based on concurrent connections and request volume (limits vary by endpoint)
  • Pitfall: Aggressive syncing or bulk operations can trigger throttling (HTTP 429 errors)
  • Solution: Schedule syncs every 4-6 hours, implement exponential backoff on throttle errors
  • Solution: Cache QBO data locally, only query for changes since last sync (use metadata queries)
  • Monitor: Log API responses and handle 429 errors gracefully with retry logic

2. QBO OAuth Token Expiration

  • Issue: Access tokens expire after ~1 hour; refresh tokens expire after 100 days
  • Pitfall: If you don't refresh tokens regularly, the refresh token expires and sync stops silently
  • Solution: Implement automatic access token refresh before each API call (or cache for ~50 minutes)
  • Solution: Use refresh tokens regularly to keep them from expiring (each use resets the 100-day window)
  • Solution: Alert admins if refresh fails, with a re-authentication flow in admin dashboard

3. Partial Shipments / Receiving

  • Scenario: Order 100 I-beams, only 60 arrive
  • Pitfall: Generate QR code for all 100, but only 60 are receivable
  • Solution: Support partial receiving - receiver enters actual quantity received
  • Solution: Allow multiple QR codes per purchase (one per delivery)
  • Solution: Track "expected" vs "received" quantities

4. QR Code Durability

  • Environment: Yard conditions (weather, dirt, wear)
  • Pitfall: Paper QR codes fade, tear, become unreadable
  • Solution: Use weatherproof labels (vinyl/polyester with UV coating)
  • Solution: Print duplicate QR codes (attach multiple to large items)
  • Solution: Build manual lookup feature in case QR is unreadable
  • Product rec: Brother QL-820NWB printer with DK-2205 continuous labels

5. Multiple Items in Same Purchase

  • Scenario: One PO contains 10 different line items
  • Pitfall: Which item does the QR code represent?
  • Solution: Generate separate QR codes for each line item
  • Solution: QR code format: PO_NUMBER-LINE_ITEM_NUMBER
  • UI consideration: Receiving screen shows all line items, generate QR for each

6. FIFO Complexity with Partial Pulls

  • Scenario: Pull 25 I-beams, but oldest batch only has 15 remaining
  • Pitfall: FIFO must span multiple purchases, costs get complex
  • Solution: Algorithm must handle multi-batch allocation automatically
  • Solution: Show cost breakdown on approval screen (15 @ $100, 10 @ $105)
  • Testing critical: Create extensive test scenarios for FIFO edge cases

7. Mobile Network in Yard

  • Reality: Yards may have spotty cell/wifi coverage
  • Pitfall: Workers can't submit pull requests from certain areas
  • Solution: Build Progressive Web App with offline capability
  • Solution: Queue requests locally, sync when connection returns
  • Solution: Visual indicator showing online/offline status

8. Job Name Consistency

  • Problem: Workers typing job names = "Main St", "Main Street", "123 Main St"
  • Pitfall: Same job appears as 3 different jobs in Knowify
  • Solution: Autocomplete dropdown from jobs table
  • Solution: Fetch active jobs from Knowify (via Zapier) to populate dropdown
  • Solution: Fuzzy matching to suggest similar job names

9. Zapier Task Limits

  • Free Plan: 100 tasks/month (probably not enough)
  • Starter Plan: 750 tasks/month = $19.99
  • Pitfall: Run out of tasks mid-month, job costing stops
  • Solution: Start with paid plan or batch multiple pulls into single Zap
  • Monitor: Track Zapier usage, alert at 80% of limit

10. Data Sync Conflicts

  • Scenario: Purchase edited in QBO after being imported to your system
  • Pitfall: Your system has old data, costs don't match
  • Solution: Periodic reconciliation job (weekly) to detect mismatches
  • Solution: Lock imported purchases in your system with warning message
  • Solution: Admin dashboard showing "out of sync" purchases

11. User Permission Complexity

  • Roles needed: Field Worker, Receiving Clerk, Admin, Super Admin
  • Pitfall: Wrong user has wrong permissions, can approve their own pulls
  • Solution: Implement role-based access control (RBAC) from day 1
  • Rule: Workers cannot approve their own requests
  • Rule: Only admins can access Zapier/QBO settings

12. Audit Trail Requirements

  • Question: "Who pulled 20 I-beams from the Site A job last month?"
  • Pitfall: No comprehensive logging, can't answer questions
  • Solution: Log EVERYTHING: who, what, when, why for all actions
  • Solution: Build searchable audit log in admin dashboard
  • Solution: Export capabilities for external audits

🎯 Priority Order for MVP

Don't try to solve everything at once. Build in this order:

  1. Core flow: Manual import → Receive → QR → Pull → Approve → FIFO (no automation yet)
  2. Automated sync: Scheduled QBO queries with admin review queue
  3. Zapier integration: Get job costing to Knowify working
  4. Polish: Offline mode, fuzzy matching, reconciliation, etc.

Get to production faster, iterate based on real user feedback!