Managing Cart Line Items

Welcome back! 👋 In the last lesson you made carts useful by adding line items with a real-world add-or-increment behavior. The route validated inputs, the service enforced business rules like inventory checks, and the repository performed safe writes in a transaction.

In this final lesson, we make the cart feel editable like a real shopping experience. You’ll learn how our API targets a specific cart item row so clients can update quantity or remove an item—without resending product details.

To update or delete a line item, we address it directly by its cart item ID:

/api/carts/:id/items/:itemId

That means we always deal with two identifiers:

• id: the cart UUID (from the carts table)
• itemId: the cart item UUID (from the cart_items table)

This is important because changing quantity or deleting an item is an operation on the line item row, not on the product itself.

The file src/app/api/carts/[id]/items/[itemId]/route.ts contains both endpoints:

• PATCH for updating quantity
• DELETE for removing the item

The route follows the same “fail fast” pattern you’ve seen already: validate path params, validate body (for PATCH), call the service, then translate the ServiceResult into an HTTP response.

Route setup and parameter handling:

// src/app/api/carts/[id]/items/[itemId]/route.ts
import { NextRequest } from 'next/server';
import { success, error, parseJson } from '@/lib/http/response';
import { isUUID } from '@/lib/http/validation';
import { updateItemService, deleteItemService, validateUpdateItem } from '@/lib/services/cartsService';

type RouteContext = { params: Promise<{ id: string; itemId: string }> };

• This route uses the same response helpers as the rest of the API (success, error) so responses stay consistent across endpoints.
• RouteContext again defines params as a Promise, so we always await context.params to read id and itemId.
• parseJson is used for PATCH so malformed JSON becomes a clean 400, rather than a thrown exception that would force a generic 500.

Updating a line item is a “quantity edit.” The client sends { "quantity": number }, and we validate everything before touching the database.

Validating both IDs and parsing the request body:

// src/app/api/carts/[id]/items/[itemId]/route.ts
export async function PATCH(req: NextRequest, context: RouteContext) {
  try {
    const { id, itemId } = await context.params;

    if (!isUUID(id) || !isUUID(itemId)) return error('VALIDATION_ERROR', 'Invalid id or itemId', undefined, 400);

    const bodyResult = await parseJson(req);
    if (!bodyResult.ok) return error(bodyResult.code, bodyResult.message, undefined, 400);

    const valid = validateUpdateItem(bodyResult.value);
    if (!valid.ok) return error('VALIDATION_ERROR', valid.message, undefined, 400);

    // ...continued below

• Both id and itemId are validated up front so invalid URLs are treated as client errors (400) instead of wasting database work.
• parseJson(req) protects the route from invalid JSON. If the body can’t be parsed, we return a standardized error envelope with an HTTP 400.
• validateUpdateItem ensures the service only receives a clean DTO { quantity: number }. That way, the service can focus on business rules instead of re-checking types.

// src/app/api/carts/[id]/items/[itemId]/route.ts
    const updated = await updateItemService(id, itemId, valid.value);
    if (!updated.ok)
      return error(updated.error.code, updated.error.message, updated.error.details, updated.error.httpStatus);

    return success(updated.value);
  } catch (e: unknown) {
    return error('INTERNAL_ERROR', (e as Error).message, undefined, 500);
  }
}

• The route delegates the update to updateItemService, passing both identifiers plus the validated payload.
• If the service returns a failure, the route doesn’t reinterpret it. It uses updated.error.httpStatus and returns exactly the error code/message/details the service produced.
• On success, the route returns the updated CartItem. This makes the UI experience nicer because the client can immediately reflect the new quantity from the response.

Deleting doesn’t need a request body. We still validate both IDs, then ask the service to delete that specific item.

Validating IDs and calling delete service:

// src/app/api/carts/[id]/items/[itemId]/route.ts
export async function DELETE(_req: NextRequest, context: RouteContext) {
  try {
    const { id, itemId } = await context.params;

    if (!isUUID(id) || !isUUID(itemId)) return error('VALIDATION_ERROR', 'Invalid id or itemId', undefined, 400);

    const deleted = await deleteItemService(id, itemId);
    if (!deleted.ok)
      return error(deleted.error.code, deleted.error.message, deleted.error.details, deleted.error.httpStatus);

    return success(deleted.value);
  } catch (e: unknown) {
    return error('INTERNAL_ERROR', (e as Error).message, undefined, 500);
  }
}

• Even though the delete operation ultimately targets a cart_items row, validating both id and itemId keeps the endpoint consistent and prevents confusing “half-valid” requests.
• deleteItemService returns a ServiceResult<{ deleted: true }> so the route can respond with a clear confirmation payload.
• Like the PATCH handler, the DELETE handler treats the service as the source of truth for HTTP mapping: NOT_FOUND becomes 404, cart state conflicts become 409, etc., without the route needing special cases.

