marketplaces/docs/API_CHANGES_REQUIRED.md

# Backend API Changes Required

## Cart Quantity Support

### 1. Add Quantity to Cart Items

**Current GET /cart Response:**
```json
[
  {
    "itemID": 123,
    "name": "Product Name",
    "price": 100,
    "currency": "RUB",
    ...other item fields
  }
]
```

**NEW Required Response:**
```json
[
  {
    "itemID": 123,
    "name": "Product Name",
    "price": 100,
    "currency": "RUB",
    "quantity": 2,  // <-- ADD THIS FIELD
    ...other item fields
  }
]
```

### 2. POST /cart - Add Item to Cart

**Current Request:**
```json
{
  "itemID": 123
}
```

**NEW Request (with optional quantity):**
```json
{
  "itemID": 123,
  "quantity": 1  // Optional, defaults to 1 if not provided
}
```

**Behavior:**
- If item already exists in cart, **increment** the quantity by the provided amount
- If item doesn't exist, add it with the specified quantity

### 3. PATCH /cart - Update Item Quantity (NEW ENDPOINT)

**Request:**
```json
{
  "itemID": 123,
  "quantity": 5  // New quantity value (not increment, but absolute value)
}
```

**Response:**
```json
{
  "message": "Cart updated successfully"
}
```

**Behavior:**
- Set the quantity to the exact value provided
- If quantity is 0 or negative, remove the item from cart

### 4. Payment Endpoints - Include Quantity

**POST /payment/create**

Update the items array to include quantity:

**Current:**
```json
{
  "amount": 1000,
  "currency": "RUB",
  "items": [
    {
      "itemID": 123,
      "price": 500,
      "name": "Product Name"
    }
  ]
}
```

**NEW:**
```json
{
  "amount": 1000,
  "currency": "RUB",
  "items": [
    {
      "itemID": 123,
      "price": 500,
      "name": "Product Name",
      "quantity": 2  // <-- ADD THIS FIELD
    }
  ]
}
```

### 5. Email Purchase Confirmation

**POST /purchase-email**

Update items to include quantity:

**NEW:**
```json
{
  "email": "user@example.com",
  "telegramUserId": "123456",
  "items": [
    {
      "itemID": 123,
      "name": "Product Name",
      "price": 500,
      "currency": "RUB",
      "quantity": 2  // <-- ADD THIS FIELD
    }
  ]
}
```

## Future: Filters & Sorting (To Be Discussed)

### GET /category/{categoryID}

Add query parameters for filtering and sorting:

**Proposed Query Parameters:**
- `sort`: Sort order (e.g., `price_asc`, `price_desc`, `rating_desc`, `name_asc`)
- `minPrice`: Minimum price filter
- `maxPrice`: Maximum price filter
- `minRating`: Minimum rating filter (1-5)
- `count`: Number of items per page (already exists)
- `skip`: Offset for pagination (already exists)

**Example:**
```
GET /category/5?sort=price_asc&minPrice=100&maxPrice=500&minRating=4&count=20&skip=0
```

**Response:** Same as current (array of items)

---

## Summary

**Required NOW:**
1. Add `quantity` field to cart item responses
2. Support `quantity` parameter in POST /cart
3. Create new PATCH /cart endpoint for updating quantities
4. Include `quantity` in payment and email endpoints

**Future (After Discussion):**
- Sorting and filtering query parameters for category items endpoint