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

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

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

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

TypeScript

// app/routes/api.orders.$id.pay.ts
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 order = await payOrderService(id);
    if (!order.ok)
      return error(
        order.error.code,
        order.error.message,
        order.error.details,
        order.error.httpStatus,
      );

    return success(order.value);
  } catch (e: unknown) {
    return error(
      "INTERNAL_ERROR",
      e instanceof Error ? e.message : "Internal error",
      undefined,
      500,
    );
  }
}

// app/routes/api.orders.$id.pay.ts
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 order = await payOrderService(id);
    if (!order.ok)
      return error(
        order.error.code,
        order.error.message,
        order.error.details,
        order.error.httpStatus,
      );

    return success(order.value);
  } catch (e: unknown) {
    return error(
      "INTERNAL_ERROR",
      e instanceof Error ? e.message : "Internal error",
      undefined,
      500,
    );
  }
}

TypeScript

// app/routes/api.orders.$id.cancel.ts
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 order = await cancelOrderService(id);
    if (!order.ok)
      return error(
        order.error.code,
        order.error.message,
        order.error.details,
        order.error.httpStatus,
      );

    return success(order.value);
  } catch (e: unknown) {
    return error(
      "INTERNAL_ERROR",
      e instanceof Error ? e.message : "Internal error",
      undefined,
      500,
    );
  }
}

// app/routes/api.orders.$id.cancel.ts
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 order = await cancelOrderService(id);
    if (!order.ok)
      return error(
        order.error.code,
        order.error.message,
        order.error.details,
        order.error.httpStatus,
      );

    return success(order.value);
  } catch (e: unknown) {
    return error(
      "INTERNAL_ERROR",
      e instanceof Error ? e.message : "Internal error",
      undefined,
      500,
    );
  }
}

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

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

TypeScript

// app/routes/api.orders.$id.pay.ts
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 order = await payOrderService(id);
    if (!order.ok)
      return error(
        order.error.code,
        order.error.message,
        order.error.details,
        order.error.httpStatus,
      );

    return success(order.value);
  } catch (e: unknown) {
    return error(
      "INTERNAL_ERROR",
      e instanceof Error ? e.message : "Internal error",
      undefined,
      500,
    );
  }
}

TypeScript

// app/routes/api.orders.$id.cancel.ts
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 order = await cancelOrderService(id);
    if (!order.ok)
      return error(
        order.error.code,
        order.error.message,
        order.error.details,
        order.error.httpStatus,
      );

    return success(order.value);
  } catch (e: unknown) {
    return error(
      "INTERNAL_ERROR",
      e instanceof Error ? e.message : "Internal error",
      undefined,
      500,
    );
  }
}

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