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

# Create an order

> Create an order with customer, item, and delivery details.

Creates an order. Your API key needs the `orders:create` scope.

## Headers

<ParamField header="X-Api-Key" type="string" required>Your API key. You can use `Authorization: Api-Key your_key` instead.</ParamField>
<ParamField header="Content-Type" type="string" required>Use `application/json`.</ParamField>

## Request body

<ParamField body="customerName" type="string" required>Customer name. Cannot be blank.</ParamField>
<ParamField body="customerPhone" type="string" required>Customer phone number.</ParamField>
<ParamField body="note" type="string">Order note.</ParamField>

<ParamField body="items" type="object[]" required>
  One or more order items.

  <Expandable title="Item fields">
    <ParamField body="productId" type="string" required>Product GUID.</ParamField>
    <ParamField body="combinationId" type="string">Product combination GUID, when applicable.</ParamField>
    <ParamField body="quantity" type="number" default="1" required>Quantity greater than zero.</ParamField>
  </Expandable>
</ParamField>

<ParamField body="address" type="object">
  Delivery address.

  <Expandable title="Address fields">
    <ParamField body="lineOne" type="string">First address line.</ParamField>
    <ParamField body="lineTwo" type="string">Second address line.</ParamField>
    <ParamField body="city" type="string">City.</ParamField>
    <ParamField body="state" type="string">State or province.</ParamField>
    <ParamField body="country" type="string">Country.</ParamField>
    <ParamField body="zipCode" type="string">Postal code.</ParamField>
    <ParamField body="phone" type="string">Delivery phone. Defaults to `customerPhone`.</ParamField>
    <ParamField body="latitude" type="number">Delivery latitude.</ParamField>
    <ParamField body="longitude" type="number">Delivery longitude.</ParamField>
  </Expandable>
</ParamField>

The delivery phone, or `customerPhone` when no delivery phone is supplied, must be valid.

## Request example

```bash theme={null}
curl --request POST "$MORABAA_API_URL/external/v1/orders" \
  --header "X-Api-Key: $MORABAA_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "customerName": "Ahmed Ali",
    "customerPhone": "+9647700000000",
    "note": "Leave at reception",
    "items": [{
      "productId": "11111111-1111-1111-1111-111111111111",
      "combinationId": null,
      "quantity": 2
    }],
    "address": {
      "lineOne": "Street 1",
      "city": "Baghdad",
      "country": "Iraq"
    }
  }'
```

## Response

A successful request returns `201 Created`. The `Location` header contains the new order URL.

<ResponseField name="id" type="UUID" required>Order ID.</ResponseField>
<ResponseField name="orderNumber" type="string" required>Order number.</ResponseField>
<ResponseField name="status" type="string" required>Current order status.</ResponseField>
<ResponseField name="total" type="number" required>Order subtotal.</ResponseField>
<ResponseField name="finalTotal" type="number" required>Final order total.</ResponseField>
<ResponseField name="productsCount" type="integer" required>Total item quantity.</ResponseField>
<ResponseField name="date" type="string" required>Order date and time in ISO 8601 format.</ResponseField>
<ResponseField name="customerName" type="string" required>Customer name.</ResponseField>
<ResponseField name="customerPhone" type="string | null">Customer phone.</ResponseField>
<ResponseField name="note" type="string | null">Order note.</ResponseField>

```json theme={null}
{
  "id": "55555555-5555-5555-5555-555555555555",
  "orderNumber": "ORD-1042",
  "status": "Pending",
  "total": 20000,
  "finalTotal": 20000,
  "productsCount": 2,
  "date": "2026-08-16T10:30:00+03:00",
  "customerName": "Ahmed Ali",
  "customerPhone": "+9647700000000",
  "note": "Leave at reception"
}
```

## Errors

| Status | Error code                | Cause                                                            |
| ------ | ------------------------- | ---------------------------------------------------------------- |
| `400`  | `customer_name_required`  | `customerName` is blank.                                         |
| `400`  | `items_required`          | `items` is empty or missing.                                     |
| `400`  | `invalid_item`            | An item has an invalid `productId`.                              |
| `400`  | `invalid_quantity`        | An item quantity is not greater than zero.                       |
| `400`  | `invalid_phone_number`    | The delivery phone is invalid.                                   |
| `400`  | `order_creation_failed`   | The order could not be created. The message contains the reason. |
| `401`  | —                         | The API key is missing or invalid.                               |
| `403`  | —                         | The key lacks the `orders:create` scope.                         |
| `429`  | —                         | The rate limit was exceeded.                                     |
| `500`  | —                         | An unexpected error occurred.                                    |
| `503`  | `store_under_maintenance` | The store is under maintenance.                                  |