Order & Bill Management

Part of: MPAC SmartPOS Cloud Platform - Product RequirementsVersion: 2.0 Last Updated: 2026-01-28

---

Overview

The Order & Bill Management domain handles the complete lifecycle of customer transactions from order creation through bill payment. It supports flexible ordering scenarios (dine-in, takeaway, delivery), advanced bill operations (splitting, combining), and integrates with the payment processing system. This domain is central to the restaurant/retail operations, managing the flow from customer selection to payment completion.

Table of Contents

• Order Lifecycle
• Bill Management

---

Order Lifecycle

Purpose: Manage customer orders from creation to completion.

Order States

CREATE → OPEN → BILLED → COMPLETED
              ↓
          CANCELLED

Order Entity

{
  "id": "uuid",
  "merchant_id": 1,
  "store_id": 2,
  "device_id": "device_uuid",
  "order_number": "ORD-001234",
  "order_type": "dine_in|takeaway|delivery",
  "table_number": "5",
  "customer_id": "cust_uuid" (optional),
  "items": [
    {
      "sequence": 1,
      "item_name": "Coffee",
      "quantity": 2,
      "unit_price": 50000,
      "subtotal": 100000
    }
  ],
  "subtotal": 100000,
  "tax_amount": 8000,
  "discount_amount": 0,
  "total_amount": 108000,
  "status": "open|billed|completed|cancelled",
  "created_at": "2026-01-28T10:00:00Z",
  "completed_at": null
}

Order Operations

1. Create Order - Add items to cart
2. Modify Order - Add/remove items (only if not billed)
3. Generate Bill - Create payment request from order
4. Complete Order - Mark as finished after payment
5. Cancel Order - Cancel before billing

API Endpoints

• POST /orders - Create order
• GET /orders - List orders with filters
• GET /orders/{id} - Order details
• PATCH /orders/{id} - Update order items
• POST /orders/{id}/cancel - Cancel order
• POST /bills - Generate bill from order

---

Bill Management

Purpose: Payment requests generated from orders with support for splitting and combining.

Bill States

PENDING → PARTIAL → PAID
    ↓
CANCELLED

Bill Entity

{
  "id": "bill_uuid",
  "merchant_id": 1,
  "store_id": 2,
  "order_id": "order_uuid",
  "bill_number": "BILL-001234",
  "staff_code": "STAFF001",
  "customer_id": "cust_uuid" (optional),
  "subtotal": 100000,
  "discount_amount": 10000,
  "tax_amount": 7200,
  "total_amount": 97200,
  "paid_amount": 50000,
  "remaining_amount": 47200,
  "status": "pending|partial|paid|cancelled",
  "is_split": false,
  "is_combined": false,
  "combined_bill_ids": [],
  "combined_table_numbers": [],
  "created_at": "2026-01-28T10:30:00Z"
}

Bill Operations

1. Create Bill from Order

POST /bills
{
  "order_id": "uuid",
  "staff_code": "STAFF001",
  "tax_percentage": 8,
}

2. Split Bill by Amount

Customer A pays: ¥50,000
Customer B pays: ¥47,200

Creates 2 Split records:
- Split 1: amount=50000, status=pending
- Split 2: amount=47200, status=pending

Each split can be paid separately

3. Split Bill by Items

Customer A: Coffee (¥100,000)
Customer B: Sandwich (¥80,000)

Creates 2 Split records:
- Split 1: item_ids=[item1], amount=100000
- Split 2: item_ids=[item2], amount=80000

4. Combine Bills

Table 5 Bill: ¥100,000
Table 8 Bill: ¥150,000

POST /bills/combine
{
  "table_numbers": ["Table 5", "Table 8"],
  "staff_code": "STAFF001"
}

Creates new combined bill:
- total_amount: ¥250,000
- combined_bill_ids: [bill1_id, bill2_id]
- combined_table_numbers: ["Table 5", "Table 8"]

Original bills marked as deleted (soft delete)

API Endpoints

• POST /bills - Create bill from order
• GET /bills - List bills with filters
• GET /bills/{id} - Bill details
• POST /bills/{id}/split - Split bill by amount or items
• POST /bills/combine - Combine multiple bills
• POST /bills/{id}/cancel - Cancel bill

---

See Also

Related Domains:

• Payment Processing - Payment execution and transaction management
• Customer - Customer data integration
• Receipt & Invoice - Document generation and delivery

Technical Implementation:

• Database Architecture - Order and bill data model and schema design
• Business Logic - Order and bill state machine and validation rules

API Reference:

• API Endpoints - Complete API specification for order and bill operations

---

Navigation: ← Previous: Merchant Hierarchy | ↑ Back to Domain Catalog | Next: Payment Processing →