Add products to cart and manage quantities

The cart system maintains one active cart per user. The first time a product is added, a new cart document is created and linked to the authenticated user. Every subsequent add or quantity update modifies that same cart — there is no need to create a cart explicitly. Subtotals and item counts are recalculated automatically on every mutation, and stock levels (minCant) are decremented when items are added and restored when they are removed or decreased.

Add a product to the cart

When a product is added, the item’s minCant (remaining stock) is decremented by cantBuy. If you later decrease the quantity or the item is removed, that stock is restored automatically.

POST /api/carts/agregate/:productId/cart Adds a product to the authenticated user’s cart. If the product–size combination already exists in the cart, the existing line’s subtotal is incremented rather than creating a duplicate entry. If the user has no existing cart, one is created on the fly.

Path parameters

productId

string

required

The unique identifier of the product to add to the cart.

Headers

token-access

string

required

A valid JWT token obtained from the authentication endpoint. Format: <jwt-token>

Request body

cantBuy

number

required

The quantity of the product to add. Must be greater than 0. A 203 is returned if this value is <= 0. The stock check (cantBuy > product.minCant) is only evaluated when product.minCant is truthy — if minCant is 0 the falsy short-circuit bypasses the check and the decrement proceeds.

sizes

array

required

The selected size(s) for the product. Used together with the product ID to identify duplicate cart entries — adding the same product with the same sizes (compared via JSON.stringify) increments the existing cart line’s subtotal rather than creating a new one.

Pricing logic

When the product has a discountPrice set (truthy), that value is used as the unit price; otherwise the standard price field is used. Both are parsed with parseFloat. The per-line subtotal is calculated as:

subtotalProducto = parseFloat(resolvedUnitPrice) × cantBuy

The cart’s overall subtotal is always the sum of all per-line subtotals.

Cart creation vs update logic

Authenticate user

The JWT token is validated and the user’s _id is extracted.

Validate request

cantBuy must be > 0. The product must exist. If product.minCant is truthy and cantBuy > product.minCant, a 203 is returned with "Stock no disponible". A 404 is returned if the product does not exist.

Decrement stock

product.minCant is reduced by cantBuy immediately after validation.

Resolve unit price

If discountPrice is truthy on the product, it is used; otherwise price is used. Both are parsed as floats.

Find or create cart

The user’s existing cart is located with Carts.findOne({"user._id": req.user._id}). If none exists, a new cart document is created with cantBuy, subtotal, products, and user set directly from the request.

Deduplicate by product + size (existing cart only)

For an existing cart, the products array is searched for an entry where p._id === productX._id.toString() && JSON.stringify(p.sizes) === JSON.stringify(sizes). If a match is found, only the matching line’s subtotal is increased by subtotalProducto. If no match is found, the product is pushed as a new line item (without a cantBuy field on the line). Then cart.cantBuy is incremented by the request’s cantBuy and cart.subtotal is recalculated as the sum of all line subtotals.

Save and respond

Both productX and cart are saved. The response includes the updated cart totals and full cart document.

Responses

msj

string

"Producto agregado/actualizado al carrito" on success.

status

boolean

true on success.

subtotalCarrito

number

The updated total monetary value of the cart after the operation.

cantidadTotal

number

The updated total number of individual items across all cart lines.

cart

object

The full, updated cart document.

Show Cart object fields

cart._id

string

Unique cart identifier.

cart.user

object

The buyer’s profile snapshot (populated at cart-creation time).

Show User fields

cart.user._id

string

Buyer ID.

cart.user.firstName

string

Buyer first name.

cart.user.lastName

string

Buyer last name.

cart.user.email

string

Buyer email.

cart.user.phone

number

Buyer phone number.

cart.user.sex

string

Buyer sex.

cart.user.document

string

Buyer document number.

cart.user.documentType

string

Buyer document type.

cart.user.activate

array

Buyer account activation flags ([{ name, value }]).

cart.products

array

Array of line items in the cart.

Show Product line item fields

cart.products[].user

object

Seller info snapshot (_id, firstName, lastName, roles, activate).

cart.products[]._id

string

Product ID.

cart.products[].title

string

Product title.

cart.products[].description

string

Product description.

cart.products[].sizes

array

Selected sizes for this line.

cart.products[].price

number

Original unit price.

cart.products[].discountPrice

string

Discounted unit price, if applicable.

cart.products[].discount

string

Discount label or percentage.

cart.products[].imageUrlIp

array

Product image URLs.

cart.products[].minCant

number

Remaining stock at the time the line was added (after decrement).

cart.products[].cantBuy

number

