Paying and Cancelling Orders

At this point, your backend can create orders (via checkout) and let clients browse them (list + fetch). Now we’ll complete the basic order lifecycle by adding two actions that transition an order from one status to another: pay and cancel . In this lesson you’ll see how our codebase models state transitions safely: the API routes validate the order ID and call service functions, and the service layer enforces which transitions are allowed (pending \to paid, and “cancel unless shipped/already cancelled”). You’ll also learn why we use dedicated action routes like /pay and /cancel instead of a generic “update order” endpoint. Previously: Creating and Reading Orders In the earlier lessons, we built checkout to convert an open cart into a pending order, snapshotting cart items into order_items and marking the cart as checked_out . Then we added read endpoints so clients can list orders with pagination and fetch a single order by its UUID. Now that orders exist and are visible, we’re ready to let clients move them forward through the lifecycle.

Why “Action Routes” for State Transitions

Paying and cancelling aren’t just ordinary updates like “change a shipping address.” They’re business actions with strict rules and side effects (even in simplified form). That’s why this project uses action-based endpoints : POST /api/orders/:id/pay POST /api/orders/:id/cancel These endpoints say exactly what the client intends to do. They also make it easy to enforce rules like “only pending orders can be paid” without exposing a general “set status to anything” API.

Pay Endpoint: Route Handler

This code lives in src/app/api/orders/[id]/pay/route.ts. Its responsibility is to extract the id from the dynamic route, validate it, call the service, and return a consistent API response. TypeScript// src/app/api/orders/[id]/pay/route.ts import { NextRequest } from 'next/server'; import { success, error } from '@/lib/http/response'; import { payOrderService } from '@/lib/services/ordersService'; import { isUUID } from '@/lib/http/validation'; type RouteContext = { params: Promise<{ id: string }> }; export async function POST(_req: NextRequest, context: RouteContext) { try { const { id } = await context.params; if (!isUUID(id)) return error('VALIDATION_ERROR', 'Invalid id', undefined, 400); 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 as Error).message, undefined, 500); } }// src/app/api/orders/[id]/pay/route.ts import { NextRequest } from 'next/server'; import { success, error } from '@/lib/http/response'; import { payOrderService } from '@/lib/services/ordersService'; import { isUUID } from '@/lib/http/validation'; type RouteContext = { params: Promise<{ id: string }> }; export async function POST(_req: NextRequest, context: RouteContext) { try { const { id } = await context.params; if (!isUUID(id)) return error('VALIDATION_ERROR', 'Invalid id', undefined, 400); 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 as Error).message, undefined, 500); } } The dynamic segment [id] is accessed using the codebase’s modern pattern: const { id } = await context.params;. In this project, params is typed as a Promise, so this is the correct way to read it. isUUID(id) is a fast validation guard that stops malformed IDs early. This prevents wasted database work and ensures invalid inputs consistently return a 400 with a validation-style error code. The route calls payOrderService(id) and then simply forwards the ServiceResult. This keeps the route “thin,” with business rules living in the service layer instead of being duplicated in HTTP handlers. Both success and failure responses go through success(...) and error(...). That matters because it keeps every endpoint speaking the same “response language,” which makes clients and UI integration much easier.

Join the 1M+ learners on CodeSignal

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

Cancel Endpoint: Route Handler

This code lives in src/app/api/orders/[id]/cancel/route.ts. It follows the exact same structure as the pay route, which is a deliberate design choice: consistent endpoint structure reduces bugs and makes the codebase easier to extend.

TypeScript

// src/app/api/orders/[id]/cancel/route.ts
import { NextRequest } from 'next/server';
import { success, error } from '@/lib/http/response';
import { cancelOrderService } from '@/lib/services/ordersService';
import { isUUID } from '@/lib/http/validation';

type RouteContext = { params: Promise<{ id: string }> };

export async function POST(_req: NextRequest, context: RouteContext) {
  try {
    const { id } = await context.params;

    if (!isUUID(id)) return error('VALIDATION_ERROR', 'Invalid id', undefined, 400);

    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 as Error).message, undefined, 500);
  }
}

// src/app/api/orders/[id]/cancel/route.ts
import { NextRequest } from 'next/server';
import { success, error } from '@/lib/http/response';
import { cancelOrderService } from '@/lib/services/ordersService';
import { isUUID } from '@/lib/http/validation';

type RouteContext = { params: Promise<{ id: string }> };

export async function POST(_req: NextRequest, context: RouteContext) {
  try {
    const { id } = await context.params;

    if (!isUUID(id)) return error('VALIDATION_ERROR', 'Invalid id', undefined, 400);

    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 as Error).message, undefined, 500);
  }
}

