Get Repayments
getRepaymentsRetrieve customer repayment details including AWB numbers, amounts, and delivery status for Europarcel shipping operations. Filter by order ID or paginate through results.
Instructions
Retrieves customer repayments with AWB details, amounts, and delivery status. Parameters: page (number), order_id (number - optional filter)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | Page number for pagination (1-1000, default: 1) | |
| order_id | No | Filter repayments by specific order ID (optional) |
Implementation Reference
- The core handler function for the 'getRepayments' MCP tool. It retrieves the API key, creates an EuroparcelApiClient, fetches repayments data, formats it nicely with pagination and status emojis, and returns a text response or error.
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 { logger.info("Fetching repayments", args); const response = await client.getRepayments({ page: args.page, order_id: args.order_id, }); logger.info(`Retrieved ${response.list.length} repayments`); let formattedResponse = `Found ${response.pagination.total} total repayments`; if (args.order_id) { formattedResponse += ` for order #${args.order_id}`; } formattedResponse += `\nPage ${response.pagination.current_page} of ${response.pagination.last_page}\n\n`; if (response.list.length === 0) { formattedResponse += "No repayments found."; } else { response.list.forEach((repayment: Repayment) => { formattedResponse += `📦 AWB: ${repayment.awb}\n`; formattedResponse += ` Order ID: ${repayment.order_id}\n`; formattedResponse += ` Carrier: ${repayment.carrier_name || repayment.carrier_id}\n`; formattedResponse += ` Recipient: ${repayment.recipient_name || "N/A"}\n`; formattedResponse += ` Amount: ${formatAmount(repayment.repayment_amount, repayment.repayment_currency)}\n`; formattedResponse += ` Status: ${formatStatus(repayment.status)}\n`; if (repayment.delivered_at) { formattedResponse += ` Delivered: ${repayment.delivered_at}\n`; } if (repayment.payout_id) { formattedResponse += ` Payout ID: ${repayment.payout_id}\n`; if (repayment.bank_iban) { formattedResponse += ` Bank: ${repayment.bank_holder || "N/A"} - ${repayment.bank_iban}\n`; } } formattedResponse += "\n"; }); // Add pagination info if there are more pages if (response.pagination.last_page > 1) { formattedResponse += `\nShowing ${response.list.length} of ${response.pagination.total} repayments`; if ( response.pagination.current_page < response.pagination.last_page ) { formattedResponse += `\nUse page: ${response.pagination.current_page + 1} to see more`; } } } return { content: [ { type: "text", text: formattedResponse, }, ], }; } catch (error: any) { logger.error("Failed to fetch repayments", error); return { content: [ { type: "text", text: `Error fetching repayments: ${error.message || "Unknown error"}`, }, ], }; } }, - Input schema using Zod for validating tool parameters: optional page (int 1-1000) and order_id (int >=1).
inputSchema: { page: z .number() .int() .min(1) .max(1000) .optional() .describe("Page number for pagination (1-1000, default: 1)"), order_id: z .number() .int() .min(1) .optional() .describe("Filter repayments by specific order ID (optional)"), }, - src/tools/repayments/getRepayments.ts:25-147 (registration)The registration function that sets up the 'getRepayments' tool on the MCP server, including name, schema, description, and handler.
export function registerGetRepaymentsTool(server: McpServer): void { // Create API client instance // Register getRepayments tool server.registerTool( "getRepayments", { title: "Get Repayments", description: "Retrieves customer repayments with AWB details, amounts, and delivery status. Parameters: page (number), order_id (number - optional filter)", inputSchema: { page: z .number() .int() .min(1) .max(1000) .optional() .describe("Page number for pagination (1-1000, default: 1)"), order_id: z .number() .int() .min(1) .optional() .describe("Filter repayments by specific order ID (optional)"), }, }, 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 { logger.info("Fetching repayments", args); const response = await client.getRepayments({ page: args.page, order_id: args.order_id, }); logger.info(`Retrieved ${response.list.length} repayments`); let formattedResponse = `Found ${response.pagination.total} total repayments`; if (args.order_id) { formattedResponse += ` for order #${args.order_id}`; } formattedResponse += `\nPage ${response.pagination.current_page} of ${response.pagination.last_page}\n\n`; if (response.list.length === 0) { formattedResponse += "No repayments found."; } else { response.list.forEach((repayment: Repayment) => { formattedResponse += `📦 AWB: ${repayment.awb}\n`; formattedResponse += ` Order ID: ${repayment.order_id}\n`; formattedResponse += ` Carrier: ${repayment.carrier_name || repayment.carrier_id}\n`; formattedResponse += ` Recipient: ${repayment.recipient_name || "N/A"}\n`; formattedResponse += ` Amount: ${formatAmount(repayment.repayment_amount, repayment.repayment_currency)}\n`; formattedResponse += ` Status: ${formatStatus(repayment.status)}\n`; if (repayment.delivered_at) { formattedResponse += ` Delivered: ${repayment.delivered_at}\n`; } if (repayment.payout_id) { formattedResponse += ` Payout ID: ${repayment.payout_id}\n`; if (repayment.bank_iban) { formattedResponse += ` Bank: ${repayment.bank_holder || "N/A"} - ${repayment.bank_iban}\n`; } } formattedResponse += "\n"; }); // Add pagination info if there are more pages if (response.pagination.last_page > 1) { formattedResponse += `\nShowing ${response.list.length} of ${response.pagination.total} repayments`; if ( response.pagination.current_page < response.pagination.last_page ) { formattedResponse += `\nUse page: ${response.pagination.current_page + 1} to see more`; } } } return { content: [ { type: "text", text: formattedResponse, }, ], }; } catch (error: any) { logger.error("Failed to fetch repayments", error); return { content: [ { type: "text", text: `Error fetching repayments: ${error.message || "Unknown error"}`, }, ], }; } }, ); logger.info("getRepayments tool registered successfully"); } - src/tools/repayments/index.ts:6-14 (registration)Higher-level registration function that calls registerGetRepaymentsTool among others.
export function registerRepaymentTools(server: McpServer): void { logger.info("Registering repayment tools..."); // Register all repayment-related tools registerGetRepaymentsTool(server); registerGetPayoutReportsTool(server); logger.info("All repayment tools registered successfully"); } - Helper to format repayment status strings with descriptive emojis.
function formatStatus(status: string): string { const statusMap: Record<string, string> = { pending: "⏳ Pending", processing: "🔄 Processing", paid: "✅ Paid", cancelled: "❌ Cancelled", failed: "⚠️ Failed", }; return statusMap[status] || status; } - Helper to format repayment amounts as currency strings.
function formatAmount(amount: number, currency: string): string { return `${amount.toFixed(2)} ${currency}`; }