Available Order Statuses

• pending_approval: Order created and awaiting store owner review. Default status for customer-submitted orders unless auto-approve is enabled.
• approved: Order has been approved by store owner. Customer can now drop off or ship cards. Triggers email notification to customer with store address.
• denied: Order has been denied/rejected by store owner. Customer is notified via email if enabled.
• pending_drop_in: Order approved, customer will drop cards off at physical location. Used for dropIn orderType.
• pending_delivery: Order approved, customer will ship cards via mail. Used for delivery orderType, requires customerAddress.
• received: Cards have been received by store (either dropped off or received via mail).
• reviewing: Store is currently reviewing/inspecting the received cards to verify condition and quantity.
• complete: Order is fully processed. Final totals calculated and stored. Cards can be sent to inventory. Triggers completion email to customer.

Status Transition Logic

1. Order Created: Initial status determined by:
   • POS buys: Uses req.body.status or defaults to 'approved'
   • Customer orders: Uses buylistConfig.defaultOrderStatus if set, otherwise checks autoApprove flag (true='approved', false='pending_approval')
2. Status Change: When status changes via PUT /api/buylist/orders/:orderId/status or shortcut endpoints:
   • Previous status stored in statusHistory array with timestamp
   • System message added: "Order status changed from [old] to [new]"
   • Order document updated and saved
   • Email sent to store owner about status change
   • If new status='approved': Customer receives approval email with store address
   • If new status='complete': Customer receives completion email
3. Complete Status Special Handling: When order status changes to 'complete':
   • If req.body provides cashTotal, creditTotal, or sellTotal: Uses those values
   • Otherwise: Calculates totals from cart items:
     • Cash items: addedCashPrice × quantity
     • Credit items: addedCreditPrice × quantity
     • Split items: (addedCashPrice × quantity × splitPercentage%) + (addedCreditPrice × quantity × (100-splitPercentage)%)
     • Custom items: Uses customItemData.userQuantity and priceMultiplier for proportional pricing
     • Applies penaltyType logic: per_line penalty applied per item if penaltyApplied=true, all_inclusive penalty applied to totals
   • Stores cashTotal, creditTotal, sellTotal in order document
   • Sets paidCashPrice = addedCashPrice and paidCreditPrice = addedCreditPrice for each cart item
   • All totals rounded to 3 decimal places

Status Change API Endpoints

• PUT /api/buylist/orders/:orderId/status - Generic endpoint, requires {status: 'status_name'} in body
• PUT /api/buylist/orders/:orderId/approve - Shortcut to set status='approved'
• PUT /api/buylist/orders/:orderId/deny - Shortcut to set status='denied'
• PATCH /api/buylist/orders/:orderId/pending-drop-in - Shortcut to set status='pending_drop_in'
• PATCH /api/buylist/orders/:orderId/pending-delivery - Shortcut to set status='pending_delivery'
• PATCH /api/buylist/orders/:orderId/received - Shortcut to set status='received'
• PATCH /api/buylist/orders/:orderId/reviewing - Shortcut to set status='reviewing'
• PATCH /api/buylist/orders/:orderId/complete - Shortcut to set status='complete'. Can include body with cashTotal, creditTotal, sellTotal to override calculated totals

Status History Tracking

Every status change is recorded in the statusHistory array within the BuylistOrder document:

• Initial Entry: When order is created, statusHistory includes: {previousStatus: null, newStatus: initialStatus, changedAt: timestamp}
• Subsequent Changes: Each status change adds entry: {previousStatus: oldStatus, newStatus: newStatus, changedAt: timestamp}
• Audit Trail: Complete history allows tracking when order moved through each stage
• Timestamp: Each entry includes changedAt field with exact Date/time of change

Custom Statuses

Stores can define custom statuses beyond the default ones. Custom statuses are managed via:

• GET /api/buylist/store/custom-statuses - List all custom statuses
• POST /api/buylist/store/custom-statuses - Add new custom status with id, name, color
• PUT /api/buylist/store/custom-statuses/:statusId - Update custom status
• DELETE /api/buylist/store/custom-statuses/:statusId - Delete custom status
• GET /api/buylist/store/default-status - Get default order status
• PUT /api/buylist/store/default-status - Set default order status (used for new orders)

Custom statuses can be used like default statuses but are not validated against ORDER_STATUSES enum. They support custom colors and labels for display in the UI.

Email Notifications

• Order Created: Store owner receives email with order details and CSV attachment. Customer receives confirmation email. (Skipped for POS buys)
• Status Changed: Store owner always receives email notification about status changes
• Approved Status: Customer receives email with approval message and store address for drop-off/shipping
• Complete Status: Customer receives completion email thanking them
• Email Configuration: Controlled by storeConfig.emailsEnabled flag. If false, no emails sent (except internal system logs)
• Email Addresses: Store owner email from storeConfig.notificationEmail or user.email. Customer email from order.customerEmail
• From Address: Uses storeConfig.outboundEmail if set, otherwise defaults to SortSwift Buylist <[email protected]>

Typical Workflow Example

1. Day 1: Customer submits order → Status: pending_approval → Emails sent to store owner and customer
2. Day 1: Store owner reviews order → PUT /orders/:id/approve → Status: approved → Customer receives approval email
3. Day 3: Customer drops off cards → Store owner updates → PATCH /orders/:id/received → Status: received
4. Day 3: Store inspects cards → PATCH /orders/:id/reviewing → Status: reviewing
5. Day 3: Inspection complete → PATCH /orders/:id/complete → Status: complete → Totals calculated, customer receives completion email
6. Day 3: Store sends to inventory → POST /orders/:id/send-to-inventory → Cards added to inventory, order marked sentToInventory=true

Status Change Validation

• Status Must Be Valid: New status must be in ORDER_STATUSES array (or custom status) or returns 400 error
• Order Must Exist: Order must be found and belong to authenticated user's store, or returns 404 error
• Send to Inventory: Order must be in 'complete' status before sending to inventory, or returns 400 error
• No Duplicate Changes: System allows changing to same status but logs it in statusHistory (no error)
• Authentication Required: All status change endpoints require authentication (check_auth middleware)