Just like the pay route, the cancel route validates the UUID before calling into the service layer. This ensures malformed IDs are rejected consistently across all order action endpoints.
The handler does not try to interpret business rules like “can we cancel this order?” That logic belongs in cancelOrderService, so it remains consistent no matter how the service is called.
The route returns the updated order object on success, which is helpful for UIs that want to immediately reflect the new status after the action completes.
The try/catch around the handler ensures unexpected runtime errors become a structured INTERNAL_ERROR response rather than crashing the route or returning an inconsistent payload.

Paying an Order: Service Rules and State Transition

The pay logic lives in src/lib/services/ordersService.ts in payOrderService. This function enforces the “only pending orders can be paid” rule and performs the transition using the repository helper setOrderStatus.

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) 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) return fail({ code: 'NOT_FOUND', message: 'Order not found', httpStatus: 404 });
    return ok(updated);
  } catch (e: unknown) {
    return handleException(e);
  }
}

The service begins by loading the current order via getOrderById(id). This “read first, then transition” pattern is essential because whether you can pay depends on the current status, not just the request intent.
If the order doesn’t exist, the service returns a NOT_FOUND error with a 404. This is a normal business outcome (not an exception), which is why it’s expressed as a ServiceResult rather than a thrown error.
The transition rule is explicit: only pending can become paid. Any other status returns a 409 Conflict, because the request is valid in shape (UUID is fine) but invalid in business state.
setOrderStatus(id, 'paid') performs the actual update. The extra if (!updated) check looks redundant at first, but it’s a defensive guard against edge cases like the order being deleted between the read and the update.
The catch block delegates to handleException, keeping error behavior consistent with the rest of the service layer (including Postgres error mapping).

Cancelling an Order: Service Rules and Edge Cases

Cancellation also lives in src/lib/services/ordersService.ts, in cancelOrderService. It allows cancellation in most states, but explicitly blocks cancelling orders that are already shipped or already cancelled.

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

The service again starts with getOrderById(id) so the decision is based on real current state. That’s especially important for cancellation, because “cancel” is only meaningful when the order hasn’t progressed too far.
The blocking rule is: you cannot cancel an order that is shipped or already cancelled. This matches the current project behavior exactly and prevents repeated cancellations or cancelling after fulfillment is underway.
Notably, this logic does not block cancelling a paid order. That might not match every real-world business, but it is the rule as implemented here—and learners should understand that rules live in the service layer and can be refined later.
Like payOrderService, it uses setOrderStatus to perform the update, and it double-checks the update result to handle rare race conditions cleanly.
Errors are returned as structured ServiceResults with NOT_FOUND or CONFLICT rather than thrown, which keeps the HTTP routes very simple: they just forward the service outcome.

Orders Service Overview: How the Pieces Fit Together

src/lib/services/ordersService.ts is the central place where order-related business rules are enforced and where repository failures are translated into API-safe results. You’ve already worked with listOrdersService, getOrderService, and checkoutService—pay and cancel follow the same patterns.

Here’s a focused look at the file’s structure, with small snippets to orient you:

Shared error mapping for consistent API behavior

TypeScript

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

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

This helper is why service functions can stay readable: they focus on business logic while handleException standardizes failure behavior.
It also cleanly separates “expected business errors” (like checkout failures) from unexpected runtime/database failures, which prevents leaking raw errors to clients.

Read operations: list and fetch

TypeScript

export async function listOrdersService(...) { /* defaults + cap + listOrders */ }
export async function getOrderService(id: string) { /* getOrderById + 404 */ }

export async function listOrdersService(...) { /* defaults + cap + listOrders */ }
export async function getOrderService(id: string) { /* getOrderById + 404 */ }

These services normalize inputs and convert “missing data” into a clear 404. They’re thin by design, because the heavy logic belongs either in repositories (DB access) or in state transition rules.

Write/action operations: checkout, pay, cancel

TypeScript

export async function checkoutService(cartId: string) { /* createOrderFromCart */ }
export async function payOrderService(id: string) { /* pending -> paid */ }
export async function cancelOrderService(id: string) { /* block shipped/cancelled -> cancelled */ }

export async function checkoutService(cartId: string) { /* createOrderFromCart */ }
export async function payOrderService(id: string) { /* pending -> paid */ }
export async function cancelOrderService(id: string) { /* block shipped/cancelled -> cancelled */ }

Checkout is transaction-heavy and lives mostly in the repository; the service primarily generates an ID and maps errors.
Pay and cancel are rule-heavy and live mostly in the service: they read the order, enforce a transition rule, then call setOrderStatus.

The key takeaway: the service layer is the rulebook. Routes validate request shape and forward results, repositories persist data safely, and services decide what transitions are allowed.

Paying and Cancelling Orders