Introduction

🎯 What does this module do?

The Orders module lets you create, manage, and track customer orders - from shopping cart checkout to payment processing and order fulfillment - handling the complete e-commerce order lifecycle.

Think of it as your order management system - customers add items to cart, place orders, make payments, and you track everything from order creation to delivery, all within OneEntry.

---

📖 Simple Explanation

Every e-commerce application needs order management:

• 🛒 Shopping Cart - Users add products, proceed to checkout
• 📋 Order Creation - Convert cart to order with customer details
• 💳 Payment Processing - Accept payments (credit card, PayPal, etc.)
• 📦 Order Tracking - Track status (pending, processing, shipped, delivered)
• 📊 Order Management - View all orders, filter by status, search
• 🧾 Order Details - View line items, totals, customer info

The problem with manual order management:

// ❌ Bad - Manual tracking
const orders = {
  order1: { items: [...], total: 99.99, status: 'pending' },
  order2: { items: [...], total: 149.99, status: 'shipped' }
};
// No payment processing, no proper tracking, no status updates

Issues:

• 🔒 No payment integration - Manual payment tracking
• 📊 Poor tracking - Hard to find orders, filter by status
• 🔄 No automation - Manual status updates, no notifications
• 💸 No tax/shipping calculation - Calculate manually

The Orders solution:

// ✅ Good - Automated order management
const order = await Orders.createOrder({
  items: cart.items,
  customer: userInfo,
  shippingAddress: address,
  paymentMethod: 'card'
});

// Order automatically:
// - Calculates totals, tax, shipping
// - Creates order record
// - Processes payment
// - Sends confirmation email
// - Tracks status

Benefits:

• 🔒 Integrated payments - Stripe, PayPal, other gateways
• 📊 Advanced tracking - Filter, search, export orders
• 🔄 Automated workflows - Status updates, notifications
• 💸 Auto-calculations - Tax, shipping, discounts

---

✨ Key Concepts

What is an Order?

An Order is a customer purchase transaction containing:

• Order Items - Products/services being purchased (quantity, price)
• Customer Information - Name, email, phone
• Shipping Address - Delivery location
• Billing Address - Payment billing info
• Payment Details - Payment method, transaction ID
• Order Totals - Subtotal, tax, shipping, total
• Order Status - Current state (pending, processing, completed)
• Timestamps - Created, updated, completed dates

Order Structure

Each order has this structure:

{
  id: "ORD-2024-001",                    // Unique order ID
  orderNumber: "1001",                   // Human-readable number
  status: "processing",                  // Order status
  customer: {
    name: "John Doe",
    email: "john@example.com",
    phone: "+1-555-0123"
  },
  items: [                               // Order line items
    {
      productId: 123,
      name: "Laptop",
      quantity: 1,
      price: 999.99,
      subtotal: 999.99
    },
    {
      productId: 456,
      name: "Mouse",
      quantity: 2,
      price: 29.99,
      subtotal: 59.98
    }
  ],
  shippingAddress: {
    street: "123 Main St",
    city: "New York",
    state: "NY",
    zip: "10001",
    country: "USA"
  },
  totals: {
    subtotal: 1059.97,
    tax: 84.80,
    shipping: 15.00,
    discount: 0,
    total: 1159.77
  },
  payment: {
    method: "credit_card",
    status: "paid",
    transactionId: "ch_abc123",
    paidAt: "2024-01-15T10:30:00Z"
  },
  createdAt: "2024-01-15T10:25:00Z",
  updatedAt: "2024-01-15T10:30:00Z"
}

Order Lifecycle

1. Customer adds items to cart
   ↓
2. Proceeds to checkout
   ↓
3. Enters shipping/billing info
   ↓
4. Selects payment method
   ↓
5. Order created (status: pending)
   ↓
6. Payment processed (status: processing)
   ↓
7. Order confirmed (status: confirmed)
   ↓
8. Items prepared (status: processing)
   ↓
9. Order shipped (status: shipped)
   ↓
10. Order delivered (status: completed)

Order Statuses

Status	Meaning	When to Use
pending	Order created, awaiting payment	Just placed, payment not processed
processing	Payment received, preparing items	Payment confirmed, packing items
confirmed	Order confirmed, ready to ship	Payment cleared, order verified
shipped	Order dispatched to customer	Package sent via carrier
delivered	Order received by customer	Delivery confirmed
completed	Order finished, no action needed	Transaction complete
cancelled	Order cancelled	Customer/admin cancelled
refunded	Payment returned to customer	Refund processed
failed	Payment or processing failed	Payment declined

Common Order Operations

Operation	Description	Example Use Case
Create Order	Convert cart to order	Checkout button clicked
Get Orders	List all orders (paginated)	Admin dashboard
Get Order by ID	Fetch specific order	View order details
Update Status	Change order status	Mark as shipped
Process Payment	Handle payment transaction	Charge credit card
Calculate Totals	Compute tax, shipping, total	Checkout summary
Cancel Order	Cancel pending order	Customer requests cancellation
Refund Order	Return payment to customer	Product return

Why Use Orders Module?

Benefit	Description
Automated Order Management	No manual tracking, everything automated
Payment Integration	Stripe, PayPal, other gateways built-in
Status Tracking	Real-time order status updates
Customer Notifications	Auto-send order confirmations, shipping updates
Inventory Management	Auto-deduct stock on order
Analytics & Reporting	Sales reports, revenue tracking
Security	PCI-compliant payment processing

