Skip to main content

API: Order Management

Methods for creating, retrieving, and managing orders.

Creating Orders​

createOrder​

Create a new order programmatically.

Signature:

CompletableFuture<Order> createOrder(
    UUID playerUuid,
    String playerName,
    List<OrderItem> items
)

Parameters:

  • playerUuid - UUID of the player creating the order
  • playerName - Name of the player (for display)
  • items - List of order items (typically one item per order)

Returns: CompletableFuture<Order> - The created order, or null if creation failed

Example:

// Create order item
OrderItem item = new OrderItem(Material.DIAMOND, 64, 100.0);

// Create order
CompletableFuture<Order> future = ordersAPI.createOrder(
    player.getUniqueId(),
    player.getName(),
    Collections.singletonList(item)
);

future.thenAccept(order -> {
    if (order != null) {
        player.sendMessage("Order #" + order.getId() + " created!");
    } else {
        player.sendMessage("Failed to create order!");
    }
});

Notes:

  • Order creation is subject to all normal restrictions (limits, cooldowns, blacklist)
  • Payment is handled automatically (escrow system)
  • Order expiration is set based on configuration

Retrieving Orders​

getOrder​

Get an order by ID.

Signature:

CompletableFuture<Order> getOrder(int orderId)

Parameters:

  • orderId - The order ID

Returns: CompletableFuture<Order> - The order, or null if not found

Example:

CompletableFuture<Order> future = ordersAPI.getOrder(1);

future.thenAccept(order -> {
    if (order != null) {
        getLogger().info("Order #" + order.getId() + 
            " by " + order.getPlayerName());
    }
});

getActiveOrders​

Get all active orders (PENDING or IN_PROGRESS).

Signature:

CompletableFuture<List<Order>> getActiveOrders()

Returns: CompletableFuture<List<Order>> - List of active orders

Example:

CompletableFuture<List<Order>> future = ordersAPI.getActiveOrders();

future.thenAccept(orders -> {
    getLogger().info("Found " + orders.size() + " active orders");
    
    for (Order order : orders) {
        getLogger().info("Order #" + order.getId() + 
            ": " + order.getItems().get(0).getMaterial());
    }
});

getOrdersByPlayer​

Get all orders created by a specific player.

Signature:

CompletableFuture<List<Order>> getOrdersByPlayer(UUID playerUuid)

Parameters:

  • playerUuid - UUID of the player

Returns: CompletableFuture<List<Order>> - List of player's orders

Example:

CompletableFuture<List<Order>> future = ordersAPI.getOrdersByPlayer(
    player.getUniqueId()
);

future.thenAccept(orders -> {
    long activeCount = orders.stream()
        .filter(o -> o.getStatus() == OrderStatus.PENDING || 
                    o.getStatus() == OrderStatus.IN_PROGRESS)
        .count();
    
    player.sendMessage("You have " + activeCount + " active orders");
});

getOrdersByStatus​

Get all orders with a specific status.

Signature:

CompletableFuture<List<Order>> getOrdersByStatus(OrderStatus status)

Parameters:

  • status - The order status to filter by

Returns: CompletableFuture<List<Order>> - List of orders with that status

Example:

CompletableFuture<List<Order>> future = ordersAPI.getOrdersByStatus(
    OrderStatus.PENDING
);

future.thenAccept(orders -> {
    getLogger().info("Found " + orders.size() + " pending orders");
});

Cancelling Orders​

cancelOrder​

Cancel an order (only if owned by the player).

Signature:

CompletableFuture<Boolean> cancelOrder(int orderId, UUID playerUuid)

Parameters:

  • orderId - The order ID to cancel
  • playerUuid - UUID of the player attempting to cancel

Returns: CompletableFuture<Boolean> - true if cancelled successfully

Example:

CompletableFuture<Boolean> future = ordersAPI.cancelOrder(
    orderId,
    player.getUniqueId()
);

future.thenAccept(success -> {
    if (success) {
        player.sendMessage("Order cancelled!");
    } else {
        player.sendMessage("Failed to cancel order!");
    }
});

Notes:

  • Only order owner can cancel (unless admin)
  • Subject to cancellation restrictions (deliveries, time limits)
  • Auto-refund occurs if enabled

Deleting Orders​

deleteOrder​

Delete an order (admin function).

Signature:

CompletableFuture<Boolean> deleteOrder(int orderId)

Parameters:

  • orderId - The order ID to delete

Returns: CompletableFuture<Boolean> - true if deleted successfully

Example:

CompletableFuture<Boolean> future = ordersAPI.deleteOrder(orderId);

future.thenAccept(success -> {
    if (success) {
        getLogger().info("Order #" + orderId + " deleted");
    }
});

Warning: This action is irreversible! No refund is processed.

Order Model​

Order Class​

public class Order {
    int getId();
    UUID getPlayerUuid();
    String getPlayerName();
    OrderStatus getStatus();
    double getTotalPrice();
    double getEscrowBalance();
    double getPaidToDeliverers();
    int getPriority();
    LocalDateTime getCreatedAt();
    LocalDateTime getExpiresAt();
    LocalDateTime getCompletedAt();
    List<OrderItem> getItems();
    
    // Helper methods
    boolean isExpired();
    boolean isCompleted();
    boolean isCancelled();
    boolean allItemsDelivered();
    boolean allItemsCollected();
    boolean allItemsPaid();
}

OrderItem Class​

public class OrderItem {
    int getId();
    int getOrderId();
    Material getMaterial();
    int getAmount();
    double getPricePerItem();
    double getTotalPrice();
    int getDelivered();
    int getCollected();
    int getPaid();
    Map<String, Integer> getEnchantments();
    String getCustomItemId();
    
    // Helper methods
    boolean isFullyDelivered();
    boolean isFullyCollected();
    boolean isFullyPaid();
    int getRemainingToDeliver();
    int getRemainingToCollect();
    int getRemainingToPay();
}

OrderStatus Enum​

public enum OrderStatus {
    PENDING,
    IN_PROGRESS,
    DELIVERED,
    COMPLETED,
    CANCELLED
}

Best Practices​

  1. Handle Null Returns: Always check for null when getting orders
  2. Use CompletableFuture: Handle async operations properly
  3. Error Handling: Check return values for success/failure
  4. Validate Input: Validate order IDs and player UUIDs
  5. Respect Permissions: Don't bypass permission checks