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 ServiceResult s, and the repository performs the checkout transaction with row locks so inventory and cart state can’t be corrupted under concurrency.

Checkout As a Transaction, Not a “Normal Write”

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.

Snapshotting: Why Orders Copy Cart Items

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.

Route: POST /api/carts/:id/checkout

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: TypeScript// 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.

Join the 1M+ learners on CodeSignal

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

Service: Mapping Checkout Errors Into API-Friendly Results

The service layer is what allows routes to stay simple. Routes call services and rely on ServiceResult to include the correct httpStatus.

In this course, checkout failures are intentionally modeled as CheckoutError thrown by the repository. The service catches that and converts it into a structured fail(...) result via mapCheckoutError(e).

This code lives in src/lib/services/ordersService.ts:

TypeScript

// src/lib/services/ordersService.ts
import { ServiceResult, ok, fail } from "@/lib/services/types";
import { CheckoutError } from "@/lib/repositories/ordersRepo";

function mapCheckoutError(e: CheckoutError): ServiceResult<never> {
  switch (e.code) {
    case "CART_NOT_FOUND":
      return fail({
        code: "NOT_FOUND",
        message: "Cart not found",
        httpStatus: 404,
      });
    case "CART_NOT_OPEN":
      return fail({
        code: "CONFLICT",
        message: "Cart is not open",
        httpStatus: 409,
      });
    case "EMPTY_CART":
      return fail({
        code: "CONFLICT",
        message: "Cart is empty",
        httpStatus: 409,
      });
    case "INSUFFICIENT_INVENTORY":
      return fail({
        code: "CONFLICT",
        message: "Insufficient inventory",
        details: e.details,
        httpStatus: 409,
      });
    default:
      return fail({
        code: "INTERNAL_ERROR",
        message: "Checkout failed",
        httpStatus: 500,
      });
  }
}

// src/lib/services/ordersService.ts
import { ServiceResult, ok, fail } from "@/lib/services/types";
import { CheckoutError } from "@/lib/repositories/ordersRepo";

function mapCheckoutError(e: CheckoutError): ServiceResult<never> {
  switch (e.code) {
    case "CART_NOT_FOUND":
      return fail({
        code: "NOT_FOUND",
        message: "Cart not found",
        httpStatus: 404,
      });
    case "CART_NOT_OPEN":
      return fail({
        code: "CONFLICT",
        message: "Cart is not open",
        httpStatus: 409,
      });
    case "EMPTY_CART":
      return fail({
        code: "CONFLICT",
        message: "Cart is empty",
        httpStatus: 409,
      });
    case "INSUFFICIENT_INVENTORY":
      return fail({
        code: "CONFLICT",
        message: "Insufficient inventory",
        details: e.details,
        httpStatus: 409,
      });
    default:
      return fail({
        code: "INTERNAL_ERROR",
        message: "Checkout failed",
        httpStatus: 500,
      });
  }
}

The mapping is deliberate and stable: repository error codes are converted into API-level error codes and HTTP status codes that routes can forward directly.
CART_NOT_FOUND maps to 404 because the cart resource is missing. This is a “not found” outcome, not a conflict.
CART_NOT_OPEN, EMPTY_CART, and INSUFFICIENT_INVENTORY map to 409 CONFLICT because the request conflicts with the current business state: the cart is sealed, has no items, or stock can’t satisfy the checkout.
For INSUFFICIENT_INVENTORY, the service includes details: e.details. That’s critical because clients often need to show which product is short (and by how much).
The goal is consistency: routes should never invent new mapping rules. They should always rely on error.httpStatus coming from the service.

Next, the service’s centralized exception handler decides whether an error is a business checkout error, a Postgres error, or an unexpected internal failure:

TypeScript

// src/lib/services/ordersService.ts
import { isPostgresError, mapPostgresError } from "@/lib/db/errors";

function handleException(e: unknown): ServiceResult<never> {
  if (e instanceof CheckoutError) {
    return mapCheckoutError(e);
  }
  if (isPostgresError(e)) return fail(mapPostgresError(e));
  return fail({
    code: "INTERNAL_ERROR",
    message: (e as Error)?.message ?? "Internal error",
    httpStatus: 500,
  });
}

// src/lib/services/ordersService.ts
import { isPostgresError, mapPostgresError } from "@/lib/db/errors";

