Skip to main content

Documentation Index

Fetch the complete documentation index at: https://mintlify.com/astrxnomo/shop-microservers/llms.txt

Use this file to discover all available pages before exploring further.

This is the core checkout endpoint that orchestrates multiple internal services to convert the authenticated user’s cart into a persisted order. It communicates with both the cart service (to read and then clear the cart) and the catalog service (to decrement stock for each purchased product), then writes the resulting order and its snapshotted line items to the orders database. No request body is required — the entire order is built from the contents of the user’s cart in Redis.

​
Endpoint

POST /api/orders/

​
Authentication

A valid JWT is required. The token is forwarded internally to the cart service so it can identify and subsequently clear the correct user’s cart. 
Authorization: Bearer <token>

​
Request Body

None. The order contents are sourced entirely from the user’s active cart. Send the request with only the Authorization header.

​
Internal Checkout Flow

The service executes the following steps on every successful checkout request:
1

Fetch the cart

The orders service calls GET /api/cart/ on the cart service, forwarding the user’s JWT. This returns the full cart including all items and the pre-computed total.
2

Validate the cart is not empty

If the cart contains no items, the request is rejected immediately with a 400 Bad Request before any stock or database operations are attempted.
3

Decrement stock for each item

For every item in the cart, the orders service calls PATCH /products/:id/stock on the catalog service with { "decrement": quantity } to reduce the available inventory by the purchased quantity.
4

Persist the order and line items

A new Order record is created in orders_db with the cart’s total and a status of PENDING. Each cart item is saved as an OrderItem with the product ID, name, price, and quantity snapshotted at this moment.
5

Clear the cart

The orders service calls DELETE /api/cart/ on the cart service, passing the JWT, to empty the user’s cart.
6

Return the new order

The newly created Order, including all OrderItem records, is returned in the response with HTTP 201 Created.

​
Example Request

curl -X POST http://localhost/api/orders/ \
  -H "Authorization: Bearer eyJhbGci..."

​
Response

​
201 — Created

Returns the newly created Order object with all snapshotted line items. 
{
  "success": true,
  "data": {
    "id": "clxxxxxxxxxxxxx",
    "userId": "clyyyyyyyyyyyyyy",
    "total": 159.98,
    "status": "PENDING",
    "createdAt": "2024-01-15T12:00:00.000Z",
    "updatedAt": "2024-01-15T12:00:00.000Z",
    "items": [
      {
        "id": "clzzzzzzzzzzzzz",
        "orderId": "clxxxxxxxxxxxxx",
        "productId": "claaaaaaaaaaaa",
        "name": "Wireless Headphones",
        "price": 79.99,
        "quantity": 2
      }
    ]
  },
  "error": null
}
​
data.id
string
CUID of the newly created order.
​
data.status
string
Always PENDING at creation. The order status is managed separately after checkout.
​
data.total
number
Total order amount carried over from the cart total at the moment of checkout.
​
data.items
array
Snapshot of all cart items at the time of checkout. Each item records the productId, name, price, and quantity as they were when the order was placed.

​
400 — Bad Request

Returned when the authenticated user’s cart is empty. No stock decrements or database writes are performed.

​
401 — Unauthorized

Returned when the Authorization header is missing or the JWT is invalid or expired.
Order items snapshot the product name and price at the time of checkout. Subsequent changes to catalog pricing or product names do not affect existing orders.
This is a reference implementation without full distributed transaction support. If stock decrement succeeds for one or more items but the order creation step fails, those inventory decrements are not automatically rolled back. Production deployments should introduce a saga or compensating transactions to handle partial failures.

Build docs developers (and LLMs) love

Get started for freeTalk to us