POS Sync Behavior

Understanding how Point of Sale (POS) synchronization works with menu category management is crucial for maintaining your customizations while keeping your menu data up-to-date.

Overview

The POS Sync system:

• Preserves User Decisions: Your manual category assignments are protected
• Updates POS Data: Product details, prices, and availability stay current
• Tracks Modifications: Every user change is flagged and respected
• Provides Audit Trail: Complete history of sync decisions

How Sync Works

Normal POS Sync Flow

Data Flow Example

Initial POS Sync:

{
  "product": "Coffee",
  "posCategory": "Hot Drinks",
  "modification": {
    "field": "PRODUCT_CATEGORY",
    "valueCategory": "Hot Drinks", // Following POS
    "originalCategory": "Hot Drinks", // POS default
    "modified": false // Not changed by user
  }
}

User Moves Product:

{
  "product": "Coffee",
  "modification": {
    "field": "PRODUCT_CATEGORY",
    "valueCategory": "Beverages", // User's choice
    "originalCategory": "Hot Drinks", // Still tracking POS
    "modified": true, // USER CHANGED THIS
    "modifiedAt": 1640995200000
  }
}

Subsequent POS Sync:

{
  "posUpdate": {
    "product": "Coffee",
    "posCategory": "Hot Drinks" // POS unchanged
  },
  "oomDecision": {
    "valueCategory": "Beverages", // KEEP user's choice
    "originalCategory": "Hot Drinks", // Update POS tracking
    "modified": true // Still true - protected
  }
}

Modification Tracking System

The Modified Flag

The core protection mechanism:

interface ModifiedSettingItem {
  field: 'PRODUCT_CATEGORY';
  modified: boolean; // Key protection flag
  valueCategory: string; // Current assignment (user's or POS)
  originalCategory: string; // What POS says
  modifiedAt: number; // When user changed it
}

When modified: false:

• System follows POS category assignment
• Updates if POS changes the category
• No user customization to preserve

When modified: true:

• System respects user's category choice
• Ignores POS category updates for this product
• Tracks POS state in OriginalCategory for reference

What Gets Modified Flag

Sync Protection Rules

Protected Elements

✅ Always Protected:

• User category assignments (when modified: true)
• OOM-created categories (createdFromOOM: true)
• Category display names
• Category display order
• Category descriptions

✅ Conditionally Protected:

• Product category assignments (if user modified)
• Product customizations (price, availability, etc.)

❌ Not Protected (always synced):

• POS category names (for POS categories)
• Product base data (name, description from POS)
• Product pricing (for POS-controlled pricing)
• Product availability (if POS-controlled)

Conflict Resolution

When POS and user assignments differ:

Scenario 1: User Assignment Wins

POS says: Coffee → "Hot Drinks"
User set: Coffee → "Beverages"
Result:   Coffee stays in "Beverages"
Reason:   modified: true

Scenario 2: POS Category No Longer Exists

POS sync: "Hot Drinks" category removed
User had: Products in "Hot Drinks"
Result:   Products become unassigned
Action:   Manual reassignment needed

Scenario 3: Product Removed from POS

POS sync: Product "Seasonal Latte" deleted
OOM had:  Product in "Seasonal Specials"
Result:   Product removed from OOM
Action:   Cannot be restored without POS

Sync Scenarios

Scenario A: New Product from POS

Setup: POS adds new product "Matcha Latte" in category "Tea"

Sync Flow:

1. POS sends product with category "Tea"
2. OOM creates product association
3. Sets ValueCategory = "Tea"
4. Sets OriginalCategory = "Tea"
5. Sets modified = false (following POS)

Result: Product appears in "Tea" category, can be moved later

Scenario B: User Moves Product

Setup: User moves "Matcha Latte" from "Tea" to "Specialty Drinks"

User Action:

1. User selects product in UI
2. Clicks "Move to Category" → "Specialty Drinks"
3. System updates modification:
   • ValueCategory = "Specialty Drinks"
   • OriginalCategory = "Tea" (unchanged)
   • modified = true
   • modifiedAt = timestamp

Result: Product in "Specialty Drinks", protected from POS sync

Scenario C: POS Changes Category

Setup: POS changes "Matcha Latte" category from "Tea" to "Coffee"

Sync Flow (User Never Moved It):

Before: { valueCategory: "Tea", originalCategory: "Tea", modified: false }
After:  { valueCategory: "Coffee", originalCategory: "Coffee", modified: false }

Result: Product follows POS to "Coffee"

Sync Flow (User Had Moved It):

Before: { valueCategory: "Specialty Drinks", originalCategory: "Tea", modified: true }
After:  { valueCategory: "Specialty Drinks", originalCategory: "Coffee", modified: true }

Result: Product stays in "Specialty Drinks" (user choice preserved)

Scenario D: Category Reorganization

Setup: User reorganizes entire menu, moving many products

System Behavior:

1. Each move sets modified: true for that product
2. Operational logs created for each move
3. ProductIDS arrays updated in categories
4. Denormalized data stays in sync

Next POS Sync:

• All moved products stay in user-assigned categories
• OriginalCategory updates if POS changed
• No products automatically moved back

