Accessing Orders

1. Navigate to /buylist/orders in your SortSwift dashboard
2. Orders are fetched via GET /api/buylist/orders with authentication
3. Orders are filtered by authenticated user's storeId automatically
4. Orders are sorted by createdAt descending (newest first) by default

Order List View

• Order Table: Displays key information:
  • Order ID (clickable to view details)
  • Customer Name & Email
  • Order Status (color-coded chip)
  • Order Type (Drop-in / Delivery)
  • Total Cash & Credit amounts
  • Cart item count
  • Created date
  • Last message indicator (unread badge)
  • Action buttons (View, Edit, Chat, Delete)
• Responsive Design: Table collapses to card view on mobile devices
• Pagination: Orders paginated (default 20 per page), adjustable via UI controls
• Status Colors: Each status has distinct color:
  • pending_approval / pending_drop_in / pending_delivery: Cyan
  • approved: Dark Blue
  • received: Dark Purple
  • reviewing: Dark Orange
  • complete: Dark Green
  • denied: Dark Red
  • Custom statuses: Use configured color from store settings

Filtering & Search

• Status Filter: Dropdown to filter by order status (All, pending_approval, approved, complete, etc.)
• Search Bar: Real-time search across:
  • Customer Name
  • Customer Email
  • Order ID
  • Product Names (cleanName, groupName)
• Date Range: Filter by order creation date (optional feature)
• POS Buy Filter: Toggle to show/hide POS-created orders (posBuy flag)
• Unread Messages: Filter to show only orders with unread messages from customers

Order Detail View

• Customer Information:
  • Name, Email, Phone
  • Order Type (Drop-in / Delivery)
  • Address (if delivery)
  • PayPal Email (if provided)
  • Customer Notes
• Cart Items:
  • Product Name, Set, Number
  • Condition & Language badges
  • Printing type (Normal, Foil, etc.)
  • Quantity
  • Cash & Credit prices (added and paid)
  • Payment Type (Cash/Credit/Split)
  • Split percentage (if Split)
  • Item notes
  • Sent to Inventory status
  • Product image thumbnail
• Order Totals:
  • Total Cash (addedCashPrice sum)
  • Total Credit (addedCreditPrice sum)
  • Final Cash Total (cashTotal, if complete)
  • Final Credit Total (creditTotal, if complete)
  • Final Sell Total (sellTotal, if complete)
  • Penalty applied (if any)
• Status History: Expandable accordion showing all status changes with timestamps
• Chat Messages: Integrated chat interface showing merged system messages and customer/store messages

Editing Orders

1. Adding Items:
   • Click "Add Item" button in order detail view
   • Search for product by name or TCGPlayer ID
   • Select condition, language, printing
   • Enter quantity
   • Choose payment type (Cash/Credit/Split)
   • If Split: Set split percentage (e.g., 70 for 70% cash, 30% credit)
   • Price fetched automatically via get-price API
   • Manual price override available
   • Click "Add" to add item to cart
   • Order totals recalculated automatically
2. Removing Items:
   • Click delete icon on cart item
   • Confirm deletion
   • Item removed from cart array
   • Order totals recalculated
   • System message added: "Removed line: [item details]"
3. Modifying Items:
   • Click edit icon on cart item
   • Modify quantity, condition, language, printing
   • Change payment type or split percentage
   • Override prices manually
   • Add/edit item notes
   • Click "Save" to update
   • System message added: "Updated line: [old] → [new]"
4. Refreshing Prices:
   • Click "Refresh Prices" button to refetch prices for all items
   • Uses concurrency-limited API calls (25 at a time)
   • Fetches latest prices from get-price endpoint
   • Updates addedCashPrice and addedCreditPrice for each item
   • Totals recalculated automatically
   • Loading indicators shown during refresh
   • Errors logged but don't block other items
5. Saving Changes:
   • All edits stored locally until "Save Order" clicked
   • PATCH /api/buylist/orders/:orderId updates order document
   • Cart array, totals, and notes updated
   • Success notification shown
   • Order detail view refreshed

Status Management