---

📋 What You Need to Know

1. Orders are Created from Cart Data

You need to provide:

1. Customer information - Name, email, phone
2. Order items - Products, quantities, prices
3. Shipping address - Delivery location
4. Payment method - How customer will pay

const orderData = {
  customer: { name, email, phone },
  items: cartItems,
  shippingAddress: address,
  paymentMethod: 'credit_card'
};

const order = await Orders.createOrder(orderData);

2. Order Status Management

Track order progress through statuses:

// Update order status
await Orders.updateOrderStatus(orderId, 'shipped');

// Get orders by status
const processingOrders = await Orders.getOrders({
  status: 'processing'
});

Common status flows:

• Digital products: pending → processing → completed
• Physical products: pending → processing → shipped → delivered → completed
• Cancelled: any status → cancelled
• Refunded: completed → refunded

3. Payment Processing

Orders integrate with payment gateways:

// Process payment
const payment = await Orders.processPayment(orderId, {
  method: 'credit_card',
  cardToken: 'tok_from_stripe',
  amount: orderTotal
});

// Check payment status
if (payment.status === 'succeeded') {
  await Orders.updateOrderStatus(orderId, 'processing');
}

Supported payment methods:

• Credit/Debit cards (via Stripe, PayPal)
• PayPal
• Bank transfer
• Cash on delivery
• Custom payment gateways

4. Order Totals Calculation

OneEntry automatically calculates:

{
  subtotal: 1059.97,      // Sum of all items
  tax: 84.80,             // Tax based on location
  shipping: 15.00,        // Shipping cost
  discount: 0,            // Applied discounts/coupons
  total: 1159.77          // Final amount to charge
}

Formula: total = subtotal + tax + shipping - discount

---

📊 Quick Reference Table

Method	Description	Returns	Use Case
createOrder()	Create new order	Promise<Order>	Checkout process
getOrders()	Get all orders (paginated)	Promise<{ items: Order[], total }>	Admin dashboard
getOrderById()	Get specific order	Promise<Order>	View order details
updateOrderStatus()	Update order status	Promise<Order>	Mark as shipped
processPayment()	Process payment transaction	Promise<Payment>	Charge customer
cancelOrder()	Cancel order	Promise<Order>	Customer cancellation
refundOrder()	Refund order payment	Promise<Refund>	Product return

Order Structure:

interface Order {
  id: string;
  orderNumber: string;
  status: OrderStatus;
  customer: {
    name: string;
    email: string;
    phone: string;
  };
  items: OrderItem[];
  shippingAddress: Address;
  billingAddress: Address;
  totals: {
    subtotal: number;
    tax: number;
    shipping: number;
    discount: number;
    total: number;
  };
  payment: {
    method: string;
    status: string;
    transactionId: string;
    paidAt: string;
  };
  createdAt: string;
  updatedAt: string;
}

---

💡 Important Notes

⚠️ Orders are Created in OneEntry

The Orders module handles the complete order lifecycle:

• ✅ Create orders from cart data
• ✅ Process payments
• ✅ Update order status
• ✅ Track shipping
• ❌ Does NOT handle shopping cart UI (you build that)

Your responsibility:

• Build shopping cart interface
• Collect customer information
• Display order confirmation

💳 Payment Processing

Orders integrate with payment gateways:

• Stripe (recommended)
• PayPal
• Custom gateways via IntegrationCollections

Important:

• Never store credit card details directly
• Use tokenization (Stripe.js, PayPal SDK)
• OneEntry handles secure payment processing

📦 Inventory Management

Orders automatically:

• ✅ Deduct inventory on order creation
• ✅ Restore inventory on cancellation
• ✅ Track stock levels

Best practice: Check stock before creating order

🔒 Security

Orders contain sensitive data:

• 🔒 Customer personal information
• 🔒 Payment details
• 🔒 Shipping addresses

Always:

• Use HTTPS for checkout pages
• Validate data before creating orders
• Implement proper authentication
• Follow PCI DSS compliance for payments

---

🎓 Best Practices

✅ DO:

1. Validate cart before creating order - Check stock availability
2. Calculate totals on server - Never trust client-side calculations
3. Send order confirmations - Email customers after order placed
4. Track order status - Update status as order progresses
5. Handle payment failures - Retry logic, clear error messages
6. Implement order search - Let customers find their orders easily
7. Store order history - Keep records for customer service
8. Use pagination - Don't load all orders at once

---

❌ DON'T:

1. Don't create orders without payment - Verify payment first
2. Don't expose payment details - Use tokenization
3. Don't skip validation - Always validate customer data
4. Don't forget notifications - Send order status updates
5. Don't ignore inventory - Check stock before order
6. Don't hardcode tax rates - Use location-based calculation
7. Don't forget error handling - Handle payment failures gracefully
8. Don't skip order confirmation - Always show order summary

---

Definition of the Orders module

The Orders module manages the creation and payment of goods or services.

The ability to make and pay for goods or services is an integral part of the E-commerce application. In this section, you can familiarize yourself with the principles of working with orders.

More information about the module's user interface https://doc.oneentry.cloud/docs/category/orders

const { Orders } = defineOneEntry(
  "your-project-url", {
    "token": "your-app-token"
  }
);

---

🔗 Related Documentation

• Products Module - Manage products available for purchase
• Users Module - Manage customers who place orders
• IntegrationCollections Module - Payment gateway integrations
• Events Module - Order status notifications

---