---
title: "Create a new order"
method: POST
path: "/orders"
tags: ["orders"]
---

# Create a new order

`POST /orders`

Places a new order with pizzas (requires userId).

Order limits:
- Maximum 50 pizzas per order
- Maximum 5 active orders per user

The estimated completion time is as follows:
- 3-5 minutes for 1-2 pizzas, plus 1 minute for each additional pizza.

Order statuses are updated automatically:
- Orders move from 'pending' to 'in-preparation' 1-3 minutes after creation.
- Orders move from 'in-preparation' to 'completed' 2-3 minutes around their estimated completion time.

## Request body

- CreateOrderRequest
  - `userId` string, required
  - `nickname` string — Optional nickname for the order that will be displayed instead of order ID (first 8 characters will be shown)
  - `items` object[], required
    - `pizzaId` string, required
    - `quantity` integer, required
    - `extraToppingIds` string[] — Optional list of extra topping IDs to add to the pizza

## Response `201`

Order created successfully

- OrderResponse — Order object returned by the API (userId is omitted for privacy)
  - `id` string, required
  - `createdAt` string, date-time, required
  - `items` OrderItem[], required
    - `pizzaId` string, required
    - `quantity` integer, required — Must be a positive integer (greater than 0). Orders with zero or negative quantity will be rejected with a 400 error.
    - `extraToppingIds` string[] — Optional list of extra topping IDs to add to the pizza
  - `estimatedCompletionAt` string, date-time, required
  - `completedAt` string, date-time — ISO date string for when the order was completed (undefined until completed)
  - `totalPrice` number, float, required
  - `status` 'pending' | 'in-preparation' | 'ready' | 'completed' | 'cancelled', required — - pending: Order has been created but not yet started - in-preparation: Order is being prepared - ready: Order is ready for pickup - completed: Order has been picked up - cancelled: Order has been cancelled

## Other responses

- `400` — Invalid request (e.g., missing required fields, invalid pizza/topping IDs, invalid quantities, or order exceeds 50 pizzas limit)
- `401` — User is not registered
- `429` — Too many active orders for this user
- `500` — Internal server error

## Changes

- **2026-07-17** `b9618c89d438` — 1 info
  - added the new optional request property `nickname`
- **2025-07-18** `63514a68987d` — 1 warning
  - removed the request property `nickname`

[Change history](https://skmtc.dev/azure/apis/pizza-api/changes/orders/post.md)

---

[API](https://skmtc.dev/azure/apis/pizza-api.md) · [All operations](https://skmtc.dev/azure/apis/pizza-api/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/azure/pizza-api/revisions/b9618c89d438/schema)