apskel-pos-backend/docs/ADVANCED_ORDER_MANAGEMENT.md

Advanced Order Management API Documentation

Overview

The Advanced Order Management API provides comprehensive functionality for managing orders beyond basic operations. This includes partial refunds, void operations, and bill splitting capabilities.

Features

• ✅ Partial Refund: Refund specific items from paid orders
• ✅ Void Order: Cancel ongoing orders (per item or entire order)
• ✅ Split Bill: Split orders by items or amounts
• ✅ Order Status Management: Support for PARTIAL and VOIDED statuses
• ✅ Transaction Tracking: Complete audit trail for all operations
• ✅ Validation: Comprehensive validation for all operations

API Endpoints

1. Partial Refund

POST /order/partial-refund

Refund specific items from a paid order while keeping the remaining items.

Request Body

{
  "order_id": 123,
  "reason": "Customer returned damaged items",
  "items": [
    {
      "order_item_id": 456,
      "quantity": 2
    },
    {
      "order_item_id": 789,
      "quantity": 1
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
order_id	int64	Yes	ID of the order to refund
reason	string	Yes	Reason for the partial refund
items	array	Yes	Array of items to refund

Item Parameters

Parameter	Type	Required	Description
order_item_id	int64	Yes	ID of the order item to refund
quantity	int	Yes	Quantity to refund (min: 1)

Response

Success (200 OK)

{
  "success": true,
  "status": 200,
  "data": {
    "order_id": 123,
    "status": "PARTIAL",
    "refunded_amount": 75000,
    "remaining_amount": 25000,
    "reason": "Customer returned damaged items",
    "refunded_at": "2024-01-15T10:30:00Z",
    "customer_name": "John Doe",
    "payment_type": "CASH",
    "refunded_items": [
      {
        "order_item_id": 456,
        "item_name": "Bakso Special",
        "quantity": 2,
        "unit_price": 25000,
        "total_price": 50000
      },
      {
        "order_item_id": 789,
        "item_name": "Es Teh Manis",
        "quantity": 1,
        "unit_price": 25000,
        "total_price": 25000
      }
    ]
  }
}

2. Void Order

POST /order/void

Void an ongoing order (NEW or PENDING status) either entirely or by specific items.

Request Body

Void Entire Order:

{
  "order_id": 123,
  "reason": "Customer cancelled order",
  "type": "ALL"
}

Void Specific Items:

{
  "order_id": 123,
  "reason": "Customer changed mind about some items",
  "type": "ITEM",
  "items": [
    {
      "order_item_id": 456,
      "quantity": 1
    }
  ]
}

Request Parameters

Parameter	Type	Required	Description
order_id	int64	Yes	ID of the order to void
reason	string	Yes	Reason for voiding
type	string	Yes	Type: "ALL" or "ITEM"
items	array	No	Required if type is "ITEM"

Response

Success (200 OK)

{
  "success": true,
  "status": 200,
  "data": {
    "order_id": 123,
    "status": "VOIDED",
    "reason": "Customer cancelled order",
    "voided_at": "2024-01-15T10:30:00Z",
    "customer_name": "John Doe",
    "voided_items": [
      {
        "order_item_id": 456,
        "item_name": "Bakso Special",
        "quantity": 1,
        "unit_price": 25000,
        "total_price": 25000
      }
    ]
  }
}

3. Split Bill

POST /order/split-bill

Split an order into a separate order by items or amounts.

Request Body

Split by Items:

{
  "order_id": 123,
  "type": "ITEM",
  "payment_method": "CASH",
  "payment_provider": "CASH",
  "items": [
    {
      "order_item_id": 789,
      "quantity": 2
    },
    {
      "order_item_id": 101,
      "quantity": 1
    }
  ]
}

Split by Amount:

{
  "order_id": 123,
  "type": "AMOUNT",
  "payment_method": "CASH",
  "payment_provider": "CASH",
  "amount": 50000
}

Request Parameters

Parameter	Type	Required	Description
order_id	int64	Yes	ID of the order to split
type	string	Yes	Type: "ITEM" or "AMOUNT"
payment_method	string	Yes	Payment method for split order
payment_provider	string	No	Payment provider for split order
items	array	No	Required if type is "ITEM"
amount	float	No	Required if type is "AMOUNT" (must be less than order total)

Item Parameters

Parameter	Type	Required	Description
order_item_id	int64	Yes	ID of the order item to split
quantity	int	Yes	Quantity to split (min: 1)

Response

Success (200 OK)

{
  "success": true,
  "status": 200,
  "data": {
    "id": 124,
    "partner_id": 1,
    "status": "PAID",
    "amount": 100000,
    "total": 110000,
    "tax": 10000,
    "customer_id": 456,
    "customer_name": "John Doe",
    "payment_type": "CASH",
    "payment_provider": "CASH",
    "source": "POS",
    "created_at": "2024-01-15T10:30:00Z",
    "updated_at": "2024-01-15T10:30:00Z",
    "order_items": [
      {
        "id": 789,
        "item_id": 1,
        "item_name": "Bakso Special",
        "price": 50000,
        "quantity": 2,
        "subtotal": 100000
      }
    ]
  }
}

Business Logic

Partial Refund Process

1. Validation

   • Verify order exists and belongs to partner
   • Ensure order status is "PAID"
   • Validate refund items exist and quantities are valid

2. Item Updates

   • Reduce quantities of refunded items
   • Remove items completely if quantity becomes 0
   • Recalculate order totals

3. Order Status Update

   • Set status to "PARTIAL" if items remain
   • Set status to "REFUNDED" if all items refunded

4. Transaction Creation

   • Create refund transaction with negative amount
   • Track refund details

Void Order Process

1. Validation

   • Verify order exists and belongs to partner
   • Ensure order status is "NEW" or "PENDING"
   • Validate void items if type is "ITEM"

2. Void Operations

   • ALL: Set order status to "VOIDED"
   • ITEM: Reduce quantities and recalculate totals

3. Status Management

   • Set status to "PARTIAL" if items remain
   • Set status to "VOIDED" if all items voided

Split Bill Process

1. Validation

   • Verify order exists and belongs to partner
   • Ensure order status is "NEW" or "PENDING"
   • Validate split configuration

2. Split Operations

   • ITEM: Create new PAID order with specified items, reduce quantities in original order
   • AMOUNT: Create new PAID order with specified amount, reduce amount in original order

3. Order Management

   • Original order remains PENDING with reduced items/amount
   • New split order becomes PAID with specified payment method
   • Recalculate totals for both orders

Order Status Flow

NEW → PENDING → PAID → REFUNDED
  ↓      ↓        ↓
VOIDED  VOIDED   PARTIAL

Error Handling

Common Error Responses

Order Not Found (404)

{
  "success": false,
  "status": 404,
  "message": "order not found"
}

Invalid Order Status (400)

{
  "success": false,
  "status": 400,
  "message": "only paid order can be partially refunded"
}

Invalid Quantity (400)

{
  "success": false,
  "status": 400,
  "message": "refund quantity 3 exceeds available quantity 2 for item 456"
}

Split Amount Mismatch (400)

{
  "success": false,
  "status": 400,
  "message": "split amount 95000 must be less than order total 100000"
}

Database Schema Updates

Orders Table

-- New statuses supported
ALTER TABLE orders ADD CONSTRAINT check_status 
CHECK (status IN ('NEW', 'PENDING', 'PAID', 'REFUNDED', 'VOIDED', 'PARTIAL'));

Order Items Table

-- Support for quantity updates
ALTER TABLE order_items ADD COLUMN updated_at TIMESTAMP DEFAULT NOW();

Constants

Order Status

const (
    New      OrderStatus = "NEW"
    Paid     OrderStatus = "PAID"
    Cancel   OrderStatus = "CANCEL"
    Pending  OrderStatus = "PENDING"
    Refunded OrderStatus = "REFUNDED"
    Voided   OrderStatus = "VOIDED"    // New
    Partial  OrderStatus = "PARTIAL"   // New
)

Testing Examples

cURL Examples

Partial Refund:

curl -X POST http://localhost:8080/api/v1/order/partial-refund \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "reason": "Customer returned damaged items",
    "items": [
      {
        "order_item_id": 456,
        "quantity": 2
      }
    ]
  }'

Void Order:

curl -X POST http://localhost:8080/api/v1/order/void \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "reason": "Customer cancelled order",
    "type": "ALL"
  }'

Split Bill:

curl -X POST http://localhost:8080/api/v1/order/split-bill \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -d '{
    "order_id": 123,
    "type": "ITEM",
    "payment_method": "CASH",
    "payment_provider": "CASH",
    "items": [
      {
        "order_item_id": 456,
        "quantity": 1
      },
      {
        "order_item_id": 789,
        "quantity": 1
      }
    ]
  }'

Security Considerations

1. Authorization: Only authorized users can perform these operations
2. Audit Trail: All operations are logged with user and timestamp
3. Validation: Strict validation prevents invalid operations
4. Data Integrity: Transaction-based operations ensure consistency

Future Enhancements

1. Bulk Operations: Support for bulk partial refunds/voids
2. Approval Workflow: Multi-level approval for large operations
3. Notification System: Customer notifications for refunds/voids
4. Analytics: Dashboard for operation trends and analysis
5. Integration: Integration with inventory management systems

Support

For questions or issues with the Advanced Order Management API, please contact the development team or create an issue in the project repository.