Product Assignment

Efficiently assign products to categories with bulk operations, multi-select capabilities, and intelligent status tracking. Product assignment helps you organize your menu for optimal customer discovery.

Overview

Product Assignment features:

• Bulk Operations: Select and assign multiple products at once
• Multi-Location Support: Add products from any linked location
• Status Indicators: Visual feedback for existing assignments
• Smart Validation: Prevents duplicate assignments
• One-Category Rule: Products can only be in one category per menu

Assignment Concepts

One Category Per Menu

Each product can be assigned to exactly one category per menu:

✅ Allowed: Same product in different categories across different menus

Menu: Breakfast → Product: Coffee → Category: Hot Beverages
Menu: All Day   → Product: Coffee → Category: Coffee Drinks

❌ Not Allowed: Same product in multiple categories within one menu

Menu: All Day → Product: Coffee → Categories: [Hot Beverages, Coffee Drinks]

Behavior: Moving a product to a new category automatically removes it from the old category.

Assignment Status

Products show their current assignment status:

Assigning Products

Via Edit Mode

Basic Assignment:

1. Navigate to Menus → Select menu → Products tab
2. Click "Edit" to enter edit mode
3. Select one or more products using checkboxes
4. Click "Move to Category" button in the footer
5. Choose target category from dropdown
6. Click "Move" to confirm

With New Category:

1. Follow steps 1-4 above
2. Select "+ Create New Category" from dropdown
3. Enter new category name
4. Click "Move" to create category and assign products

Via Add Products Modal

From Location:

1. Select a category in your menu
2. Click "+ Add Products" button
3. Add Products from Location modal opens
4. Search and select products from linked locations
5. Products from multiple locations are shown
6. Only products available across all linked locations appear
7. Click "Add Products (X)" to assign

Modal Features:

• Search by product name or ID
• Checkbox for individual selection
• "Select All" for bulk selection
• Product count in the confirm button
• Visual indicators for already-assigned products

Via API

Move Products to Category:

POST /menus/{menuId}/categories/{categoryId}/products/move
Content-Type: application/json
 
{
  "productIds": ["prod-123", "prod-456", "prod-789"],
  "newCategoryName": "Seasonal Specials"  // Optional: creates category
}

Response:

{
  "movedProducts": [
    {
      "productId": "prod-123",
      "productName": "Pumpkin Spice Latte",
      "fromCategory": "Coffee",
      "toCategory": "Seasonal Specials",
      "success": true
    }
  ],
  "failedProducts": [
    {
      "productId": "prod-999",
      "productName": "Unknown Item",
      "reason": "Product not found in menu",
      "error": "NOT_FOUND"
    }
  ]
}

Add Products to Category:

POST /menus/{menuId}/categories/{categoryId}/products
Content-Type: application/json
 
{
  "productIds": ["prod-101", "prod-102"]
}

Response:

{
  "addedProducts": [
    {
      "productId": "prod-101",
      "productName": "Croissant",
      "categoryId": "cat-pastries",
      "categoryName": "Pastries",
      "success": true
    }
  ],
  "skippedProducts": [
    {
      "productId": "prod-102",
      "productName": "Muffin",
      "reason": "Already assigned to this category",
      "existingCategory": "Pastries"
    }
  ]
}

Bulk Operations

Move Products (Bulk)

Use Case: Reorganizing multiple products at once

Steps:

1. Enter edit mode
2. Select multiple products (checkboxes)
3. Click "Move to Category" in footer
4. Footer shows: "X products selected"
5. Choose target category
6. All products move together

Example Scenario:

Moving 5 seasonal items from "Coffee" → "Seasonal Specials"
✓ Pumpkin Spice Latte
✓ Maple Pecan Latte
✓ Cranberry White Mocha
✓ Gingerbread Latte
✓ Peppermint Mocha

Clear Selection

To deselect products:

• Click "Clear" button in footer
• Click selected checkboxes individually
• Exit and re-enter edit mode

Remove from Category

Use Case: Unassigning products from their current category

DELETE /menus/{menuId}/categories/{categoryId}/products
Content-Type: application/json
 
{
  "productIds": ["prod-123", "prod-456"]
}

Behavior: Products become unassigned (no category).

Multi-Location Product Selection

How It Works

When adding products from locations:

1. Intersection Logic: Only products present in all linked locations appear
2. Unique by POS ID: Products matched by posId across locations
3. First Location Data: Product details from the first linked location used
4. Assignment Check: Visual indicators show if product already assigned

