Orders API: Place, Verify, and Track Food Delivery

The Orders API handles the full order lifecycle from placement through payment verification and status updates. Orders are created when a customer checks out, linked to a Stripe Checkout session, and tracked through three sequential statuses: Food Processing → Out for delivery → Delivered. The order document also carries a payment boolean that is set to true only after a successful Stripe payment callback.

POST /api/order/place

Places a new order for the authenticated user. The controller saves the order to MongoDB, clears the user’s cart, builds a Stripe Checkout session from the supplied items plus a fixed ₹2 delivery charge, and returns the hosted Stripe session URL. The client should redirect the user to that URL to complete payment.

The amount field is stored in MongoDB exactly as supplied. The controller independently adds a ₹2 delivery charge as a separate Stripe line item — you do not need to include it in amount. Typically the frontend sends the sum of (item.price × item.quantity) for all items.

Request Headers

token

string

required

A valid JWT token issued at login. userId is injected by the auth middleware.

Request Body

items

array

required

Array of cart items to order. Each element must include:

Show Item object

name

string

required

Name of the food item (used as the Stripe line item product name).

price

number

required

Price per unit in INR. Stripe receives this as price * 100 (paise).

quantity

number

required

Number of units ordered.

amount

number

required

Total order amount in INR. This value is stored as-is in MongoDB. The ₹2 delivery charge is added to the Stripe session separately and does not need to be included here.

address

object

required

Delivery address for the order.

Show Address object

firstName

string

required

Recipient’s first name.

lastName

string

required

Recipient’s last name.

string

required

Contact email address.

street

string

required

Street address line.

city

string

required

City name.

state

string

required

State or region.

zipcode

string

required

Postal / ZIP code.

country

string

required

Country name.

phone

string

required

Contact phone number.

Response

success

boolean

true when the order was created and the Stripe session was generated.

session_url

string

The full Stripe-hosted Checkout URL. Redirect the user here to complete payment (e.g., "https://checkout.stripe.com/c/pay/cs_test_...").

{
  "success": true,
  "session_url": "https://checkout.stripe.com/c/pay/cs_test_a1B2c3D4e5F6..."
}

Example

curl -X POST http://localhost:4000/api/order/place \
  -H "Content-Type: application/json" \
  -H "token: <your_jwt_token>" \
  -d '{
    "items": [
      { "name": "Caesar Salad", "price": 199, "quantity": 2 },
      { "name": "Garlic Bread",  "price": 89,  "quantity": 1 }
    ],
    "amount": 487,
    "address": {
      "firstName": "Rohan",
      "lastName": "Sharma",
      "email": "rohan@example.com",
      "street": "12 MG Road",
      "city": "Bengaluru",
      "state": "Karnataka",
      "zipcode": "560001",
      "country": "India",
      "phone": "9876543210"
    }
  }'

POST /api/order/verify

Called by the frontend after Stripe redirects back to the application. Stripe appends success=true or success=false plus the orderId to the redirect URL; the frontend extracts these and posts them here.

If success is "true" — the order’s payment field is set to true.
If success is "false" — the order document is permanently deleted from MongoDB.

Request Body

orderId

string

required

The MongoDB _id of the order to verify, returned by /api/order/place.

success

string

required

String "true" (payment succeeded) or "false" (payment cancelled or failed). Note this is a string, not a boolean, as it comes directly from the Stripe redirect query parameter.

Response

success

boolean

true when payment was confirmed; false when the order was not paid.

message

string

"Paid" on successful payment, "Not Paid" when payment failed or was cancelled.

{ "success": true, "message": "Paid" }

{ "success": false, "message": "Not Paid" }

Example

curl -X POST http://localhost:4000/api/order/verify \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "6641b5a2e4b0c123456789ff", "success": "true" }'

POST /api/order/userorders

Fetches all orders belonging to the authenticated user. Used by the “My Orders” page on the frontend to display order history and current status.

Request Headers

token

string

required

A valid JWT token. userId is injected by the auth middleware.

Request Body

Send an empty JSON object.

{}

Response

success

boolean

true when orders were fetched successfully.

data

array

Array of order documents for the authenticated user.

Show Order object

_id

string

MongoDB ObjectId of the order.

userId

string

ID of the user who placed the order.

items

array

Array of ordered items, each with name, price, and quantity.

amount

number