function handleException(e: unknown): ServiceResult<never> {
  if (e instanceof CheckoutError) {
    return mapCheckoutError(e);
  }
  if (isPostgresError(e)) return fail(mapPostgresError(e));
  return fail({
    code: "INTERNAL_ERROR",
    message: (e as Error)?.message ?? "Internal error",
    httpStatus: 500,
  });
}

CheckoutError is treated as an expected business failure and mapped into a structured failure result. This prevents “empty cart” from ever looking like a server crash.
Postgres errors are handled consistently using mapPostgresError, keeping DB-specific concerns out of the route layer.
Anything else becomes an INTERNAL_ERROR with 500, which is appropriate when something truly unexpected happens.

Finally, checkout itself is intentionally thin in the service: generate an order ID and delegate to the repository transaction.

TypeScript

// src/lib/services/ordersService.ts
import { randomUUID } from "node:crypto";
import { Order } from "@/lib/types/domain";
import { createOrderFromCart } from "@/lib/repositories/ordersRepo";

export async function checkoutService(
  cartId: string,
): Promise<ServiceResult<Order>> {
  try {
    const order = await createOrderFromCart({ orderId: randomUUID(), cartId });
    return ok(order);
  } catch (e: unknown) {
    return handleException(e);
  }
}

// src/lib/services/ordersService.ts
import { randomUUID } from "node:crypto";
import { Order } from "@/lib/types/domain";
import { createOrderFromCart } from "@/lib/repositories/ordersRepo";

export async function checkoutService(
  cartId: string,
): Promise<ServiceResult<Order>> {
  try {
    const order = await createOrderFromCart({ orderId: randomUUID(), cartId });
    return ok(order);
  } catch (e: unknown) {
    return handleException(e);
  }
}

The service owns ID generation (randomUUID()), keeping repositories focused on persistence, not orchestration.
All real checkout guarantees happen inside createOrderFromCart. This ensures the strongest invariants are enforced where they matter most: inside the transaction.
The service catches any thrown error and converts it into a ServiceResult, which is exactly what the route needs to produce consistent HTTP responses.

Repository: createOrderFromCart and Transactional Checkout Guarantees

The core of checkout lives in:

src/lib/repositories/ordersRepo.ts

This function runs inside withTransaction(...), and that is what guarantees checkout behaves atomically: either everything succeeds, or nothing is applied.

Below is the full checkout implementation, and then we’ll break it down by the key invariants and the locking strategy.

// src/lib/repositories/ordersRepo.ts
export async function createOrderFromCart(params: {
  orderId: string;
  cartId: string;
}): Promise<Order> {
  const { orderId, cartId } = params;
  return withTransaction(async (client: DbClient) => {
    const cartRows = await client.query<CartSnapshotRow>(
      "SELECT id, status FROM carts WHERE id = $1 FOR UPDATE",
      [cartId],
    );
    const cart = cartRows.rows[0];
    if (!cart) {
      throw new CheckoutError("CART_NOT_FOUND");
    }
    if (cart.status !== "open") {
      throw new CheckoutError("CART_NOT_OPEN");
    }

    const itemsResult = await client.query<CartItemSnapshotRow>(
      `SELECT product_id, quantity, unit_price_cents FROM cart_items WHERE cart_id = $1 ORDER BY created_at ASC FOR UPDATE`,
      [cartId],
    );
    if (itemsResult.rows.length === 0) {
      throw new CheckoutError("EMPTY_CART");
    }

    const productIds = [...new Set(itemsResult.rows.map((r) => r.product_id))];
    const productsResult = await client.query<ProductInventoryRow>(
      `SELECT id, currency, inventory_count FROM products WHERE id = ANY($1::uuid[]) FOR UPDATE`,
      [productIds],
    );
    const productMap = new Map(productsResult.rows.map((p) => [p.id, p]));

    const productQuantities = new Map<string, number>();
    for (const item of itemsResult.rows) {
      const currentQty = productQuantities.get(item.product_id) ?? 0;
      productQuantities.set(item.product_id, currentQty + item.quantity);
    }

    for (const [productId, requiredQty] of productQuantities.entries()) {
      const product = productMap.get(productId);
      if (!product || product.inventory_count < requiredQty) {
        throw new CheckoutError("INSUFFICIENT_INVENTORY", {
          productId,
          available: product?.inventory_count ?? 0,
        });
      }
    }

    for (const [productId, requiredQty] of productQuantities.entries()) {
      await client.query(
        "UPDATE products SET inventory_count = inventory_count - $1, updated_at = now() WHERE id = $2",
        [requiredQty, productId],
      );
    }

    const subtotal = itemsResult.rows.reduce(
      (acc, r) => acc + r.quantity * r.unit_price_cents,
      0,
    );
    const tax = computeTaxCents(subtotal);
    const total = subtotal + tax;
    const currency = (productMap.get(itemsResult.rows[0].product_id)
      ?.currency ?? "USD") as Order["currency"];

    const orderRows = await client.query<OrderRow>(
      `INSERT INTO orders (id, cart_id, status, subtotal_cents, tax_cents, total_cents, currency)
       VALUES ($1,$2,'pending',$3,$4,$5,$6) RETURNING *`,
      [orderId, cartId, subtotal, tax, total, currency],
    );
    const order = mapOrderRow(orderRows.rows[0]);

    for (const r of itemsResult.rows) {
      await client.query<OrderItemRow>(
        `INSERT INTO order_items (id, order_id, product_id, quantity, unit_price_cents)
         VALUES ($1,$2,$3,$4,$5)`,
        [randomUUID(), order.id, r.product_id, r.quantity, r.unit_price_cents],
      );
    }

    await client.query(
      "UPDATE carts SET status = $1, updated_at = now() WHERE id = $2",
      ["checked_out", cartId],
    );
    return order;
  });
}