Example:

Menu linked to: Location A, Location B, Location C

Location A products: [Coffee, Tea, Juice, Sandwich]
Location B products: [Coffee, Tea, Water, Salad]
Location C products: [Coffee, Tea, Smoothie]

Available to add: [Coffee, Tea]  ← Only common products

Search and Filter

Search Functionality:

• Search by product name (case-insensitive)
• Search by POS ID
• Real-time filtering as you type
• Debounced for performance

Filter Behavior:

• Filtered products shown in list
• Select All applies to filtered products only
• Selections preserved when changing search

Visual Indicators

Already Assigned:

☑ Latte ⚠️ Already in "Coffee" - will be moved

Unassigned:

☐ Croissant

Assigned to This Category:

☑ Espresso ✓ (checkbox disabled)

Assignment Validation

Pre-Assignment Checks

Before assigning products, the system validates:

1. Product Exists: Product must be in menu
2. Category Exists: Target category must exist
3. Menu Match: Product and category must be in same menu
4. Duplicate Check: Warns if already in target category

Error Handling

Common Errors:

Error Response Example:

{
  "error": "PRODUCT_NOT_FOUND",
  "message": "Product prod-999 not found in menu menu-123",
  "productId": "prod-999",
  "menuId": "menu-123"
}

Assignment Tracking

Modification System

Every assignment is tracked using modifications:

{
  "field": "PRODUCT_CATEGORY",
  "modified": true,
  "valueCategory": "cat-beverages", // Current assignment
  "originalCategory": "cat-coffee", // POS default
  "modifiedAt": 1640995200000 // Timestamp
}

Key Fields:

• modified: true → User manually assigned (protected from POS sync)
• modified: false → Following POS default (will update with POS)

Operational Logs

All assignments are logged:

{
  "operationType": "product_added_to_category",
  "productId": "prod-123",
  "menuId": "menu-456",
  "fromCategory": "",
  "toCategory": "cat-coffee",
  "source": "USER",
  "message": "Product Latte added to category Coffee",
  "createdAt": 1640995200000
}

Log Types:

• product_added_to_category - Initial assignment
• product_moved_to_category - Moved between categories
• product_removed_from_category - Unassigned

View logs in Operation Logs section for audit trail.

Best Practices

Organization Strategy

Start with Core Categories:

1. Create main categories first (Appetizers, Mains, Desserts, Drinks)
2. Add subcategories if menu is large (Hot Drinks, Cold Drinks)
3. Assign products to the most specific applicable category

Use Bulk Operations:

• Assign similar products together
• Use search to find related items quickly
• Move seasonal items in bulk

Leverage Multi-Location:

• Ensure consistent product naming across locations
• Use POS IDs for reliable matching
• Add common products to shared menus

Performance Tips

For Large Menus (500+ products):

• Use search to narrow down products before selecting
• Assign in batches rather than all at once
• Let each batch complete before starting next

For Multiple Locations:

• Link locations strategically
• Consider location-specific menus for unique items
• Use intersection wisely (more locations = fewer common products)

Workflows

New Menu Setup

1. Create or sync menu from POS
2. Create category structure
3. Use "Add Products from Location" for initial population
4. Review and adjust assignments
5. Publish menu

Seasonal Update

1. Create seasonal category (e.g., "Summer Specials")
2. Search for seasonal products
3. Bulk move to seasonal category
4. After season: Move back or archive

Menu Reorganization

1. Enter edit mode
2. Review current category distribution
3. Create new categories if needed
4. Select and move products in bulk
5. Delete unused categories
6. Exit edit mode and verify

Troubleshooting

Products Not Appearing in Add Modal

Possible Causes:

• Product not in any linked location
• Product not in all linked locations (intersection logic)
• Product already assigned to current category

Solution:

• Check product availability across locations
• Verify product exists in menu
• Review location linkages

Assignment Not Saving

Possible Causes:

• Network connectivity issue
• Validation error
• Permission denied

Solution:

1. Check browser console for errors
2. Verify you have edit permissions
3. Try again with smaller batch
4. Contact support if persists

Products Disappearing After POS Sync

Cause: POS sync may have removed products no longer in POS

Solution:

• Products deleted in POS are removed from OOM
• Check POS system for product status
• Re-add products if needed

Learn about POS Sync Protection →

Next Steps