Update validation is intentionally strict: in this API, “changing quantity” always means setting it to a positive integer. If someone wants to remove an item, they use DELETE instead.

Validating the update payload:

This lives in src/lib/services/cartsService.ts and is called by the PATCH route before the service runs.

// src/lib/services/cartsService.ts
export function validateUpdateItem(input: unknown): { ok: true; value: UpdateCartItemInput } | { ok: false; message: string } {
  const v = input as Partial<UpdateCartItemInput>;
  if (!isInt(v?.quantity, { min: 1 })) return { ok: false, message: 'quantity must be integer >= 1' };
  return { ok: true, value: { quantity: v.quantity! } };
}

• quantity must be an integer and must be at least 1. This avoids “0 quantity” rows, negative quantities, and fractional quantities that would make totals unpredictable.
• Returning a cleaned { quantity } object means updateItemService receives a properly shaped UpdateCartItemInput every time, which keeps business logic simpler and safer.
• This validation also creates a clean separation of intent: PATCH means edit quantity, and DELETE means remove the item.

updateItemService coordinates the update process and enforces important rules:

• the cart must exist and be open
• the item must exist
• the associated product must still be available (not archived)
• the new quantity must not exceed inventory

Updating quantity safely:

// src/lib/services/cartsService.ts
export async function updateItemService(cartId: string, itemId: string, input: UpdateCartItemInput): Promise<ServiceResult<CartItem>> {
  try {
    const cart = await getCartById(cartId);
    const cartResult = ensureCartOpen(cart);
    if (!cartResult.ok) return cartResult;

    const existing = await getCartItemByCartAndId(cartId, itemId);
    if (!existing) return fail({ code: 'NOT_FOUND', message: 'Cart item not found', httpStatus: 404 });

    const product = await getProductById(existing.product_id);
    if (!product || product.status === 'archived') return fail({ code: 'CONFLICT', message: 'Product not available', httpStatus: 409 });

    if (input.quantity > product.inventory_count) {
      return fail({ code: 'CONFLICT', message: 'Insufficient inventory', httpStatus: 409 });
    }

    const updated = await updateCartItemQuantity(cartId, itemId, input.quantity);
    if (!updated) return fail({ code: 'NOT_FOUND', message: 'Cart item not found', httpStatus: 404 });

    return ok(updated);
  } catch (e: unknown) {
    return handleException(e);
  }
}

• The service starts by loading the cart and enforcing lifecycle rules through ensureCartOpen. This prevents edits on carts that are already checked out or abandoned.
• It confirms the item exists inside that cart using getCartItemByCartAndId(cartId, itemId). That keeps the API honest: you can’t update an item that belongs to a different cart.
• The product lookup is used for inventory validation and availability rules. If the product is missing or archived, updating the cart item is treated as a conflict (409) because the item can’t be meaningfully maintained.
• The final call to updateCartItemQuantity(cartId, itemId, input.quantity) performs the actual write. The extra if (!updated) check handles the edge case where the row disappears between read and update (rare, but possible in concurrent systems).

Deleting an item is similar: we still enforce “cart must be open,” and we return clean 404s if the item doesn’t exist.

// src/lib/services/cartsService.ts
export async function deleteItemService(cartId: string, itemId: string): Promise<ServiceResult<{ deleted: true }>> {
  try {
    const cart = await getCartById(cartId);
    const cartResult = ensureCartOpen(cart);
    if (!cartResult.ok) return cartResult;

    const existing = await getCartItemByCartAndId(cartId, itemId);
    if (!existing) return fail({ code: 'NOT_FOUND', message: 'Cart item not found', httpStatus: 404 });

    const deleted = await deleteCartItem(cartId, itemId);
    if (!deleted) return fail({ code: 'NOT_FOUND', message: 'Cart item not found', httpStatus: 404 });

    return ok({ deleted: true });
  } catch (e: unknown) {
    return handleException(e);
  }
}

• We again enforce that only an open cart can be edited. This keeps cart state transitions predictable and avoids “mutating history” after checkout.
• We check existence before deleting so we can return a clear, user-friendly 404 and message when the item isn’t present.
• The delete function returns a boolean, so the service can distinguish “deleted successfully” from “nothing was deleted” and map that to a 404.

In this lesson you completed the cart editing experience:

• src/app/api/carts/[id]/items/[itemId]/route.ts exposes:

  • PATCH to update quantity (validates IDs + JSON + payload)
  • DELETE to remove the item (validates IDs, no body)

• validateUpdateItem enforces a strict update contract: quantity must be an integer ≥ 1.

• updateItemService and deleteItemService enforce business rules consistently:

  • cart must exist and be open
  • item must exist within that cart
  • updates must respect product availability and inventory

• updateCartItemQuantity and deleteCartItem perform the precise SQL operations scoped by both cart ID and item ID.

With create, add, update, and delete in place, your cart API now supports the full “editable cart” workflow that real checkout systems depend on.