The entire checkout workflow occurs inside withTransaction. This ensures that if inventory is insufficient, or order insertion fails, or anything throws, the database rolls back to the pre-checkout state.
Row locks (FOR UPDATE) prevent concurrent checkout requests from seeing stale state or double-spending inventory. Without these locks, two transactions could both pass inventory checks and decrement stock twice.
Notice that the repository throws CheckoutError for expected business failures. That’s intentional: the repository is the best place to detect these invariants, and the service is the best place to translate them into HTTP semantics.

Locking Products, Validating Inventory, and Reporting Details

Inventory correctness is one of the most important checkout guarantees. This checkout implementation locks product rows and verifies there’s enough stock for the total requested quantity per product.

First, it locks all products involved:

TypeScript

const productIds = [...new Set(itemsResult.rows.map((r) => r.product_id))];
const productsResult = await client.query<ProductInventoryRow>(
  `SELECT id, currency, inventory_count FROM products WHERE id = ANY($1::uuid[]) FOR UPDATE`,
  [productIds],
);
const productMap = new Map(productsResult.rows.map((p) => [p.id, p]));

const productIds = [...new Set(itemsResult.rows.map((r) => r.product_id))];
const productsResult = await client.query<ProductInventoryRow>(
  `SELECT id, currency, inventory_count FROM products WHERE id = ANY($1::uuid[]) FOR UPDATE`,
  [productIds],
);
const productMap = new Map(productsResult.rows.map((p) => [p.id, p]));

new Set(...) ensures each product ID appears once, avoiding redundant row locking and redundant checks.
FOR UPDATE locks each product row so other checkouts can’t decrement inventory concurrently and cause oversells.
Building productMap gives you O(1) product lookups per cart item, which keeps the code simple and efficient.

Then it aggregates required quantities per product and validates inventory:

TypeScript

const productQuantities = new Map<string, number>();
for (const item of itemsResult.rows) {
  const currentQty = productQuantities.get(item.product_id) ?? 0;
  productQuantities.set(item.product_id, currentQty + item.quantity);
}

for (const [productId, requiredQty] of productQuantities.entries()) {
  const product = productMap.get(productId);
  if (!product || product.inventory_count < requiredQty) {
    throw new CheckoutError("INSUFFICIENT_INVENTORY", {
      productId,
      available: product?.inventory_count ?? 0,
    });
  }
}

const productQuantities = new Map<string, number>();
for (const item of itemsResult.rows) {
  const currentQty = productQuantities.get(item.product_id) ?? 0;
  productQuantities.set(item.product_id, currentQty + item.quantity);
}

for (const [productId, requiredQty] of productQuantities.entries()) {
  const product = productMap.get(productId);
  if (!product || product.inventory_count < requiredQty) {
    throw new CheckoutError("INSUFFICIENT_INVENTORY", {
      productId,
      available: product?.inventory_count ?? 0,
    });
  }
}

The aggregation step matters because there can be multiple cart item rows (or logically multiple quantities) referencing the same product. Checkout needs the total required quantity per product to validate correctly.
Throwing INSUFFICIENT_INVENTORY includes details with productId and available. This is exactly what allows client UIs to show helpful messages like “Only 2 left in stock.”
The service preserves these details when it maps the error, so routes can forward them without inventing custom payload structures.