> ## Documentation Index
> Fetch the complete documentation index at: https://twigz.arqqin.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Cart to Order Flow

> Complete guide to implementing the shopping cart to order process

# Cart to Order Flow

This guide walks you through implementing the complete shopping cart to order conversion process.

## Overview

The cart-to-order flow involves several steps:

1. Add items to cart
2. Validate cart contents
3. Calculate totals and fees
4. Process payment
5. Create order
6. Update inventory
7. Send notifications

## Step-by-Step Implementation

### 1. Add Items to Cart

```typescript theme={null}
// Add product to cart
const addToCart = async (productId: string, quantity: number) => {
  await convex.mutation(api.customers.cart.addToCart, {
    productId,
    quantity,
    customerId: "user_123"
  });
};
```

### 2. Validate Cart for Checkout

```typescript theme={null}
// Validate cart before checkout
const validation = await convex.query(api.customers.cartToOrder.validateCartForCheckout, {
  customerId: "user_123"
});

if (!validation.isValid) {
  console.error("Cart validation failed:", validation.errors);
  return;
}
```

### 3. Create Payment Intent

```typescript theme={null}
// Create Stripe payment intent
const paymentIntent = await convex.mutation(api.customers.payments.createPaymentIntent, {
  amount: validation.totalAmount,
  currency: "AED",
  customerId: "user_123"
});
```

### 4. Process Payment

```typescript theme={null}
// Use Stripe client to confirm payment
const { error } = await stripe.confirmPayment({
  clientSecret: paymentIntent.clientSecret,
  elements,
  confirmParams: {
    return_url: "https://yourapp.com/return"
  }
});
```

### 5. Create Order from Cart

```typescript theme={null}
// Convert cart to order after successful payment
const order = await convex.mutation(api.customers.cartToOrder.createOrderFromCart, {
  customerId: "user_123",
  paymentIntentId: paymentIntent.id,
  shippingAddress: {
    street: "123 Main St",
    city: "Dubai",
    emirate: "Dubai",
    postalCode: "12345"
  }
});
```

## Complete Flow Example

```typescript theme={null}
const completeCheckout = async () => {
  try {
    // 1. Validate cart
    const validation = await convex.query(api.customers.cartToOrder.validateCartForCheckout, {
      customerId: currentUser.id
    });

    if (!validation.isValid) {
      throw new Error(`Cart validation failed: ${validation.errors.join(", ")}`);
    }

    // 2. Create payment intent
    const paymentIntent = await convex.mutation(api.customers.payments.createPaymentIntent, {
      amount: validation.totalAmount,
      currency: "AED",
      customerId: currentUser.id
    });

    // 3. Process payment with Stripe
    const { error } = await stripe.confirmPayment({
      clientSecret: paymentIntent.clientSecret,
      elements,
      confirmParams: {
        return_url: `${window.location.origin}/checkout/success`
      }
    });

    if (error) {
      throw new Error(`Payment failed: ${error.message}`);
    }

    // 4. Create order
    const order = await convex.mutation(api.customers.cartToOrder.createOrderFromCart, {
      customerId: currentUser.id,
      paymentIntentId: paymentIntent.id,
      shippingAddress: shippingAddress
    });

    // 5. Clear cart
    await convex.mutation(api.customers.cart.clearCart, {
      customerId: currentUser.id
    });

    return order;
  } catch (error) {
    console.error("Checkout failed:", error);
    throw error;
  }
};
```

## Error Handling

### Common Validation Errors

* **Out of stock**: Product no longer available
* **Price changes**: Product price updated
* **Invalid quantities**: Quantity exceeds available stock
* **Store unavailable**: Store is not accepting orders

### Payment Errors

* **Insufficient funds**: Card declined
* **Invalid card**: Card details incorrect
* **Network error**: Payment processing failed

## Best Practices

1. **Always validate** cart before payment
2. **Handle errors gracefully** with user-friendly messages
3. **Clear cart** only after successful order creation
4. **Send confirmations** via email and push notifications
5. **Update inventory** immediately after order creation

<Note>
  The cart-to-order flow is designed to be atomic - either all steps succeed or none do, ensuring data consistency.
</Note>