Cancel Order

Instructions

Implementation Reference

• src/tools/orders/cancelOrder.ts:7-130 (handler)

  The main tool handler that registers the 'cancelOrder' tool with the MCP server, defines input schema (order_id, refund_channel), validates parameters, calls the API client, and formats the response.

  export function registerCancelOrderTool(server: McpServer): void {
    // Create API client instance
  
    // Register cancelOrder tool
    server.registerTool(
      "cancelOrder",
      {
        title: "Cancel Order",
        description:
          "Cancel an existing order. Parameters: order_id (required - accepts numbers like 6505 and strings like '6505'), refund_channel ('wallet' or 'card', required)",
        inputSchema: {
          order_id: z
            .union([z.string(), z.number()])
            .describe("The order ID to cancel"),
          refund_channel: z
            .enum(["wallet", "card"])
            .describe("Where to process the refund: 'wallet' or 'card'"),
        },
      },
      async (args: any) => {
        // Get API key from async context
        const apiKey = apiKeyStorage.getStore();
  
        if (!apiKey) {
          return {
            content: [
              {
                type: "text",
                text: "Error: X-API-KEY header is required",
              },
            ],
          };
        }
  
        // Create API client with customer's API key
        const client = new EuroparcelApiClient(apiKey);
  
        try {
          if (!args.order_id) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: order_id parameter is required",
                },
              ],
            };
          }
  
          const orderId = Number(args.order_id);
          if (!Number.isInteger(orderId) || orderId <= 0) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: order_id must be a positive integer",
                },
              ],
            };
          }
  
          if (
            !args.refund_channel ||
            !["wallet", "card"].includes(args.refund_channel)
          ) {
            return {
              content: [
                {
                  type: "text",
                  text: "Error: refund_channel parameter is required and must be 'wallet' or 'card'",
                },
              ],
            };
          }
  
          logger.info("Cancelling order", {
            order_id: orderId,
            refund_channel: args.refund_channel,
          });
  
          const result = await client.cancelOrder(orderId, args.refund_channel);
  
          logger.info("Order cancellation result", result);
  
          let formattedResponse = result.success ? "✅ " : "❌ ";
          formattedResponse += result.message + "\n\n";
  
          if (result.success) {
            formattedResponse += `Order #${result.order_id} has been cancelled.\n`;
            if (result.status) {
              formattedResponse += `Status: ${result.status}\n`;
            }
            formattedResponse += `Refund will be processed to: ${args.refund_channel}\n`;
  
            if (result.details) {
              formattedResponse += "\nAdditional Details:\n";
              Object.entries(result.details).forEach(([key, value]) => {
                formattedResponse += `   ${key}: ${value}\n`;
              });
            }
          }
  
          return {
            content: [
              {
                type: "text",
                text: formattedResponse,
              },
            ],
          };
        } catch (error: any) {
          logger.error("Failed to cancel order", error);
  
          return {
            content: [
              {
                type: "text",
                text: `Error cancelling order: ${error.message || "Unknown error"}`,
              },
            ],
          };
        }
      },
    );

• src/types/index.ts:286-292 (schema)

  TypeScript interface defining the shape of the API response for cancelOrder.

  export interface CancelOrderResponse {
    success: boolean;
    order_id: number;
    status?: string;
    message: string;
    details?: any;
  }

• src/api/client.ts:351-364 (helper)

  API client helper method that sends a DELETE request to /orders/{orderId} with a refund_channel query parameter to cancel an order.

  async cancelOrder(
    orderId: number,
    refundChannel: "wallet" | "card",
  ): Promise<CancelOrderResponse> {
    const response = await this.client.delete<CancelOrderResponse>(
      `/orders/${orderId}`,
      {
        params: {
          refund_channel: refundChannel,
        },
      },
    );
    return response.data;
  }

• src/tools/orders/index.ts:4-34 (registration)

  Registration point where cancelOrder tool is imported, registered alongside other order tools, and re-exported.

  import { registerCancelOrderTool } from "./cancelOrder.js";
  import { registerTrackAwbsByCarrierTool } from "./trackAwbsByCarrier.js";
  import { registerGenerateLabelLinkTool } from "./generateLabelLink.js";
  import { registerTrackOrdersByIdsTool } from "./trackOrdersByIds.js";
  import { registerPricingTools } from "./getPricing.js";
  import { registerCreateOrderTool } from "./createOrder.js";
  import { logger } from "../../utils/logger.js";
  
  export function registerOrderTools(server: McpServer): void {
    logger.info("Registering order tools...");
  
    // Register all order-related tools
    registerGetOrdersTool(server);
    registerGetOrderByIdTool(server);
    registerCancelOrderTool(server);
    registerTrackAwbsByCarrierTool(server);
    registerGenerateLabelLinkTool(server);
    registerTrackOrdersByIdsTool(server);
    registerCreateOrderTool(server);
  
    // Register pricing tools as well since they're order-related
    registerPricingTools(server);
  
    logger.info("All order tools registered successfully");
  }
  
  // Export individual registration functions if needed
  export { registerGetOrdersTool } from "./getOrders.js";
  export { registerCreateOrderTool } from "./createOrder.js";
  export { registerGetOrderByIdTool } from "./getOrderById.js";
  export { registerCancelOrderTool } from "./cancelOrder.js";

• src/tools/orders/cancelOrder.ts:17-24 (schema)

  Zod input schema for the cancelOrder tool defining order_id (string|number) and refund_channel ('wallet'|'card').

  inputSchema: {
    order_id: z
      .union([z.string(), z.number()])
      .describe("The order ID to cancel"),
    refund_channel: z
      .enum(["wallet", "card"])
      .describe("Where to process the refund: 'wallet' or 'card'"),
  },