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

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:

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: 179,
  storageId: 1,
  createdDate: '2025-07-03T00:43:02.908Z',
  statusIdentifier: 'inProgress',
  formIdentifier: 'orderForm',
  formData: [
    {
      marker: 'order_name',
      type: 'string',
      value: 'Ivan'
    }
  ],
  attributeSetIdentifier: 'order_form',
  totalSum: '300.00',
  currency: 'USD',
  paymentAccountIdentifier: 'cash',
  paymentAccountLocalizeInfos: { title: 'Cash' },
  products: [
    {
      id: 2957,
      title: 'Cosmo',
      sku: null,
      previewImage: null,
      price: 150,
      quantity: 2,
    },
  ],
  isCompleted: true,
}

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 examples

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
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

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

Order Status Management

Track order progress through statuses:

Common status flows:

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

Payment Processing

Orders integrate with payment gateways

---

💡 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

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

---

📊 Quick Reference Table

Method	Description
createOrder()	Create new order
getAllOrdersByMarker()	Get all orders (paginated)
getOrderByMarker()	Get one order storage object by marker.
getAllOrdersStorage()	Getting all order storage objects.
getOrderByMarkerAndId()	Getting one order by marker and id from the order storage object created by the user.
updateOrderByMarkerAndId()	Update one order by marker and id from the order storage object created by the user.

❓ Common Questions (FAQ)

How do I create an order with multiple products?

Pass an array of product objects in the order data. Each product should include id, quantity, and price. The total sum is calculated automatically based on product quantities and prices.

---

Can I update an order after it's been created?

Yes, use updateOrderByMarkerAndId() to modify order details like status, shipping address, or order data. However, once payment is processed, be cautious when modifying order items or totals.

---

How do I track order status changes?

Use the statusIdentifier field to track current order state. You can also set up webhooks or use the Events module to receive notifications when order status changes.

---

What's the difference between order storage and individual orders?

Order storage is a container that groups related orders (like orders from a specific form or sales channel). Individual orders are the actual purchase transactions within that storage. Use markers to identify and organize different order storages.

---

How do I handle order cancellations and refunds?

Update the order status to 'cancelled' using updateOrderByMarkerAndId(). For refunds, use the Payments module to process the refund transaction, then update the order status to 'refunded'.

---

Can I retrieve a customer's order history?

Yes, use getAllOrdersByMarker() with appropriate filters to fetch all orders for a specific customer. You can filter by user ID, date range, or other criteria.

---

🎓 Best Practices

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

---

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

---

Definition of the Orders module

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

---