Operational Logs

What Gets Logged

Every category operation creates a log entry:

{
  "id": "log-abc123",
  "operationType": "product_moved_to_category",
  "menuId": "menu-456",
  "productId": "prod-123",
  "fromCategory": "Tea",
  "toCategory": "Specialty Drinks",
  "source": "USER",
  "message": "Product Matcha Latte moved to category Specialty Drinks",
  "createdAt": 1640995200000,
  "locationId": "loc-789"
}

Log Types

Querying Logs

Via API:

GET /operation-logs?menuId={menuId}&operationType=product_moved_to_category

Via UI: Navigate to Menus → Operation Logs tab

Use Cases:

• Audit trail for compliance
• Troubleshooting sync issues
• Understanding sync decisions
• Tracking user activity

Sync Strategies

Strategy 1: Let POS Lead (Default)

Best For: Simple menus, consistent POS categories

How It Works:

• Don't manually reassign products
• Let POS sync update categories
• Customizations only in OOM categories

Pros: Low maintenance, always matches POS Cons: No customization per channel

Strategy 2: Customize for Channels

Best For: Multi-channel publishing, customer-facing optimization

How It Works:

1. Let POS sync bring in products and categories
2. Create OOM categories for customer experience
3. Manually assign products to OOM categories
4. POS categories remain but products move out

Pros: Optimized UX, preserved during sync Cons: More manual work, need to manage changes

Strategy 3: Hybrid Approach

Best For: Most use cases

How It Works:

1. Most products follow POS categories
2. Key products manually organized (featured, seasonal, etc.)
3. Create a few OOM categories for specials
4. Leave bulk of menu following POS

Pros: Balance of automation and control Cons: Need to track which products customized

Monitoring Sync

Sync Status Indicators

In UI:

• 🔄 "Syncing..." - Sync in progress
• ✅ "Last synced: 5 minutes ago" - Successful
• ⚠️ "Sync failed" - Error occurred
• 🔒 Lock icon on fields - POS-controlled

Via API:

GET /menus/{menuId}

Response includes:

{
  "lastSyncedAt": 1640995200000,
  "syncStatus": "success",
  "modifiedProductsCount": 12 // Products with user modifications
}

Sync Alerts

Configure alerts for:

• Sync failures
• Products removed by POS
• Category structure changes
• Large batch modifications

Troubleshooting

Problem: Products Keep Moving Back

Cause: Modified flag not being set

Check:

1. View product association in database
2. Verify modification.modified = true
3. Check modification.modifiedAt timestamp

Solution:

• Use UI to move products (sets flag automatically)
• If using API, ensure modified: true in payload
• Contact support if flag not persisting

Problem: POS Changes Not Appearing

Cause: Sync may not be running or failing

Check:

1. View operation logs for recent POS_SYNC entries
2. Check sync status in menu details
3. Verify POS integration is active

Solution:

• Manually trigger sync if available
• Check POS system connectivity
• Review error logs for sync failures

Problem: Category Deleted But Keeps Coming Back

Cause: Category still exists in POS

Solution:

1. Delete category in POS system
2. Wait for next POS sync
3. Alternative: Move all products out, hide category

Problem: Bulk Changes Not Protected

Cause: Bulk operation may not set modification flags

Check:

1. Review operational logs for bulk operation
2. Check modification flags on affected products
3. Verify operation completed successfully

Solution:

• Re-apply bulk operation through UI
• Manually verify critical product assignments
• Report issue if bulk operation is failing

Best Practices

Design Practices

Category Naming:

• Use POS categories as base
• Create customer-friendly OOM categories for special groupings
• Keep category names distinct between POS and OOM

Product Organization:

• Group high-value products in custom categories
• Let commodity items follow POS categories
• Seasonal items in dedicated OOM categories

Operational Practices

Monitor Regularly:

• Review sync logs weekly
• Check for unexpected category changes
• Validate key product assignments monthly

Document Customizations:

• Keep list of manually organized products
• Note which categories are OOM-created
• Document business rules for categorization

Test Before Major Changes:

• Test POS updates in staging if available
• Preview menu before publishing after sync
• Have rollback plan for critical menus

Sync Hygiene

Regular Audits:

• Review modification flags quarterly
• Clean up old operational logs
• Verify no "orphaned" product assignments

Change Management:

• Coordinate POS changes with OOM team
• Plan category reorganizations during off-peak
• Communicate sync schedule to staff

Advanced Topics

Manual Modification Flag Management

Via API (use with caution):

PATCH /menus/{menuId}/products/{productId}/association
Content-Type: application/json
 
{
  "modifications": [
    {
      "field": "PRODUCT_CATEGORY",
      "modified": false,  // Reset to follow POS
      "valueCategory": "",
      "originalCategory": ""
    }
  ]
}

Use Cases:

• Bulk reset to POS defaults
• Fixing stuck modification flags
• Migration scenarios

Programmatic Sync Control

For advanced integrations:

POST /internal/menus/{menuId}/sync
Content-Type: application/json
 
{
  "source": "POS",
  "preserveUserModifications": true,
  "dryRun": false
}

Note: Requires special permissions, contact support.

Next Steps