Managing Order Transitions

Huge congrats for making it this far. 🎉 You’ve built a full “mini e-commerce backend” flow: carts \to items \to checkout \to orders \to retrieval . What’s left now is the part that makes orders feel “alive”: state transitions . In this final lesson, you’ll implement the two most important “actions” on an order in this codebase: Pay an order: POST /api/orders/:id/pay Cancel an order: POST /api/orders/:id/cancel You’ll see the same layering pattern you’ve used throughout the course: Routes validate input and enforce HTTP method rules. Services enforce business rules like “only pending orders can be paid.” Repositories persist state changes with a safe UPDATE ... RETURNING ... .

What “Order Transitions” Mean Here

Orders have a status field with a small set of allowed values: pending (created at checkout) paid shipped cancelled This project intentionally uses action routes (/pay, /cancel) instead of a generic “update status” endpoint. That’s because transitions are not “free-form edits”—they’re business actions with rules: Paying is only valid from pending . Canceling is blocked if the order is already shipped or already cancelled . Those rules belong in the service layer, so every caller follows the same policy.

Repository: Persisting a Status Change With setOrderStatus

Learners will implement setOrderStatus(id, status) in src/lib/repositories/ordersRepo.ts. The requirements are very specific: Run an update: UPDATE orders SET status = $1, updated_at = now() WHERE id = $2 RETURNING * If no row is returned, return null (so the service can turn it into a 404) If a row is returned, map it with mapOrderRow(...) so the rest of the app sees domain data Here’s what that looks like in this repo style: TypeScript// src/lib/repositories/ordersRepo.ts export async function setOrderStatus( id: string, status: Order["status"], ): Promise<Order | null> { const rows = await query<OrderRow>( `UPDATE orders SET status = $1, updated_at = now() WHERE id = $2 RETURNING *`, [status, id], ); return rows[0] ? mapOrderRow(rows[0]) : null; } RETURNING * is doing a lot of work for you: you don’t need to perform a second query to re-fetch the updated order, which keeps transitions fast and consistent. The rows[0] ? ... : null shape is a deliberate contract: repositories don’t decide HTTP status codes; they simply report “updated” vs “not found.” Mapping via mapOrderRow keeps the “no raw DB rows beyond the repo” rule intact. Services/routes never deal with OrderRow directly.

Join the 1M+ learners on CodeSignal

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

payOrderService: pending → paid only

Requirements:

If the order doesn’t exist → 404
Only allow paying when order.status === "pending"
Otherwise return 409 with a message like Cannot pay order in status <status>
If allowed, call setOrderStatus(id, "paid") and return the updated order
Keep the failure shape consistent (fail({ code, message, httpStatus }))

A clean implementation looks like this:

TypeScript

// src/lib/services/ordersService.ts
export async function payOrderService(
  id: string,
): Promise<ServiceResult<Order>> {
  try {
    const order = await getOrderById(id);
    if (!order) {
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

    if (order.status !== "pending") {
      return fail({
        code: "CONFLICT",
        message: `Cannot pay order in status ${order.status}`,
        httpStatus: 409,
      });
    }

    const updated = await setOrderStatus(id, "paid");
    if (!updated) {
      // Defensive: the order could disappear between read + update
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

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

// src/lib/services/ordersService.ts
export async function payOrderService(
  id: string,
): Promise<ServiceResult<Order>> {
  try {
    const order = await getOrderById(id);
    if (!order) {
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

    if (order.status !== "pending") {
      return fail({
        code: "CONFLICT",
        message: `Cannot pay order in status ${order.status}`,
        httpStatus: 409,
      });
    }

    const updated = await setOrderStatus(id, "paid");
    if (!updated) {
      // Defensive: the order could disappear between read + update
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

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

The service reads first (getOrderById) because the transition depends on the current status.
Returning 409 CONFLICT is important: the request is valid (UUID exists), but the system state makes it invalid (e.g., it’s already paid).
The second NOT_FOUND check after setOrderStatus looks redundant, but it’s a good correctness habit: it handles edge cases where the record disappears between the read and the update.

cancelOrderService: block shipped/cancelled

Requirements:

If missing → 404
Reject status === "shipped" and status === "cancelled" with 409
Otherwise call setOrderStatus(id, "cancelled")
Keep the error envelope consistent

Implementation:

TypeScript

// src/lib/services/ordersService.ts
export async function cancelOrderService(
  id: string,
): Promise<ServiceResult<Order>> {
  try {
    const order = await getOrderById(id);
    if (!order) {
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

    if (order.status === "shipped" || order.status === "cancelled") {
      return fail({
        code: "CONFLICT",
        message: `Cannot cancel order in status ${order.status}`,
        httpStatus: 409,
      });
    }

    const updated = await setOrderStatus(id, "cancelled");
    if (!updated) {
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

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

// src/lib/services/ordersService.ts
export async function cancelOrderService(
  id: string,
): Promise<ServiceResult<Order>> {
  try {
    const order = await getOrderById(id);
    if (!order) {
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

    if (order.status === "shipped" || order.status === "cancelled") {
      return fail({
        code: "CONFLICT",
        message: `Cannot cancel order in status ${order.status}`,
        httpStatus: 409,
      });
    }

    const updated = await setOrderStatus(id, "cancelled");
    if (!updated) {
      return fail({
        code: "NOT_FOUND",
        message: "Order not found",
        httpStatus: 404,
      });
    }

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

This rule set intentionally allows canceling in other states (including pending and even paid in the current simplified rules). Whether that’s “realistic” isn’t the point here—the point is the service is the single source of truth for policy.
Like pay, cancel returns 409 for invalid transitions rather than throwing.

Managing Order Transitions

What “Order Transitions” Mean Here

Repository: Persisting a Status Change With setOrderStatus

Join the 1M+ learners on CodeSignal

Service: payOrderService and cancelOrderService Business Rules

payOrderService: pending → paid only

cancelOrderService: block shipped/cancelled

Routes: POST-only Action Endpoints With UUID Validation

Pay route: POST /api/orders/:id/pay

Cancel route: POST /api/orders/:id/cancel

Why This Layering Matters

Recap