• Status Dropdown: Quick-change dropdown in order detail view with all available statuses
• Status Buttons: Quick action buttons for common statuses:
  • Approve (sets to 'approved')
  • Deny (sets to 'denied')
  • Mark Received (sets to 'received')
  • Mark Reviewing (sets to 'reviewing')
  • Complete (sets to 'complete', prompts for final totals)
• Completing Orders:
  • When marking complete, dialog prompts for final totals
  • Can override calculated totals with manual values
  • System calculates totals from cart if not provided
  • Applies penalty logic if configured
  • Stores cashTotal, creditTotal, sellTotal
  • Sets paidCashPrice and paidCreditPrice for each item
  • Customer receives completion email
• Status Validation: System validates status transitions and prevents invalid changes

Sending to Inventory

• Prerequisites: Order must be in 'complete' status
• Full Order Send:
  • Click "Send to Inventory" button
  • Confirms all non-sent items will be sent
  • POST /api/buylist/orders/:orderId/send-to-inventory
  • All items marked as sentToInventory: true
  • Success notification shown
• Individual Item Send:
  • Click "Send" icon on individual cart item
  • Only that item sent to inventory
  • POST /api/buylist/orders/:orderId/items/send-to-inventory
  • Item marked as sentToInventory: true
  • Useful for sending verified items as they're inspected
• Visual Indicators: Items already sent show checkmark badge, can't be sent again

Penalty Management

• Penalty Types:
  • none: No penalty applied
  • per_line: Penalty applied per item (if penaltyApplied flag set on item)
  • all_inclusive: Single penalty percentage applied to total order
• Applying Penalties:
  • Set penaltyType dropdown in order detail view
  • Set penaltyPercentage (0-100)
  • For per_line: Mark individual items with penaltyApplied flag
  • Penalties calculated when order marked complete
  • Reduces final totals by percentage
• Common Use Cases: Condition downgrades, missing items, damaged cards, late submissions

CSV Export

• Export Single Order: Click "Export CSV" button in order detail view
• Export Multiple Orders: Select orders in list view, click "Export Selected"
• CSV Format:
  • One row per cart item
  • Columns: Product Name, Set, Number, Condition, Language, Printing, Quantity, Cash Price, Credit Price, Payment Type, Notes
  • Includes order header info (customer name, email, order ID, status, totals)
• Use Cases: Backup records, external processing, accounting, inventory reconciliation

Custom Items

• Adding Custom Items:
  • Click "Add Custom Item" button
  • Enter description (e.g., "Miscellaneous Bulk Rares")
  • Enter base quantity
  • Enter base cash and credit prices
  • User can override quantity (userQuantity)
  • Price calculated proportionally: (userQuantity / baseQuantity) × basePrice
  • isCustomItem flag set to true
  • customItemData object stores base values
• Use Cases: Bulk lots, accessories, items without TCGPlayer IDs, miscellaneous inventory

Chat Integration

• Accessing Chat: Click "Chat" button or icon in order list or detail view
• Message Display:
  • System messages merged intelligently (e.g., "Added 2 lines" instead of two separate "Added line" messages)
  • Customer messages shown with timestamp
  • Store messages shown with sender name
  • Messages sorted by timestamp
  • Unread indicator badge
• Sending Messages:
  • Type message in chat input
  • Click "Send" or press Enter
  • POST /api/buylist/orders/:orderId/messages
  • Message added to order.messages array
  • Customer receives email notification (if enabled)
  • lastMessageSender updated
• Auto-Refresh: Chat polls for new messages every 3 seconds if enabled

Best Practices

• Workflow:
  1. Review pending orders daily
  2. Approve or deny promptly
  3. Update status as cards received
  4. Review/inspect items thoroughly
  5. Apply penalties if needed before completing
  6. Mark complete with accurate totals
  7. Send to inventory after verification
• Price Management: Refresh prices before completing orders to ensure accuracy
• Communication: Use chat to clarify condition issues, missing items, or delays
• Documentation: Add notes to items when modifying conditions or quantities
• Batch Processing: Export CSV for accounting/reconciliation on regular schedule
• Error Handling: Check SKU coverage before sending to inventory to avoid skipped items