> For the complete documentation index, see [llms.txt](https://pixiedia.gitbook.io/maginium/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://pixiedia.gitbook.io/maginium/commerce-modules/order-module.md).

# Order Module

The **Order Module** in Maginium provides a comprehensive solution for managing customer orders. This module ensures seamless integration with other components of the platform, allowing businesses to process, track, and manage orders efficiently. Below is an in-depth guide to the features, workflows, and technical aspects of the Order Module.

***

### Overview

The Order Module allows businesses to:

* **Create and Manage Orders:** Handle the entire lifecycle of an order from creation to completion.
* **Track Order Status:** Provide real-time updates on order statuses.
* **Manage Payment Integration:** Ensure smooth processing of payments.
* **Enable Order Modifications:** Support updates and changes to orders after placement.

***

### Features

#### 1. **Order Lifecycle Management**

The module supports the complete lifecycle of an order:

* **Order Placement:** Customers can place orders through various sales channels.
* **Order Processing:** Automate order validation, inventory checks, and preparation.
* **Order Fulfillment:** Seamless integration with the Fulfillment Module for shipping and delivery.
* **Order Completion:** Mark orders as completed once delivered.

#### 2. **Order Status Tracking**

Each order has a dedicated status tracker to reflect its current state:

* Pending
* Processed
* Shipped
* Delivered
* Cancelled

#### 3. **Payment Integration**

Support for multiple payment gateways:

* Credit/Debit Cards
* PayPal
* Bank Transfers
* Digital Wallets

**Important:** Maginium uses secure payment protocols to ensure all transactions are encrypted and compliant with PCI DSS standards.

#### 4. **Order Modifications**

Allow modifications to orders post-placement:

* **Edit Quantities**
* **Change Shipping Address**
* **Apply Discounts**
* **Cancel Orders**

**Note:** Certain changes might be restricted once the order reaches the fulfillment stage.

***

### Database Schema

The Order Module uses the following key tables:

#### 1. `orders`

| Column         | Type      | Description                              |
| -------------- | --------- | ---------------------------------------- |
| `id`           | UUID      | Unique identifier for the order.         |
| `customer_id`  | UUID      | Links to the customer placing the order. |
| `status`       | ENUM      | Current status of the order.             |
| `total_amount` | DECIMAL   | Total cost of the order.                 |
| `created_at`   | TIMESTAMP | Order creation timestamp.                |
| `updated_at`   | TIMESTAMP | Last update timestamp.                   |

#### 2. `order_items`

| Column       | Type    | Description                     |
| ------------ | ------- | ------------------------------- |
| `id`         | UUID    | Unique identifier for the item. |
| `order_id`   | UUID    | Links to the parent order.      |
| `product_id` | UUID    | Links to the purchased product. |
| `quantity`   | INTEGER | Quantity ordered.               |
| `price`      | DECIMAL | Price per unit.                 |

#### 3. `payments`

| Column           | Type   | Description                              |
| ---------------- | ------ | ---------------------------------------- |
| `id`             | UUID   | Unique identifier for the payment.       |
| `order_id`       | UUID   | Links to the associated order.           |
| `payment_method` | STRING | Payment method used.                     |
| `status`         | ENUM   | Payment status (Pending/Success/Failed). |
| `transaction_id` | STRING | External gateway transaction ID.         |

***

### APIs

#### 1. **Create Order**

**Endpoint:** `POST /api/orders`

**Payload:**

```json
{
  "customer_id": "12345",
  "items": [
    { "product_id": "67890", "quantity": 2 },
    { "product_id": "54321", "quantity": 1 }
  ],
  "payment_method": "credit_card"
}
```

**Response:**

```json
{
  "order_id": "abcd-1234",
  "status": "pending",
  "total_amount": 150.75
}
```

#### 2. **Get Order Details**

**Endpoint:** `GET /api/orders/{id}`

**Response:**

```json
{
  "id": "abcd-1234",
  "customer_id": "12345",
  "status": "processed",
  "items": [
    { "product_id": "67890", "quantity": 2, "price": 50.25 },
    { "product_id": "54321", "quantity": 1, "price": 50.25 }
  ],
  "total_amount": 150.75
}
```

#### 3. **Update Order Status**

**Endpoint:** `PATCH /api/orders/{id}`

**Payload:**

````json
{
  "status": "shipped"
}

**Response:**
```json
{
  "message": "Order status updated successfully."
}
````

***

### Best Practices

1. **Validation:** Ensure that all inputs, especially customer and item details, are validated before processing orders.
2. **Asynchronous Order Processing:** Use queues for tasks like payment processing and inventory updates to improve performance.
3. **Security:** Always use HTTPS and secure tokens for API requests to protect sensitive data.

***