Adding Cart Line Items

Welcome back! 👋 Now that carts can be created and fetched in a fully hydrated shape (with items and computed totals), it’s time to make them actually useful by adding line items . In this lesson, you’ll implement the full “Add to Cart” flow: the route validates input and delegates to the service, the service enforces business rules like inventory and cart lifecycle, and the repository performs an atomic add-or-increment write using a transaction. This mirrors how real e-commerce backends handle users clicking “Add to cart” multiple times—correctly and safely, even under concurrency. Previously, your cart reads were already computing subtotal_cents, tax_cents, and total_cents . Once line items are added, those totals automatically become meaningful—because the repository recomputes them on every read.

What a Cart Line Item Represents

A cart line item corresponds to one row in the cart_items table. It captures: The product_id that was added. The quantity requested. The unit_price_cents at the time of addition (a snapshot). That unit_price_cents field is critical. Even if the product’s price changes later, your cart totals are computed from what was recorded in the cart. This keeps pricing stable and predictable for the user.

Route: POST /api/carts/:id/items

The entry point for adding items is implemented in: app/routes/api.carts.$id.items.ts This route is responsible for: Validating the :id URL parameter. Allowing only POST. Safely parsing JSON with parseJson(...). Validating the body using validateAddItem(...). Delegating to addItemService(...). Mapping service failures using the service-provided httpStatus. Returning 201 Created on success. Let’s walk through it carefully. First, the imports and route function: TypeScript// app/routes/api.carts.$id.items.ts import type { ActionFunctionArgs } from "@remix-run/node"; import { success, error, parseJson } from "@/lib/http/response"; import { addItemService, validateAddItem } from "@/lib/services/cartsService"; import { isUUID } from "@/lib/http/validation"; export async function action({ request, params }: ActionFunctionArgs) { try { const id = params.id ?? ""; if (!isUUID(id)) return error("VALIDATION_ERROR", "Invalid id", undefined, 400); if (request.method !== "POST") { return error("VALIDATION_ERROR", "Method not allowed", undefined, 405); } const bodyResult = await parseJson(request); 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); 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 instanceof Error ? e.message : "Internal error", undefined, 500, ); } } The route extracts params.id and immediately validates it using isUUID. If the ID is malformed, it returns a 400 VALIDATION_ERROR. This prevents meaningless database calls and clearly communicates “your URL is wrong.” Only POST is allowed. Any other method returns 405. This keeps the endpoint strict and predictable. parseJson(request) is used instead of directly calling request.json(). This ensures malformed JSON doesn’t crash the route and instead becomes a structured 400 error. validateAddItem(...) converts untrusted input into a strongly shaped AddCartItemInput. If validation fails, the route returns 400 before hitting any business logic. addItemService(...) returns a ServiceResult. The route does not guess HTTP codes—it forwards result.error.httpStatus, centralizing domain-to-HTTP mapping inside the service. On success, success(result.value, 201) returns 201 Created. Even if the row was incremented instead of inserted, it is still a successful mutation. This route stays thin. It owns HTTP mechanics, not business rules.

Join the 1M+ learners on CodeSignal

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

Service: addItemService Business Rules

Now we move to the core business logic in:

src/lib/services/cartsService.ts

This is where lifecycle rules, product checks, and inventory enforcement happen.

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);
  }
}

The cart is loaded first. ensureCartOpen(cart) enforces two rules: missing cart → 404, non-open cart → 409 CONFLICT. This prevents adding items to checked-out or abandoned carts.
The product must exist. If not found, we return 404. That’s a true missing resource.
If the product is "archived", we return 409 CONFLICT. The product exists but is not purchasable.
Inventory is enforced twice:
- First, if the incoming quantity exceeds inventory_count, we reject.
- Second, if the item already exists in the cart, we check existing.quantity + input.quantity. This prevents cumulative overflow.
Without that second check, a user could add 3 twice and bypass a 5-unit limit.
The service takes a price snapshot from product.price_cents. That value is passed into the repository as unitPriceCents.
The service does not contain SQL. It coordinates business rules and delegates persistence to the repository.

This layering keeps business logic testable and separate from database details.

Repository: addOrIncrementCartItem, Concurrency, and Correctness

The persistence logic lives in:

src/lib/repositories/cartsRepo.ts

This function must safely handle concurrent “Add to Cart” requests.

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);
}

withTransaction(...) guarantees atomicity of the write you choose to perform (the UPDATE or the INSERT) and ensures the function either fully succeeds or fully rolls back if something fails mid-way.
However, in standard PostgreSQL READ COMMITTED isolation, wrapping SELECT then INSERT in a transaction does not, by itself, prevent race conditions:
- Two concurrent requests can both run the SELECT, both observe “no row exists”, and then both attempt the INSERT.
What actually prevents duplicate (cart_id, product_id) rows is the database-level uniqueness rule (typically a UNIQUE (cart_id, product_id) constraint). Under concurrency, that constraint is the “final authority” that enforces “one row per product per cart.”
Because the constraint is what guarantees correctness, production-grade implementations usually handle this in one of these ways:
- Use an UPSERT: INSERT ... ON CONFLICT (cart_id, product_id) DO UPDATE SET quantity = cart_items.quantity + EXCLUDED.quantity ... RETURNING * so the database resolves the race in a single statement.
- Or, if keeping the “select-then-insert” approach, catch the unique-violation error and then retry by performing the UPDATE path (since you now know the row exists).
The main goal remains the same: “Add to cart” should behave like add-or-increment, even when two requests hit at the same time. The transaction helps keep a single attempt consistent, but the unique constraint (or UPSERT) is what makes the behavior correct under concurrency.