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 endpoint adds a product to the authenticated user’s Redis-backed cart. The caller is responsible for supplying the product’s display fields — name, price, and imageUrl — alongside the productId, since the cart service stores a snapshot of the item at add-time rather than looking it up from the catalog on every read. If a cart entry for the given productId already exists, its quantity is incremented by the supplied value rather than creating a duplicate entry.

​
Endpoint

POST /api/cart/items

​
Authentication

This endpoint requires a valid JWT passed as a Bearer token in the Authorization header. 
Authorization: Bearer <token>

​
Request

​
Request body

​
productId
string
required
The CUID of the product to add. Must match the id of a product in the catalog service.
​
name
string
required
The display name of the product. Stored in the cart for rendering without a catalog lookup.
​
price
number
required
The unit price of the product. Must be a positive number. Stored in the cart to enable total calculation.
​
imageUrl
string
required
A valid, fully qualified URL pointing to the product image. Validated as a URL by AddItemSchema.
​
quantity
number
The number of units to add. Must be a positive integer. Defaults to 1 if omitted.

​
Example request

curl -X POST http://localhost/api/cart/items \
  -H "Authorization: Bearer eyJhbGci..." \
  -H "Content-Type: application/json" \
  -d '{
    "productId": "clxxxxxxxxxxxxx",
    "name": "Wireless Headphones",
    "price": 79.99,
    "imageUrl": "https://example.com/headphones.jpg",
    "quantity": 1
  }'

​
Response

​
200 — Success

Returns the full updated items array for the user’s cart after the addition has been applied. 
{
  "success": true,
  "data": [
    {
      "productId": "clxxxxxxxxxxxxx",
      "name": "Wireless Headphones",
      "price": 79.99,
      "imageUrl": "https://example.com/headphones.jpg",
      "quantity": 1
    }
  ],
  "error": null
}
If the cart already contains an entry for the supplied productId, the service increments quantity on the existing entry rather than appending a new one. For example, if the item is already in the cart with quantity: 1 and you POST quantity: 2, the stored quantity becomes 3.

​
400 — Validation Error

Returned when the request body fails AddItemSchema validation — for example, if productId or name is missing, price is not a positive number, imageUrl is not a valid URL, or quantity is zero or negative. 
{
  "success": false,
  "data": null,
  "error": "..."
}

​
401 — Unauthorized

Returned when the Authorization header is missing or the JWT is invalid or expired. 
{
  "success": false,
  "data": null,
  "error": "Unauthorized"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us