Quantity of this item in the cart (set on new-cart creation; not updated on existing-cart deduplication).

cart.products[].subtotal

number

Line subtotal (unit price × cantBuy).

cart.products[].date

string

Timestamp from the source product record.

cart.cantBuy

number

Total items in the cart (sum of all line cantBuy values).

cart.subtotal

number

Total cart value (sum of all line subtotals).

cart.date_creation_cart_client

string

ISO date when the cart was first created.

cart.createdAt

string

Mongoose-managed creation timestamp.

cart.updatedAt

string

Mongoose-managed last-updated timestamp.

Error responses

Status	Meaning
`203`	`cantBuy` is `<= 0` (invalid quantity).
`203`	`product.minCant` is truthy and `cantBuy > product.minCant` (insufficient stock).
`404`	Product not found.

Example

curl -X POST https://api.example.com/api/carts/agregate/64a1f8e2c3b2a10012d4e7f1/cart \
  -H "token-access: <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{
    "cantBuy": 2,
    "sizes": ["M"]
  }'

Update item quantity in cart

This endpoint is marked as unfinished (//* Sin terminar) in the source controller. The core increase/decrease logic is implemented and functional, but the endpoint may be subject to further changes.

POST /api/carts/:productId/cart/:cartId Increments or decrements the quantity of a specific product in an existing cart. Ownership is validated — the cart is looked up by both _id and user._id, so a user cannot modify another user’s cart. Stock is managed in both directions: increasing consumes stock, decreasing restores it.

Path parameters

productId

string

required

The ID of the product line to modify within the cart.

cartId

string

required

The ID of the cart document to update.

Headers

token-access

string

required

A valid JWT token. Format: <jwt-token>

Request body

action

string

required

The quantity change direction. Accepted values:

"increase" — adds 1 to the line’s cantBuy, deducts 1 from product.minCant. Fails with 203 if product.minCant <= 0.
"decrease" — subtracts 1 from the line’s cantBuy, restores 1 to product.minCant. If cantBuy is already <= 1, the entire product line is removed from the cart and the full cantBuy quantity is restored to product.minCant.

Increase behavior

Returns 203 with "Sin stock disponible" if product.minCant <= 0.
cartProduct.cantBuy is incremented by 1.
cartProduct.subtotal is recalculated as price × cantBuy.
product.minCant is decremented by 1 and saved.
Cart totals are recalculated from all lines.

Decrease behavior

If cartProduct.cantBuy <= 1: the full cantBuy quantity is restored to product.minCant, the product line is removed from the products array via splice, and cart totals are recalculated.
Otherwise: cartProduct.cantBuy is decremented by 1, cartProduct.subtotal is recalculated, product.minCant is restored by 1, and cart totals are recalculated.

Responses

msj

string

"Carrito actualizado" on success.

status

boolean

true on success.

subtotalCarrito

number

Updated total cart value.

cantidadTotal

number

Updated total item count.

cart

object

Full updated cart document (same shape as described in the add-to-cart section above).

Error responses

Status	Meaning
`400`	`action` is not `"increase"` or `"decrease"`.
`404`	Cart not found or does not belong to the authenticated user.
`404`	Product not found in the cart, or product not found in the database.
`203`	Attempted to `increase` but `product.minCant <= 0` (no stock remaining).

Example

curl -X POST https://api.example.com/api/carts/64a1f8e2c3b2a10012d4e7f1/cart/64b3c1a2d5e7f80023c9a4b1 \
  -H "token-access: <jwt-token>" \
  -H "Content-Type: application/json" \
  -d '{ "action": "increase" }'

Users

Products

Shopping Cart

Add products to cart and manage quantities

Add a product to the cart

Path parameters

Headers

Request body

Pricing logic

Cart creation vs update logic

Responses

Error responses

Example

Update item quantity in cart

Path parameters

Headers

Request body

Increase behavior

Decrease behavior

Responses

Error responses

Example

Build docs developers (and LLMs) love

Users

Products

Shopping Cart

Documentation Index

​Add a product to the cart

​Path parameters

​Headers

​Request body

​Pricing logic

​Cart creation vs update logic

​Responses

​Error responses

​Example

​Update item quantity in cart

​Path parameters

​Headers

​Request body

​Increase behavior

​Decrease behavior

​Responses

​Error responses

​Example

Build docs developers (and LLMs) love

Add a product to the cart

Path parameters

Headers

Request body

Pricing logic

Cart creation vs update logic

Responses

Error responses

Example

Update item quantity in cart

Path parameters

Headers

Request body

Increase behavior

Decrease behavior

Responses

Error responses

Example