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

# Create Order

> Creates an order directly without going through the cart flow

## Create a Direct Purchase Order

`POST /api/v1/orders`

Creates an order directly without going through the cart flow. This endpoint validates the items, processes payment from the specified wallet, and returns the created order.

### Authentication

Requires a Bearer token in the `Authorization` header.

### Idempotent Retries

If a request times out or your connection drops before you see the response, it's safe to
retry it as long as you send the same `Idempotency-Key` header both times. If an order was
already created for that key, the retry returns that same order instead of creating a
second one, so you won't be charged twice.

| Header            | Type   | Required    | Description                                                                                                                                   |
| ----------------- | ------ | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `Idempotency-Key` | string | Recommended | A key unique to this purchase attempt (a UUID or your own order reference works). Reusing the same key on a retry returns the original order. |

```
Idempotency-Key: 5f8d0d31-6f1a-4e2c-9d3b-2c7a1e9b4f10
```

Without this header, every request creates a new order, even if it's an exact duplicate of
one you just sent. That's unchanged from before, so existing integrations aren't affected
if you don't set it. We recommend adding it to any client that retries automatically.

### Request Body

| Field                        | Type          | Required | Description                             |
| ---------------------------- | ------------- | -------- | --------------------------------------- |
| `wallet_id`                  | string (UUID) | ✅        | The ID of the wallet to use for payment |
| `items`                      | array         | ✅        | Array of items to purchase              |
| `items[].product_variant_id` | integer       | ✅        | ID of the product variant               |
| `items[].quantity`           | integer       | ✅        | Quantity to purchase (minimum: 1)       |

### Example Request

```bash theme={null}
curl -X POST https://api.manastore.com/api/v1/orders \
  -H "Authorization: Bearer your-token-here" \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 5f8d0d31-6f1a-4e2c-9d3b-2c7a1e9b4f10" \
  -d '{
    "wallet_id": "123e4567-e89b-12d3-a456-426614174002",
    "items": [
      {
        "product_variant_id": 123,
        "quantity": 1
      }
    ]
  }'
```

### Responses

| Status                      | Description                                                                  |
| --------------------------- | ---------------------------------------------------------------------------- |
| `201 Created`               | Order created successfully                                                   |
| `401 Unauthorized`          | Missing or invalid authentication token                                      |
| `403 Forbidden`             | Access denied                                                                |
| `422 Unprocessable Entity`  | Validation error or business rule violation (e.g. insufficient wallet funds) |
| `500 Internal Server Error` | Unexpected server error                                                      |

### 201 — Order Created

```json theme={null}
{
  "message": "Order created successfully",
  "data": {
    "id": 12345,
    "ulid": "01J9Z3NDEKTSV4RRFFQ69G5FAV",
    "order_number": "#ORD-12345",
    "fulfillment_status": "pending",
    "payment_status": "completed",
    "subtotal": { "amount": 99.99, "formatted": "€99.99" },
    "conversion_fees": { "amount": 2.5, "formatted": "€2.50" },
    "total": { "amount": 102.49, "formatted": "€102.49" },
    "currency": "EUR",
    "items": [
      {
        "id": 67890,
        "product_name": "Digital Game Key",
        "variant_name": "Standard Edition",
        "quantity": 1,
        "unit_price": { "amount": 99.99, "formatted": "€99.99" },
        "total_price": { "amount": 99.99, "formatted": "€99.99" },
        "created_at": "2023-01-01T12:00:00+00:00",
        "updated_at": "2023-01-01T12:00:00+00:00"
      }
    ],
    "created_at": "2023-01-01T12:00:00+00:00",
    "updated_at": "2023-01-01T12:00:00+00:00"
  }
}
```

### 422 — Validation / Business Rule Error

```json theme={null}
{
  "message": "Insufficient funds in wallet"
}
```

### 500 — Server Error

```json theme={null}
{
  "message": "An unexpected error occurred while processing your order."
}
```