get_amazon_transactions
Fetch Amazon payment transactions to reconcile payments, track spending, or export for accounting. Scrapes the transactions page for date, order IDs, amount, payment method, and vendor details.
Instructions
Fetch all Amazon payment transactions from the dedicated transactions page. Faster than per-order extraction as it scrapes the infinite-scroll transactions list. Returns: date, order IDs, amount, payment method, card info (last 4 digits), vendor. Useful for reconciling payments, tracking spending, or exporting for accounting.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| region | Yes | Amazon region code | |
| start_date | No | Start date filter in ISO format (YYYY-MM-DD) | |
| end_date | No | End date filter in ISO format (YYYY-MM-DD) | |
| max_scrolls | No | Maximum scroll attempts to load more transactions. Default: 50. Increase for longer history. |
Implementation Reference
- Primary implementation of the tool logic: navigates to Amazon's transactions page, scrolls infinitely to load all transactions, extracts transaction data using multiple selector strategies, filters by date range if provided, deduplicates, sorts by date, and returns the list of transactions.export async function extractTransactionsFromPage( page: Page, region: string, options?: { startDate?: Date; endDate?: Date; maxScrolls?: number; onProgress?: (message: string, count: number) => void; }, ): Promise<Transaction[]> { const regionConfig = getRegionByCode(region); const currency = regionConfig?.currency || "USD"; const url = getTransactionsPageUrl(region); const { startDate, endDate, maxScrolls = 50, onProgress } = options || {}; // Navigate to transactions page onProgress?.("Loading transactions page...", 0); await page.goto(url, { waitUntil: "domcontentloaded", timeout: 30000 }); // Wait for transactions to load await page .waitForSelector( '[data-testid="transaction-link"], .transaction-date-container, .transactions-line-item', { timeout: 10000 }, ) .catch(() => {}); // Give initial content time to render await page.waitForTimeout(1000); let allTransactions: Transaction[] = []; let previousCount = 0; let scrollCount = 0; let stableCount = 0; // Scroll to load all transactions while (scrollCount < maxScrolls) { // Extract current transactions const pageTransactions = await extractVisibleTransactions(page, currency); // Merge with existing (deduplicate) allTransactions = mergeTransactions(allTransactions, pageTransactions); onProgress?.( `Found ${allTransactions.length} transactions...`, allTransactions.length, ); // Check if we've stopped finding new transactions if (allTransactions.length === previousCount) { stableCount++; if (stableCount >= 3) { // No new transactions after 3 scroll attempts break; } } else { stableCount = 0; } previousCount = allTransactions.length; // Check date range - stop if we've gone past the start date if (startDate && allTransactions.length > 0) { const oldestDate = Math.min( ...allTransactions.map((t) => t.date.getTime()), ); if (oldestDate < startDate.getTime()) { break; } } // Scroll down to load more await scrollToLoadMore(page); scrollCount++; // Wait for new content await page.waitForTimeout(500); } // Filter by date range if specified let filteredTransactions = allTransactions; if (startDate || endDate) { filteredTransactions = allTransactions.filter((t) => { if (startDate && t.date < startDate) return false; if (endDate && t.date > endDate) return false; return true; }); } // Sort by date descending (newest first) filteredTransactions.sort((a, b) => b.date.getTime() - a.date.getTime()); onProgress?.( `Complete: ${filteredTransactions.length} transactions`, filteredTransactions.length, ); return filteredTransactions; }
- src/index.ts:1159-1212 (handler)MCP server dispatch handler for the tool: validates region, prepares page and parameters, calls the extractor function, formats the JSON response with transaction data.case "get_amazon_transactions": { const regionParam = args?.region as string | undefined; const regionError = validateRegion(regionParam, args); if (regionError) return regionError; const region = regionParam!; const currentPage = await getPage(); const progressToken = request.params._meta?.progressToken; const startDate = args?.start_date as string | undefined; const endDate = args?.end_date as string | undefined; const maxScrolls = args?.max_scrolls as number | undefined; const transactions = await extractTransactionsFromPage( currentPage, region, { startDate: startDate ? new Date(startDate) : undefined, endDate: endDate ? new Date(endDate) : undefined, maxScrolls, onProgress: async (message, count) => { await sendProgress(progressToken, count, 0, message); }, }, ); return { content: [ { type: "text", text: JSON.stringify( { status: "success", params: { region, startDate, endDate, maxScrolls, }, transactionCount: transactions.length, transactions: transactions.map((t) => ({ date: t.date.toISOString(), orderIds: t.orderIds, amount: t.amount, cardInfo: t.cardInfo, vendor: t.vendor, })), }, null, 2, ), }, ], }; }
- src/index.ts:382-410 (schema)Input schema definition and tool metadata (name, description) used for MCP tool registration and validation.{ name: "get_amazon_transactions", description: "Fetch all Amazon payment transactions from the dedicated transactions page. Faster than per-order extraction as it scrapes the infinite-scroll transactions list. Returns: date, order IDs, amount, payment method, card info (last 4 digits), vendor. Useful for reconciling payments, tracking spending, or exporting for accounting.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, start_date: { type: "string", description: "Start date filter in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date filter in ISO format (YYYY-MM-DD)", }, max_scrolls: { type: "number", description: "Maximum scroll attempts to load more transactions. Default: 50. Increase for longer history.", }, }, required: ["region"], }, },
- src/index.ts:132-504 (registration)The tools array where get_amazon_transactions is registered with the MCP server.const tools: Tool[] = [ { name: "get_amazon_orders", description: "Fetch Amazon order history for a specified date range or year. Returns order summaries including: order ID, date, total amount, status, item count, shipping address (7 lines), payment method, and Subscribe & Save frequency. Optionally includes detailed item data (ASIN, name, price, quantity, seller, condition) and shipment tracking. Use for browsing order history or building reports.", inputSchema: { type: "object", properties: { region: { type: "string", description: `Amazon region code. Supported: ${getRegionCodes().join(", ")}`, enum: getRegionCodes(), }, year: { type: "number", description: "Year to fetch orders from (e.g., 2024). If omitted, uses current year.", }, start_date: { type: "string", description: "Start date in ISO format (YYYY-MM-DD). Overrides year if provided.", }, end_date: { type: "string", description: "End date in ISO format (YYYY-MM-DD). Overrides year if provided.", }, include_items: { type: "boolean", description: "Extract item details (ASIN, name, price, quantity, seller, condition) from each order's invoice page. Adds ~2s per order.", default: false, }, include_shipments: { type: "boolean", description: "Extract shipment info (delivery status, tracking link) from each order's detail page. Adds ~2s per order. Note: tracking link URL is captured but not the carrier tracking number - use fetch_tracking_numbers for that.", default: false, }, fetch_tracking_numbers: { type: "boolean", description: "Extract actual carrier tracking numbers (e.g., AZ218181365JE) by visiting each shipment's 'Track package' page. Adds ~2s per shipment. Only works when include_shipments is true.", default: false, }, max_orders: { type: "number", description: "Maximum number of orders to fetch. Use to limit results for large accounts or avoid timeouts.", }, }, required: ["region"], }, }, { name: "get_amazon_order_details", description: "Get comprehensive details for a specific Amazon order by order ID. Returns full order data including: items (ASIN, name, price, quantity, seller, condition), financial breakdown (subtotal, shipping, tax, VAT, promotions, total), shipping address, payment methods, and optionally shipment tracking and transaction history.", inputSchema: { type: "object", properties: { order_id: { type: "string", description: "Amazon order ID in format XXX-XXXXXXX-XXXXXXX (e.g., 123-4567890-1234567)", }, region: { type: "string", description: "Amazon region code where the order was placed", enum: getRegionCodes(), }, include_shipments: { type: "boolean", description: "Extract shipment info from order detail page (default: true)", default: true, }, fetch_tracking_numbers: { type: "boolean", description: "Extract actual carrier tracking number (e.g., AZ218181365JE) by visiting the 'Track package' page. Adds ~2s per shipment.", default: false, }, include_transactions: { type: "boolean", description: "Include payment transaction details (default: false)", default: false, }, }, required: ["order_id", "region"], }, }, { name: "export_amazon_orders_csv", description: "Export Amazon orders summary to CSV file. Fast extraction from order list page (~0.5s per 10 orders). CSV columns: Order ID, Date, Total, Status, Item Count, Address (7 lines), Subscribe & Save, Platform, Region, Order URL. Defaults to ~/Downloads with auto-generated filename. For large accounts (500+ orders), use max_orders to batch exports and avoid timeouts.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, year: { type: "number", description: "Year to export (defaults to current year)", }, start_date: { type: "string", description: "Start date in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date in ISO format (YYYY-MM-DD)", }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-orders-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to export. Recommended: 100-200 per batch for large accounts.", }, }, required: ["region"], }, }, { name: "export_amazon_items_csv", description: "Export detailed Amazon order items to CSV file. Visits each order's invoice page to extract item-level data (~2s/order). CSV columns: Order ID, Date, ASIN, Product Name, Condition, Quantity, Unit Price, Item Total, Seller, Subscribe & Save, Order financials (Subtotal, Shipping, Tax, VAT, Promotion, Total), Status, Address (7 lines), Payment Method, Product URL, Order URL, Region. Ideal for expense tracking, inventory analysis, or accounting exports.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, year: { type: "number", description: "Year to export (defaults to current year)", }, start_date: { type: "string", description: "Start date in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date in ISO format (YYYY-MM-DD)", }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-items-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to process. Recommended: 50-100 per batch due to ~2s/order extraction time.", }, }, required: ["region"], }, }, { name: "export_amazon_shipments_csv", description: "Export Amazon shipment tracking data to CSV file. Visits each order's detail page to extract tracking info (~4s/order). CSV columns: Order ID, Date, Shipment ID, Status, Delivered (Yes/No/Unknown), Tracking ID, Tracking URL, Items in Shipment, Item Names, Payment Amount, Refund. Useful for tracking deliveries and reconciling shipments.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, year: { type: "number", description: "Year to export (defaults to current year)", }, start_date: { type: "string", description: "Start date in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date in ISO format (YYYY-MM-DD)", }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-shipments-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to process. Recommended: 25-50 per batch due to ~4s/order extraction time.", }, fetch_tracking_numbers: { type: "boolean", description: "Extract actual carrier tracking numbers (e.g., AZ218181365JE) by visiting each shipment's 'Track package' page. Adds ~2s per shipment.", default: false, }, }, required: ["region"], }, }, { name: "export_amazon_transactions_csv", description: "Export Amazon payment transactions to CSV file. Extracts transaction data from each order's detail page. CSV columns include: date, order ID, amount, payment method, card info. For faster bulk transaction export, consider get_amazon_transactions which scrapes the dedicated transactions page.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, year: { type: "number", description: "Year to export (defaults to current year)", }, start_date: { type: "string", description: "Start date in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date in ISO format (YYYY-MM-DD)", }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-transactions-{year}-{date}.csv", }, max_orders: { type: "number", description: "Maximum number of orders to process", }, }, required: ["region"], }, }, { name: "get_amazon_transactions", description: "Fetch all Amazon payment transactions from the dedicated transactions page. Faster than per-order extraction as it scrapes the infinite-scroll transactions list. Returns: date, order IDs, amount, payment method, card info (last 4 digits), vendor. Useful for reconciling payments, tracking spending, or exporting for accounting.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, start_date: { type: "string", description: "Start date filter in ISO format (YYYY-MM-DD)", }, end_date: { type: "string", description: "End date filter in ISO format (YYYY-MM-DD)", }, max_scrolls: { type: "number", description: "Maximum scroll attempts to load more transactions. Default: 50. Increase for longer history.", }, }, required: ["region"], }, }, { name: "get_amazon_gift_card_balance", description: "Get current Amazon gift card balance and transaction history. Returns: current balance, last updated timestamp, and paginated transaction history (date, description, amount, closing balance, type, associated order ID, claim code, serial number). Supports fetching complete history across multiple pages.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, max_pages: { type: "number", description: "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.", default: 10, }, fetch_all_pages: { type: "boolean", description: "Automatically paginate through all available transaction history. Default: true.", default: true, }, }, required: ["region"], }, }, { name: "export_amazon_gift_cards_csv", description: "Export Amazon gift card transaction history to CSV file. CSV columns: Date, Description, Amount, Closing Balance, Type (credit/debit), Order ID, Claim Code, Serial Number, Region. Useful for tracking gift card usage and reconciling balances.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, output_path: { type: "string", description: "Full path to save CSV file. Defaults to ~/Downloads/amazon-{region}-gift-cards-{date}.csv", }, max_pages: { type: "number", description: "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.", default: 10, }, }, required: ["region"], }, }, { name: "get_amazon_gift_card_transactions", description: "Get Amazon gift card transaction history with full details. Returns: current balance, transaction count, and detailed transactions (date, description, amount, closing balance, transaction type, order ID, claim code, serial number). Supports pagination for complete history.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code", enum: getRegionCodes(), }, max_pages: { type: "number", description: "Maximum pages of transaction history to fetch. Default: 10. Set to 0 for unlimited.", default: 10, }, }, required: ["region"], }, }, { name: "check_amazon_auth_status", description: "Check if the browser session is authenticated with Amazon for a specific region. Returns authentication status (authenticated/not authenticated), current URL, and any error messages. Use this to verify login status before running other tools, or to prompt user to log in if session expired.", inputSchema: { type: "object", properties: { region: { type: "string", description: "Amazon region code to check authentication for", enum: getRegionCodes(), }, }, required: ["region"], }, }, ];
- Helper function that orchestrates extraction strategies to parse visible transactions from the page DOM.async function extractVisibleTransactions( page: Page, currency: string, ): Promise<Transaction[]> { // Try Strategy 0 (transaction-date-container based) let transactions = await extractStrategy0(page, currency); if (transactions.length > 0) { return transactions; } // Try Strategy 1 (component-based parsing) transactions = await extractStrategy1(page, currency); if (transactions.length > 0) { return transactions; } // Fallback: generic extraction return extractGeneric(page, currency); }