Total order amount in INR as submitted when the order was placed.

address

object

Delivery address object.

status

string

Current order status. One of "Food Processing", "Out for delivery", or "Delivered". Defaults to "Food Processing" on creation.

date

string

ISO 8601 timestamp when the order was created.

payment

boolean

true if Stripe payment was confirmed, false otherwise.

{
  "success": true,
  "data": [
    {
      "_id": "6641b5a2e4b0c123456789ff",
      "userId": "6640a1b2c3d4e5f678901234",
      "items": [
        { "name": "Caesar Salad", "price": 199, "quantity": 2 }
      ],
      "amount": 400,
      "address": {
        "firstName": "Rohan",
        "lastName": "Sharma",
        "email": "rohan@example.com",
        "street": "12 MG Road",
        "city": "Bengaluru",
        "state": "Karnataka",
        "zipcode": "560001",
        "country": "India",
        "phone": "9876543210"
      },
      "status": "Food Processing",
      "date": "2024-05-12T08:00:00.000Z",
      "payment": true
    }
  ]
}

Example

curl -X POST http://localhost:4000/api/order/userorders \
  -H "Content-Type: application/json" \
  -H "token: <your_jwt_token>" \
  -d '{}'

GET /api/order/list

Returns every order in the system, regardless of user. Intended for the admin panel to display and manage all incoming orders.

This endpoint has no authentication. It exposes all customer orders — including names, addresses, and phone numbers. Add admin authentication middleware before deploying to production.

Response

success

boolean

true when the order list was fetched successfully.

data

array

Array of all order documents across all users. Each object has the same fields as described in POST /api/order/userorders.

{
  "success": true,
  "data": [ /* all order objects */ ]
}

Example

curl -X GET http://localhost:4000/api/order/list

POST /api/order/status

Updates the status field of a specific order. Used by the admin panel to progress an order through the delivery pipeline.

This endpoint has no authentication. Any caller can change the status of any order. Restrict access to authenticated admin users before going to production.

Request Body

orderId

string

required

The MongoDB _id of the order to update.

status

string

required

The new status value. Should be one of:

"Food Processing" — order received, kitchen is preparing
"Out for delivery" — order dispatched to the customer
"Delivered" — order successfully delivered

Response

success

boolean

true when the status was updated successfully.

message

string

"Status Updated" on success, "Error" on failure.

{ "success": true, "message": "Status Updated" }

Example

curl -X POST http://localhost:4000/api/order/status \
  -H "Content-Type: application/json" \
  -d '{ "orderId": "6641b5a2e4b0c123456789ff", "status": "Out for delivery" }'

Order Status Lifecycle

Every order begins in the Food Processing state the moment it is created. An admin uses the /api/order/status endpoint to advance it through the pipeline. The three states flow in sequence:

Food Processing  ──▶  Out for delivery  ──▶  Delivered

Stage	Meaning
Food Processing	Default state. The kitchen has received the order and is preparing it.
Out for delivery	The order has been packed and dispatched to the delivery agent.
Delivered	The order has been successfully handed to the customer.

Status transitions are not enforced server-side — the API accepts any string value. Follow the three-stage sequence above in your admin UI to keep order tracking consistent.

Authentication

Endpoints

Orders API: Place, Verify, and Track Food Delivery

POST /api/order/place

Request Headers

Request Body

Response

Example

POST /api/order/verify

Request Body

Response

Example

POST /api/order/userorders

Request Headers

Request Body

Response

Example

GET /api/order/list

Response

Example

POST /api/order/status

Request Body

Response

Example

Order Status Lifecycle

Build docs developers (and LLMs) love

Authentication

Endpoints

Documentation Index

​POST /api/order/place

​Request Headers

​Request Body

​Response

​Example

​POST /api/order/verify

​Request Body

​Response

​Example

​POST /api/order/userorders

​Request Headers

​Request Body

​Response

​Example

​GET /api/order/list

​Response

​Example

​POST /api/order/status

​Request Body

​Response

​Example

​Order Status Lifecycle

Build docs developers (and LLMs) love

POST /api/order/place

Request Headers

Request Body

Response

Example

POST /api/order/verify

Request Body

Response

Example

POST /api/order/userorders

Request Headers

Request Body

Response

Example

GET /api/order/list

Response

Example

POST /api/order/status

Request Body

Response

Example

Order Status Lifecycle