Skip to main content

Order Lifecycle

Understanding how orders progress from creation to completion.

Lifecycle Overview​

An order goes through several states during its lifetime:

PENDING → IN_PROGRESS → DELIVERED → COMPLETED
                ↓
            CANCELLED

Order States​

PENDING​

Description: Order created, waiting for deliveries

Characteristics:

  • No items delivered yet
  • Escrow balance held (if charge-on-creation enabled)
  • Visible to all players
  • Can be cancelled (if allowed)

Transitions:

  • → IN_PROGRESS when first delivery occurs
  • → CANCELLED if cancelled
  • → Expired if time limit reached

IN_PROGRESS​

Description: Order has partial deliveries

Characteristics:

  • Some items delivered
  • Partial payment made to deliverers
  • Remaining items still needed
  • Can receive more deliveries

Transitions:

  • → DELIVERED when all items delivered
  • → CANCELLED if cancelled (may be restricted)
  • → Expired if time limit reached

DELIVERED​

Description: All items delivered, waiting for collection

Characteristics:

  • All items delivered
  • Deliverers paid
  • Items available for collection
  • Order creator can collect items

Transitions:

  • → COMPLETED when all items collected
  • → Auto-deleted when fully collected and paid

COMPLETED​

Description: Order fully fulfilled and collected

Characteristics:

  • All items collected
  • All payments processed
  • Order ready for deletion
  • Auto-deleted to save storage

Transitions:

  • → Deleted (automatic cleanup)

CANCELLED​

Description: Order cancelled by creator or admin

Characteristics:

  • Order no longer active
  • Escrow refunded (if enabled)
  • No new deliveries allowed
  • May be kept for record-keeping

Transitions:

  • → Deleted (optional, configurable)

Lifecycle Diagram​

PENDINGIN_PROGRESSDELIVEREDCOMPLETEDCANCELLEDFirst deliveryAll deliveredCollectedCancelledCancelled

State Transitions​

Creation → PENDING​

When an order is created:

  1. Order created with PENDING status
  2. Payment deducted (if charge-on-creation enabled)
  3. Escrow balance set
  4. Order visible to all players

PENDING → IN_PROGRESS​

When first delivery occurs:

  1. First items delivered
  2. Status changes to IN_PROGRESS
  3. Partial payment to deliverer
  4. Remaining items still needed

IN_PROGRESS → DELIVERED​

When all items delivered:

  1. Last items delivered
  2. Status changes to DELIVERED
  3. All deliverers paid
  4. Items available for collection

DELIVERED → COMPLETED​

When all items collected:

  1. Order creator collects items
  2. Status changes to COMPLETED
  3. Order auto-deleted
  4. Lifecycle complete

Any State → CANCELLED​

When order is cancelled:

  1. Status changes to CANCELLED
  2. Escrow refunded (if enabled)
  3. No new deliveries allowed
  4. Order removed from active list

Expiration​

Orders can expire if order-life is configured:

  1. Expiration Check: Periodic check for expired orders
  2. Auto-Refund: Escrow refunded if enabled
  3. Status Update: Order marked appropriately
  4. Cleanup: Expired orders with no uncollected items are deleted

Concurrent Operations​

The plugin handles concurrent operations safely:

  • Multiple Deliveries: Multiple players can deliver simultaneously
  • Optimistic Locking: Prevents over-delivery
  • Transaction Safety: Database transactions ensure consistency

Best Practices​

  1. Monitor Order Status: Use /orders myorders to track your orders
  2. Collect Promptly: Collect items soon after delivery
  3. Cancel Early: Cancel orders before deliveries if needed
  4. Check Expiration: Be aware of order expiration times