Adding Cart Line Items

Welcome back! 👋 Now that we can create carts and fetch them in a stable, predictable shape, it’s time to make a cart useful by adding items to it. In this lesson you’ll follow the full “Add to cart” flow end-to-end: the API route parses and validates the request, the service layer enforces business rules (like inventory limits), and the repository performs an add-or-increment write safely inside a transaction. This is the exact behavior you see in real e-commerce backends when a user clicks “Add to cart” multiple times. Previously\dots In the last lesson, we treated the cart as a first-class backend resource: you created carts and fetched them back fully “hydrated” with items and computed totals . That stable response shape is what makes today’s work clean—once we add cart_items rows, GET /api/carts/:id automatically becomes meaningful because totals can now be computed from those line items.

What a “line item” represents

A cart line item is one row in cart_items . It captures: Which product was added (product_id) How many (quantity) What price was used when it was added (unit_price_cents) That last field is a snapshot : it preserves stability if product prices change later. Our totals logic (from the previous lesson) uses this snapshot when computing subtotal and tax.

The API endpoint for adding items

The main entry point for “Add to cart” is: POST /api/carts/:id/items This is implemented in src/app/api/carts/[id]/items/route.ts . The handler is deliberately strict: it validates the cart ID, safely parses JSON, validates the body shape, then delegates to the service layer and converts the result into a consistent HTTP response. Route setup and imports: This first part shows what the route depends on and how Next.js provides dynamic route params in this codebase. TypeScript // src/app/api/carts/[id]/items/route.ts import { NextRequest } from 'next/server'; import { success, error, parseJson } from '@/lib/http/response'; import { addItemService, validateAddItem } from '@/lib/services/cartsService'; import { isUUID } from '@/lib/http/validation'; type RouteContext = { params: Promise<{ id: string }> }; // src/app/api/carts/[id]/items/route.ts import { NextRequest } from 'next/server'; import { success, error, parseJson } from '@/lib/http/response'; import { addItemService, validateAddItem } from '@/lib/services/cartsService'; import { isUUID } from '@/lib/http/validation'; type RouteContext = { params: Promise<{ id: string }> }; success and error are the project’s response helpers, so every route returns a consistent envelope instead of hand-rolling NextResponse formatting in each file. parseJson(req) is used instead of req.json() directly so the route can handle malformed JSON without crashing. That keeps error handling consistent and prevents “unexpected 500s” for simple client mistakes. RouteContext is important: in this project, context.params is a Promise . That’s why the handler does const { id } = await context.params instead of accessing params synchronously.

Join the 1M+ learners on CodeSignal

Be a part of our community of 1M+ users who develop and demonstrate their skills on CodeSignal

TypeScript

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

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

TypeScript

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

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

    // ...continued below

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

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

    // ...continued below

TypeScript

// src/app/api/carts/[id]/items/route.ts
    const bodyResult = await parseJson(req);
    if (!bodyResult.ok) return error(bodyResult.code, bodyResult.message, undefined, 400);

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

    // ...continued below

// src/app/api/carts/[id]/items/route.ts
    const bodyResult = await parseJson(req);
    if (!bodyResult.ok) return error(bodyResult.code, bodyResult.message, undefined, 400);

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

    // ...continued below

TypeScript

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

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

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

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

TypeScript

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

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

TypeScript

// src/lib/repositories/cartsRepo.ts
export async function addOrIncrementCartItem(params: { cartId: string; itemId: string; productId: string; quantity: number; unitPriceCents: number }): Promise<CartItem> {
  const { cartId, itemId, productId, quantity, unitPriceCents } = params;
  const rows = await withTransaction(async (client) => {
    const existing = await client.query<CartItemRow>(
      `SELECT * FROM cart_items WHERE cart_id = $1 AND product_id = $2`,
      [cartId, productId]
    );

    if (existing.rows[0]) {
      const updated = await client.query<CartItemRow>(
        `UPDATE cart_items SET quantity = quantity + $1, updated_at = now() WHERE id = $2 RETURNING *`,
        [quantity, existing.rows[0].id]
      );
      return updated.rows;
    }

    const inserted = await client.query<CartItemRow>(
      `INSERT INTO cart_items (id, cart_id, product_id, quantity, unit_price_cents) VALUES ($1,$2,$3,$4,$5) RETURNING *`,
      [itemId, cartId, productId, quantity, unitPriceCents]
    );
    return inserted.rows;
  });
  const ci = rows[0];
  return mapCartItemRow(ci);
}

