marketplaces/docs/API_CHANGES_REQUIRED.md

Backend API Changes Required

Cart Quantity Support

1. Add Quantity to Cart Items

Current GET /cart Response:

[
  {
    "itemID": 123,
    "name": "Product Name",
    "price": 100,
    "currency": "RUB",
    ...other item fields
  }
]

NEW Required Response:

[
  {
    "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:

{
  "itemID": 123
}

NEW Request (with optional quantity):

{
  "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:

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

Response:

{
  "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:

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

NEW:

{
  "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:

{
  "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