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

# Orders

> Create orders at checkout

## `shop.checkout.createOrder(params)`

Places an order. Call this when the customer confirms checkout.

```typescript theme={null}
const order = await shop.checkout.createOrder({
  customer_name: 'John Doe',
  customer_email: 'john@example.com',
  customer_phone: '+94771234567',
  items: [
    {
      product_id: 'uuid-here',
      name: 'Red Cotton T-Shirt',
      price: 2500,
      quantity: 2,
      image: 'https://...',
      variant: 'Size: L',
    },
  ],
  shipping_address: {
    line1: '42 Galle Road',
    city: 'Colombo',
    country: 'LK',
  },
  payment_method: 'cod',
});

console.log(order.order_number); // e.g. "ORD-M3X9K-AB12"
```

### Parameters

| Param              | Type         | Required | Description                         |
| ------------------ | ------------ | -------- | ----------------------------------- |
| `customer_name`    | `string`     | ✅        | Full name                           |
| `customer_email`   | `string`     | ✅        | Email address                       |
| `customer_phone`   | `string`     | ❌        | Phone number                        |
| `items`            | `CartItem[]` | ✅        | At least one item required          |
| `shipping_address` | `object`     | ❌        | Delivery address                    |
| `shipping_method`  | `string`     | ❌        | Selected shipping method            |
| `payment_method`   | `string`     | ❌        | Default: `'cod'`                    |
| `notes`            | `string`     | ❌        | Order notes from customer           |
| `promo_code_id`    | `string`     | ❌        | ID from `validatePromo` result      |
| `discount_amount`  | `number`     | ❌        | Discount value from `validatePromo` |

### CartItem type

```typescript theme={null}
{
  product_id: string;  // UUID
  name: string;        // product name at time of purchase
  price: number;       // unit price
  quantity: number;
  image?: string;      // image URL
  variant?: string;    // e.g. "Color: Red, Size: L"
}
```

### Response

```typescript theme={null}
{
  id: string;
  order_number: string;  // human-readable, e.g. "ORD-M3X9K-AB12"
  total: number;
  status: string;        // "pending"
  created_at: string;
}
```

### Example — Full checkout flow

```typescript theme={null}
import { Shopi, ShopiError } from '@shopi-lk/storefront-sdk';

const shop = new Shopi({ apiKey: process.env.SHOPI_API_KEY! });

async function placeOrder(cart: CartItem[], formData: CheckoutForm) {
  // 1. Optionally validate promo first
  let promoResult = null;
  if (formData.promoCode) {
    promoResult = await shop.checkout.validatePromo({
      code: formData.promoCode,
      cart_items: cart,
      subtotal: cart.reduce((s, i) => s + i.price * i.quantity, 0),
    });
  }

  // 2. Place the order
  try {
    const order = await shop.checkout.createOrder({
      customer_name: formData.name,
      customer_email: formData.email,
      customer_phone: formData.phone,
      items: cart,
      shipping_address: formData.address,
      payment_method: formData.paymentMethod,
      notes: formData.notes,
      promo_code_id: promoResult?.valid ? promoResult.promo_code?.id : undefined,
      discount_amount: promoResult?.valid ? promoResult.discount_amount : undefined,
    });

    // 3. Redirect to confirmation
    window.location.href = `/order-confirmed?ref=${order.order_number}`;
  } catch (error) {
    if (error instanceof ShopiError) {
      showError(`Order failed: ${error.message}`);
    }
  }
}
```

<Note>
  Always snapshot the product `name` and `price` at checkout time into the `items` array. Do not rely on re-fetching prices at order creation — prices may change.
</Note>