TypeScript

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

    const product = await getProductById(input.product_id);
    if (!product) return fail({ code: 'NOT_FOUND', message: 'Product not found', httpStatus: 404 });

    if (product.status === 'archived') return fail({ code: 'CONFLICT', message: 'Archived product cannot be added', httpStatus: 409 });

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

    const existing = await getCartItemByCartAndProduct(cartId, product.id);
    if (existing && existing.quantity + input.quantity > product.inventory_count) {
      return fail({ code: 'CONFLICT', message: 'Insufficient inventory', httpStatus: 409 });
    }

    const item = await addOrIncrementCartItem({
      cartId,
      itemId: randomUUID(),
      productId: product.id,
      quantity: input.quantity,
      unitPriceCents: product.price_cents,
    });
    return ok(item);
  } catch (e: unknown) {
    return handleException(e);
  }
}

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

    const product = await getProductById(input.product_id);
    if (!product) return fail({ code: 'NOT_FOUND', message: 'Product not found', httpStatus: 404 });

    if (product.status === 'archived') return fail({ code: 'CONFLICT', message: 'Archived product cannot be added', httpStatus: 409 });

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

    const existing = await getCartItemByCartAndProduct(cartId, product.id);
    if (existing && existing.quantity + input.quantity > product.inventory_count) {
      return fail({ code: 'CONFLICT', message: 'Insufficient inventory', httpStatus: 409 });
    }

    const item = await addOrIncrementCartItem({
      cartId,
      itemId: randomUUID(),
      productId: product.id,
      quantity: input.quantity,
      unitPriceCents: product.price_cents,
    });
    return ok(item);
  } catch (e: unknown) {
    return handleException(e);
  }
}

TypeScript

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

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

    // ...continued below

TypeScript

// src/app/api/carts/[id]/items/route.ts
    const bodyResult = await parseJson(req);
    if (!bodyResult.ok) return error(bodyResult.code, bodyResult.message, undefined, 400);

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

    // ...continued below

TypeScript

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

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

TypeScript

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

TypeScript

// src/lib/repositories/cartsRepo.ts
export async function addOrIncrementCartItem(params: { cartId: string; itemId: string; productId: string; quantity: number; unitPriceCents: number }): Promise<CartItem> {
  const { cartId, itemId, productId, quantity, unitPriceCents } = params;
  const rows = await withTransaction(async (client) => {
    const existing = await client.query<CartItemRow>(
      `SELECT * FROM cart_items WHERE cart_id = $1 AND product_id = $2`,
      [cartId, productId]
    );

    if (existing.rows[0]) {
      const updated = await client.query<CartItemRow>(
        `UPDATE cart_items SET quantity = quantity + $1, updated_at = now() WHERE id = $2 RETURNING *`,
        [quantity, existing.rows[0].id]
      );
      return updated.rows;
    }

    const inserted = await client.query<CartItemRow>(
      `INSERT INTO cart_items (id, cart_id, product_id, quantity, unit_price_cents) VALUES ($1,$2,$3,$4,$5) RETURNING *`,
      [itemId, cartId, productId, quantity, unitPriceCents]
    );
    return inserted.rows;
  });
  const ci = rows[0];
  return mapCartItemRow(ci);
}

TypeScript

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

    const product = await getProductById(input.product_id);
    if (!product) return fail({ code: 'NOT_FOUND', message: 'Product not found', httpStatus: 404 });

    if (product.status === 'archived') return fail({ code: 'CONFLICT', message: 'Archived product cannot be added', httpStatus: 409 });

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

    const existing = await getCartItemByCartAndProduct(cartId, product.id);
    if (existing && existing.quantity + input.quantity > product.inventory_count) {
      return fail({ code: 'CONFLICT', message: 'Insufficient inventory', httpStatus: 409 });
    }

    const item = await addOrIncrementCartItem({
      cartId,
      itemId: randomUUID(),
      productId: product.id,
      quantity: input.quantity,
      unitPriceCents: product.price_cents,
    });
    return ok(item);
  } catch (e: unknown) {
    return handleException(e);
  }
}

Adding Cart Line Items

What a “line item” represents

The API endpoint for adding items

Join the 1M+ learners on CodeSignal

Reading and validating the cart ID

Safely parsing JSON and validating the request body

Calling the service and translating results into HTTP

Validation: protecting the service layer from bad input

Repository: add-or-increment with a transaction

Service: enforcing business rules for adding items

How this connects back to fetching carts

Recap