Remix Checkout Implementation

Welcome to the Orders course! 👋 Up to now, your backend has been all about building and managing a cart—creating it, adding items, adjusting quantities, and computing totals. Checkout is the moment your system becomes a true e-commerce backend: we turn an editable cart into an immutable order, and we do it in a way that stays correct even if multiple requests hit the server at the same time.

In this lesson you’ll follow the checkout flow end-to-end in Remix: the route validates input and translates service results into HTTP responses, the service maps repository checkout failures into consistent ServiceResults, and the repository performs the checkout transaction with row locks so inventory and cart state can’t be corrupted under concurrency.

Checkout is special because it’s not just “insert a row.” It’s a coordinated sequence of steps that must all succeed together:

• confirm the cart exists and is eligible to checkout
• confirm the cart has items
• confirm inventory exists for all cart items
• decrement inventory
• create an order and snapshot items into order_items
• mark the cart as checked out so it cannot be checked out twice

If any part fails, nothing should be partially applied. That’s why checkout lives inside a single database transaction, with row locks (FOR UPDATE) to prevent concurrent checkouts or concurrent inventory changes from producing inconsistent state.

Carts are temporary and editable. Orders are historical and should remain stable.

At checkout time, we “snapshot” the cart by inserting one order_items row per cart_items row. Each order_items row stores:

• product_id
• quantity
• unit_price_cents (the price snapshot taken when the item was added to the cart)

This means the order total and receipt remain correct even if the product’s price changes later. The cart might change, but the order shouldn’t.

Checkout is exposed through a dedicated Remix action route:

app/routes/api.carts.$id.checkout.ts

The action’s responsibility is intentionally narrow:

• validate the cart id (params.id) using isUUID
• allow only POST
• call checkoutService(id)
• map failures using the service-provided httpStatus
• return 201 on success because an order resource was created

Here is the route implementation:

// app/routes/api.carts.$id.checkout.ts
import type { ActionFunctionArgs } from "@remix-run/node";
import { success, error } from "@/lib/http/response";
import { checkoutService } from "@/lib/services/ordersService";
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 result = await checkoutService(id);
    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,
    );
  }
}

• isUUID(id) runs before any service or DB call. Invalid UUIDs are treated as malformed requests (400), not “not found,” because the client didn’t even provide a valid identifier.
• Only POST is permitted. Checkout is a mutation that creates a new resource (an order), so other methods are rejected with 405 in the same consistent error envelope.
• The route does not invent status codes. It forwards result.error.httpStatus, which keeps error mapping logic centralized inside the service layer.
• On success, success(result.value, 201) is important: it tells clients “an order was created,” which is distinct from a normal 200 OK response.
• The outer try/catch is for unexpected failures only. Business failures should be represented by ServiceResult failures, not thrown exceptions.