Amazon Order History CSV Download MCP

Instructions

Implementation Reference

• src/tools/fetch-orders.ts:101-948 (handler)

  Core handler function that orchestrates the entire process of fetching Amazon orders: navigates to order history pages, handles pagination, extracts order summaries from list view, and conditionally visits individual order detail/invoice pages to extract items, shipments, tracking numbers, and transactions using Playwright selectors.
  export async function fetchOrders( page: Page, plugin: AmazonPlugin, options: FetchOrdersOptions, ): Promise<FetchOrdersResult> { const { region, year, startDate, endDate, includeItems = false, includeShipments = false, includeTransactions = false, fetchTrackingNumbers = false, useInvoice = true, // Default to invoice extraction (faster) maxOrders, orderId, onProgress, } = options; const result: FetchOrdersResult = { orders: [], items: [], shipments: [], transactions: [], totalFound: 0, errors: [], }; const regionConfig = getRegionByCode(region); if (!regionConfig) { result.errors.push( `Unknown region: ${region}. Valid regions: us, uk, ca, de, fr, es, it, nl, jp, au, mx, in, ae, sa, ie, be`, ); return result; } const domain = regionConfig.domain; const currency = regionConfig.currency || "USD"; const currencySymbol = currency === "GBP" ? "£" : currency === "EUR" ? "€" : "$"; try { // If specific orderId requested, skip order list and go directly to invoice/detail if (orderId) { console.error( `[fetch-orders] Fetching single order: ${orderId} (region: ${region})`, ); onProgress?.(`Fetching order ${orderId}...`, 0, 1); // Create header for this order const header: OrderHeader = { id: orderId, orderId, date: null, total: { amount: 0, currency, currencySymbol, formatted: "" }, detailUrl: `https://www.${domain}/gp/your-account/order-details?orderID=${orderId}`, platform: "amazon", region, }; const enrichedOrder: EnrichedOrder = { ...header }; // Go to invoice page and extract items directly (inline, with timeouts) const invoiceUrl = `https://www.${domain}/gp/css/summary/print.html?orderID=${orderId}`; console.error(`[fetch-orders] Navigating to invoice: ${invoiceUrl}`); await page.goto(invoiceUrl, { waitUntil: "domcontentloaded", timeout: 15000, }); const currentUrl = page.url(); console.error(`[fetch-orders] Current URL: ${currentUrl}`); await page .waitForSelector('[data-component="purchasedItems"], table, .a-box', { timeout: 3000, }) .catch(() => {}); // Check for error banners (e.g., "We're unable to load your order details") const errorBanner = await page .locator( '[data-component="errorbanner"], .a-alert-error, .a-alert-info', ) .first(); const errorBannerCount = await errorBanner.count().catch(() => 0); if (errorBannerCount > 0) { const errorText = await errorBanner .textContent({ timeout: 500 }) .catch(() => ""); if ( errorText?.includes("unable to load") || errorText?.includes("problem loading") ) { console.error( `[fetch-orders] Error detected: ${errorText.slice(0, 200)}`, ); result.errors.push( `Order page error: ${errorText.slice(0, 200).trim()}`, ); } } // Try to extract items - first try data-component, then fall back to extractFromInvoice const itemContainers = await page .locator('[data-component="purchasedItems"]') .all(); console.error( `[fetch-orders] Found ${itemContainers.length} purchasedItems containers on invoice page`, ); // Invoice pages often don't have data-component, try the full invoice extractor if (itemContainers.length === 0) { console.error( `[fetch-orders] No data-component items found, using extractFromInvoice`, ); const invoiceData = await extractFromInvoice(page, header); // Copy over invoice data (amounts, recipient, payments) regardless of items console.error( `[fetch-orders] Invoice data: subtotal=${invoiceData.subtotal?.formatted}, total=${invoiceData.total?.formatted}, vat=${invoiceData.vat?.formatted}, shipping=${invoiceData.shipping?.formatted}`, ); if (invoiceData.subtotal) enrichedOrder.subtotal = invoiceData.subtotal; if (invoiceData.total) enrichedOrder.grandTotal = invoiceData.total; if (invoiceData.shipping) enrichedOrder.shipping = invoiceData.shipping; if (invoiceData.tax) enrichedOrder.tax = invoiceData.tax; if (invoiceData.vat) enrichedOrder.vat = invoiceData.vat; if (invoiceData.gift) enrichedOrder.promotion = invoiceData.gift; if (invoiceData.recipientName) { enrichedOrder.recipient = invoiceData.recipientName; if (invoiceData.shippingAddress) { // Prepend recipient name as line1 if address doesn't start with it const addressWithName = [ invoiceData.recipientName, ...invoiceData.shippingAddress, ]; enrichedOrder.shippingAddress = parseInvoiceAddressLines(addressWithName); } } if (invoiceData.payments && invoiceData.payments.length > 0) { enrichedOrder.payments = invoiceData.payments; // Also set paymentMethod from first payment const firstPayment = invoiceData.payments[0]; enrichedOrder.paymentMethod = { type: firstPayment.method, lastFour: firstPayment.lastFour, }; } // Convert invoice items to full Item type if found if (invoiceData.items && invoiceData.items.length > 0) { // Create enriched header with all order data for items const enrichedHeader: OrderHeader = { ...header, recipient: typeof enrichedOrder.recipient === "string" ? enrichedOrder.recipient : undefined, subtotal: enrichedOrder.subtotal, shipping: enrichedOrder.shipping, tax: enrichedOrder.tax, vat: enrichedOrder.vat, promotion: enrichedOrder.promotion, grandTotal: enrichedOrder.grandTotal, shippingAddress: enrichedOrder.shippingAddress, paymentMethod: enrichedOrder.paymentMethod, }; const items = invoiceData.items.map((ii) => ({ id: ii.asin || ii.name.slice(0, 50), asin: ii.asin, name: ii.name, quantity: ii.quantity, unitPrice: ii.unitPrice, totalPrice: { ...ii.unitPrice, amount: ii.unitPrice.amount * ii.quantity, formatted: `${currencySymbol}${(ii.unitPrice.amount * ii.quantity).toFixed(2)}`, }, url: ii.asin ? `https://www.${domain}/dp/${ii.asin}` : "", orderHeader: enrichedHeader, condition: ii.condition, seller: ii.seller ? { name: ii.seller } : undefined, subscriptionFrequency: ii.subscriptionFrequency, platformData: { source: "invoice" }, })); console.error( `[fetch-orders] extractFromInvoice found ${items.length} items`, ); enrichedOrder.items = items; result.items = items; } } // Only use inline extraction if we found data-component containers (detail page) // Otherwise extractFromInvoice already handled it above if (itemContainers.length > 0) { // Create enriched header with all order data for items const enrichedHeader: OrderHeader = { ...header, recipient: typeof enrichedOrder.recipient === "string" ? enrichedOrder.recipient : undefined, subtotal: enrichedOrder.subtotal, shipping: enrichedOrder.shipping, tax: enrichedOrder.tax, vat: enrichedOrder.vat, promotion: enrichedOrder.promotion, grandTotal: enrichedOrder.grandTotal, shippingAddress: enrichedOrder.shippingAddress, paymentMethod: enrichedOrder.paymentMethod, }; const extractedItems: Item[] = []; for (const container of itemContainers) { try { // Title + ASIN const titleLink = container .locator('[data-component="itemTitle"] a') .first(); const titleCount = await titleLink.count().catch(() => 0); if (titleCount === 0) continue; const name = await titleLink .textContent({ timeout: 500 }) .catch(() => ""); if (!name?.trim()) continue; const href = await titleLink .getAttribute("href", { timeout: 500 }) .catch(() => ""); const asinMatch = href?.match(/\/dp\/([A-Z0-9]+)/i); const asin = asinMatch ? asinMatch[1] : undefined; // Price const priceEl = container .locator('[data-component="unitPrice"] .a-offscreen') .first(); const priceText = await priceEl .textContent({ timeout: 500 }) .catch(() => ""); const priceMatch = priceText?.match(/[£$€]?([\d,.]+)/); const priceAmount = priceMatch ? parseFloat(priceMatch[1].replace(",", "")) : 0; // Quantity (check badge first, then quantity component) let quantity = 1; const qtyBadge = container .locator(".od-item-view-qty span") .first(); const qtyBadgeCount = await qtyBadge.count().catch(() => 0); if (qtyBadgeCount > 0) { const qtyText = await qtyBadge .textContent({ timeout: 500 }) .catch(() => ""); const qtyMatch = qtyText?.match(/(\d+)/); if (qtyMatch) quantity = parseInt(qtyMatch[1], 10); } // Seller let seller: string | undefined; const sellerEl = container .locator('[data-component="orderedMerchant"]') .first(); const sellerCount = await sellerEl.count().catch(() => 0); if (sellerCount > 0) { const sellerText = await sellerEl .textContent({ timeout: 500 }) .catch(() => ""); const sellerMatch = sellerText?.match(/Sold by:\s*(.+)/i); if (sellerMatch) seller = sellerMatch[1].trim(); } // Condition let condition: string | undefined; const condEl = container .locator('[data-component="itemCondition"]') .first(); const condCount = await condEl.count().catch(() => 0); if (condCount > 0) { const condText = await condEl .textContent({ timeout: 500 }) .catch(() => ""); const condMatch = condText?.match(/Condition:\s*(.+)/i); if (condMatch) condition = condMatch[1].trim(); } // Subscription frequency let subscriptionFrequency: string | undefined; const freqEl = container .locator('[data-component="deliveryFrequency"]') .first(); const freqCount = await freqEl.count().catch(() => 0); if (freqCount > 0) { const freqText = await freqEl .textContent({ timeout: 500 }) .catch(() => ""); const freqMatch = freqText?.match(/Auto-delivered:\s*(.+)/i); if (freqMatch) subscriptionFrequency = freqMatch[1].trim(); } extractedItems.push({ id: asin || name.trim().slice(0, 50), asin, name: name.trim(), quantity, unitPrice: { amount: priceAmount, currency, currencySymbol, formatted: `${currencySymbol}${priceAmount.toFixed(2)}`, }, totalPrice: { amount: priceAmount * quantity, currency, currencySymbol, formatted: `${currencySymbol}${(priceAmount * quantity).toFixed(2)}`, }, url: asin ? `https://www.${domain}/dp/${asin}` : "", orderHeader: enrichedHeader, condition, seller: seller ? { name: seller } : undefined, subscriptionFrequency, platformData: { source: "invoice" }, }); } catch { continue; } } console.error( `[fetch-orders] Extracted ${extractedItems.length} items from data-component`, ); // Store items if (extractedItems.length > 0) { enrichedOrder.items = extractedItems; result.items = extractedItems; } } // If no items found from invoice, try the detail page if (result.items.length === 0 && result.errors.length === 0) { console.error( `[fetch-orders] No items from invoice, trying detail page extraction`, ); await page.goto(header.detailUrl, { waitUntil: "domcontentloaded", timeout: 15000, }); await page .waitForSelector('[data-component="purchasedItems"], .a-box', { timeout: 2000, }) .catch(() => {}); // Check for error banners on detail page const detailErrorBanner = await page .locator( '[data-component="errorbanner"], .a-alert-error, .a-alert-info', ) .first(); const detailErrorCount = await detailErrorBanner.count().catch(() => 0); if (detailErrorCount > 0) { const errorText = await detailErrorBanner .textContent({ timeout: 500 }) .catch(() => ""); if ( errorText?.includes("unable to load") || errorText?.includes("problem loading") ) { console.error( `[fetch-orders] Detail page error: ${errorText.slice(0, 200)}`, ); result.errors.push( `Order detail error: ${errorText.slice(0, 200).trim()}`, ); } } if (result.errors.length === 0) { const items = await plugin.extractItems(page, header).catch(() => []); if (items.length > 0) { console.error( `[fetch-orders] Found ${items.length} items from detail page`, ); enrichedOrder.items = items; result.items = items; } } } // Get shipments from detail page if requested if (includeShipments) { console.error(`[fetch-orders] Fetching shipments from detail page`); // Only navigate if not already there if (!page.url().includes("order-details")) { await page.goto(header.detailUrl, { waitUntil: "domcontentloaded", timeout: 15000, }); await page .waitForSelector('[data-component="shipments"], .a-box', { timeout: 2000, }) .catch(() => {}); } const shipments = await plugin .extractShipments(page, header, fetchTrackingNumbers) .catch(() => []); enrichedOrder.shipments = shipments; result.shipments = shipments; console.error(`[fetch-orders] Found ${shipments.length} shipments`); } // Get transactions if requested if (includeTransactions) { const transactions = await plugin .extractTransactions(page, header) .catch(() => []); result.transactions = transactions; console.error( `[fetch-orders] Found ${transactions.length} transactions`, ); } result.orders = [enrichedOrder]; result.totalFound = 1; return result; } // Build order list URL (for multi-order fetch) const listUrl = plugin.getOrderListUrl(region, { year, startDate: startDate ? new Date(startDate) : undefined, endDate: endDate ? new Date(endDate) : undefined, }); // Navigate to order list console.error(`[fetch-orders] Navigating to: ${listUrl}`); onProgress?.("Navigating to order history...", 0, 0); await page.goto(listUrl, { waitUntil: "domcontentloaded", timeout: 60000 }); // Wait for order cards to appear (more reliable than fixed timeout) await page .waitForSelector('.order-card, [class*="order-card"], .a-box-group', { timeout: 3000, }) .catch(() => {}); console.error(`[fetch-orders] Page loaded, URL: ${page.url()}`); // Check authentication console.error(`[fetch-orders] Checking auth...`); const authStatus = await plugin.checkAuthStatus(page, region); console.error(`[fetch-orders] Auth result: ${JSON.stringify(authStatus)}`); if (!authStatus.authenticated) { result.errors.push(`Not authenticated: ${authStatus.message}`); return result; } // Extract orders from all pages let pageNum = 1; let hasMore = true; while (hasMore) { console.error(`[fetch-orders] Extracting page ${pageNum}...`); onProgress?.( `Extracting orders from page ${pageNum}...`, result.orders.length, 0, ); // Extract order headers from current page const pageHeaders = await extractOrderHeaders(page, region); console.error( `[fetch-orders] Found ${pageHeaders.length} orders on page ${pageNum}`, ); // Cast to the enriched type for result storage result.orders.push(...(pageHeaders as EnrichedOrder[])); onProgress?.( `Found ${result.orders.length} orders (page ${pageNum})...`, result.orders.length, 0, ); // Check if we've hit the max if (maxOrders && result.orders.length >= maxOrders) { result.orders = result.orders.slice(0, maxOrders); break; } // Check for next page hasMore = await hasNextPage(page); console.error(`[fetch-orders] Has next page: ${hasMore}`); if (hasMore && result.orders.length < (maxOrders || 1000)) { const navigated = await goToNextPage(page); console.error(`[fetch-orders] Navigated to next: ${navigated}`); if (!navigated) break; pageNum++; } else { hasMore = false; } } result.totalFound = result.orders.length; const extractionMode = useInvoice ? "invoice" : "detail"; onProgress?.( `Found ${result.totalFound} orders, starting ${extractionMode} extraction...`, 0, result.totalFound, ); // If detailed extraction requested, visit each order if (includeItems || includeShipments || includeTransactions) { const startTime = Date.now(); let processedCount = 0; for (let i = 0; i < result.orders.length; i++) { const order = result.orders[i]; // Calculate ETA based on average time per order const elapsed = Date.now() - startTime; const avgTimePerOrder = processedCount > 0 ? elapsed / processedCount : useInvoice ? 1500 : 3000; const remaining = result.orders.length - i; const etaSeconds = Math.round((avgTimePerOrder * remaining) / 1000); const etaStr = etaSeconds > 60 ? `~${Math.round(etaSeconds / 60)}m ${etaSeconds % 60}s` : `~${etaSeconds}s`; console.error( `[fetch-orders] Processing order ${i + 1}/${result.orders.length}: ${order.id} (${extractionMode} mode)`, ); onProgress?.( `Order ${i + 1}/${result.orders.length} (${order.id}) - ETA: ${etaStr}`, i + 1, result.orders.length, ); // Skip cancelled orders - they have no useful detail to extract const orderStatus = order.status?.label?.toLowerCase() || ""; if (orderStatus === "cancelled") { console.error(`[fetch-orders] Skipping cancelled order ${order.id}`); order.items = []; processedCount++; continue; } // Create header for extraction functions let recipientStr: string | undefined; if (typeof order.recipient === "string") { recipientStr = order.recipient; } else if ( order.recipient && typeof order.recipient === "object" && "name" in order.recipient ) { recipientStr = (order.recipient as { name: string }).name; } const header: OrderHeader = { id: order.id, orderId: order.orderId, date: order.date, total: order.total, detailUrl: order.detailUrl, recipient: recipientStr, platform: order.platform, region: order.region, }; try { if (useInvoice) { // Invoice-based extraction (faster, cleaner HTML) console.error( `[fetch-orders] Using invoice extraction for ${order.id}`, ); onProgress?.( `Order ${i + 1}/${result.orders.length} - Loading invoice...`, i, result.orders.length, ); const invoiceData = await extractFromInvoice(page, header); // Merge all invoice data into order (amounts, recipient, payments) if (invoiceData.subtotal) order.subtotal = invoiceData.subtotal; if (invoiceData.shipping) order.shipping = invoiceData.shipping; if (invoiceData.tax) order.tax = invoiceData.tax; if (invoiceData.vat) order.vat = invoiceData.vat; if (invoiceData.total) order.grandTotal = invoiceData.total; if (invoiceData.gift) order.promotion = invoiceData.gift; if (invoiceData.payments && invoiceData.payments.length > 0) { order.payments = invoiceData.payments; // Also set paymentMethod from first payment const firstPayment = invoiceData.payments[0]; order.paymentMethod = { type: firstPayment.method, lastFour: firstPayment.lastFour, }; } if (invoiceData.recipientName) { order.recipient = invoiceData.recipientName; if (invoiceData.shippingAddress) { // Prepend recipient name as line1 if address doesn't start with it const addressWithName = [ invoiceData.recipientName, ...invoiceData.shippingAddress, ]; order.shippingAddress = parseInvoiceAddressLines(addressWithName); } } // Extract items from invoice if requested if (includeItems) { // Create enriched header with all order data for items // This includes shippingAddress, status, etc. that were merged above const enrichedHeader: OrderHeader = { id: order.id, orderId: order.orderId, date: order.date, total: order.total, detailUrl: order.detailUrl, recipient: recipientStr, status: order.status, platform: order.platform, region: order.region, subtotal: order.subtotal, shipping: order.shipping, tax: order.tax, vat: order.vat, promotion: order.promotion, grandTotal: order.grandTotal, shippingAddress: order.shippingAddress, paymentMethod: order.paymentMethod, subscribeAndSave: order.subscribeAndSave, }; // Check if invoice has items and matches expected count from order list const expectedItemCount = order.itemCount || 0; const invoiceItemCount = invoiceData.items?.length || 0; if ( invoiceData.items && invoiceItemCount > 0 && (expectedItemCount === 0 || invoiceItemCount >= expectedItemCount) ) { // Invoice has items and count looks correct - use invoice data const items = invoiceData.items.map((ii) => ({ id: ii.asin || ii.name.slice(0, 50), asin: ii.asin, name: ii.name, quantity: ii.quantity, unitPrice: ii.unitPrice, totalPrice: { ...ii.unitPrice, amount: ii.unitPrice.amount * ii.quantity, }, url: ii.asin ? `https://www.${regionConfig.domain}/dp/${ii.asin}` : "", orderHeader: enrichedHeader, condition: ii.condition, seller: ii.seller ? { name: ii.seller } : undefined, subscriptionFrequency: ii.subscriptionFrequency, platformData: { source: "invoice" }, })); console.error( `[fetch-orders] Found ${items.length} items from invoice (expected ${expectedItemCount})`, ); result.items.push(...items); order.items = items; } else { // Fallback to detail page if: // - Invoice extraction found no items, OR // - Invoice item count doesn't match expected count from order list console.error( `[fetch-orders] Invoice has ${invoiceItemCount} items but expected ${expectedItemCount}, falling back to detail page`, ); await page.goto(order.detailUrl, { waitUntil: "domcontentloaded", timeout: 15000, }); await page .waitForSelector('.a-box, [data-component="orderDetails"]', { timeout: 1000, }) .catch(() => {}); const items = await plugin .extractItems(page, enrichedHeader) .catch(() => []); console.error( `[fetch-orders] Found ${items.length} items from detail page`, ); result.items.push(...items); order.items = items; } } // Shipments need detail page (not on invoice) if (includeShipments) { console.error( `[fetch-orders] Fetching shipments from detail page`, ); onProgress?.( `Order ${i + 1}/${result.orders.length} - Fetching shipments...`, i, result.orders.length, ); await page.goto(order.detailUrl, { waitUntil: "domcontentloaded", timeout: 15000, }); await page .waitForSelector( '[data-component="shipments"], .shipment-is-delivered, .a-box', { timeout: 1000 }, ) .catch(() => {}); const shipments = await plugin .extractShipments(page, header, fetchTrackingNumbers) .catch(() => []); result.shipments.push(...shipments); order.shipments = shipments; } // Transactions from detail page if (includeTransactions) { if (!includeShipments) { await page.goto(order.detailUrl, { waitUntil: "domcontentloaded", timeout: 15000, }); } const transactions = await plugin .extractTransactions(page, header) .catch(() => []); result.transactions.push(...transactions); } processedCount++; } else { // Detail page extraction (original method) console.error(`[fetch-orders] Navigating to: ${order.detailUrl}`); onProgress?.( `Order ${i + 1}/${result.orders.length} - Loading details...`, i, result.orders.length, ); await page.goto(order.detailUrl, { waitUntil: "domcontentloaded", timeout: 30000, }); await page .waitForSelector( '#od-subtotals, [data-component="orderDetails"], .order-details, .a-box', { timeout: 1500 }, ) .catch(() => {}); console.error(`[fetch-orders] Page loaded for order ${order.id}`); // Run extractions in parallel for speed const extractionPromises: Promise<void>[] = []; // Order details extraction extractionPromises.push( extractOrderDetails(page, region) .then((details) => { Object.assign(order, details); console.error(`[fetch-orders] Order details extracted`); }) .catch(() => {}), ); // Items extraction if (includeItems) { extractionPromises.push( plugin .extractItems(page, header) .then((items) => { console.error(`[fetch-orders] Found ${items.length} items`); result.items.push(...items); order.items = items; }) .catch(() => { order.items = []; }), ); } // Shipments extraction if (includeShipments) { extractionPromises.push( plugin .extractShipments(page, header, fetchTrackingNumbers) .then((shipments) => { result.shipments.push(...shipments); order.shipments = shipments; }) .catch(() => {}), ); } // Transactions extraction if (includeTransactions) { extractionPromises.push( plugin .extractTransactions(page, header) .then((transactions) => { result.transactions.push(...transactions); }) .catch(() => {}), ); } // Wait for all extractions to complete await Promise.all(extractionPromises); processedCount++; } } catch (error) { result.errors.push(`Error extracting order ${order.id}: ${error}`); processedCount++; } } } onProgress?.( `Complete! ${result.orders.length} orders, ${result.items.length} items`, result.orders.length, result.orders.length, ); return result; } catch (error) { result.errors.push(`Fetch error: ${error}`); return result; } }
• src/index.ts:133-186 (registration)

  Tool registration in the MCP tools array, including name, description, and input schema.
  { 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"], }, },
• src/index.ts:137-184 (schema)

  Input schema defining parameters for the get_amazon_orders tool: region (required), year, dates, include flags, max_orders.
  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"],
• src/index.ts:648-750 (registration)

  Switch case dispatcher that handles the tool call, validates region, invokes fetchOrders, and formats the JSON response.
  case "get_amazon_orders": { const regionParam = args?.region as string | undefined; const regionError = validateRegion(regionParam, args); if (regionError) return regionError; const region = regionParam!; // Validated above // Get progress token from request meta const progressToken = request.params._meta?.progressToken; const currentPage = await getPage(); const result = await fetchOrders(currentPage, amazonPlugin, { region, year: args?.year as number | undefined, startDate: args?.start_date as string | undefined, endDate: args?.end_date as string | undefined, includeItems: args?.include_items as boolean | undefined, includeShipments: args?.include_shipments as boolean | undefined, fetchTrackingNumbers: args?.fetch_tracking_numbers as | boolean | undefined, maxOrders: args?.max_orders as number | undefined, onProgress: async (message, current, total) => { await sendProgress(progressToken, current, total, message); }, }); return { content: [ { type: "text", text: JSON.stringify( { status: "success", // Echo input parameters for debugging params: { region, year: args?.year, startDate: args?.start_date, endDate: args?.end_date, includeItems: args?.include_items, includeShipments: args?.include_shipments, fetchTrackingNumbers: args?.fetch_tracking_numbers, maxOrders: args?.max_orders, }, totalOrders: result.totalFound, orders: result.orders.map((o) => ({ id: o.id, date: o.date?.toISOString(), total: o.total, status: o.status?.label || "Unknown", // Use itemCount from order header (extracted from list page) or fall back to items array length itemCount: o.itemCount ?? o.items?.length ?? 0, shipmentCount: o.shipments?.length || 0, // Enhanced order header data from list page subtotal: o.subtotal, shipping: o.shipping, tax: o.tax, vat: o.vat, promotion: o.promotion, grandTotal: o.grandTotal, // Shipping address shippingAddress: o.shippingAddress, // Payment method from list page paymentMethod: o.paymentMethod, // Recipient (simple name) recipient: typeof o.recipient === "object" ? o.recipient : { name: o.recipient }, // Payments from detail/invoice payments: o.payments, // Include items when extracted items: o.items?.map((i) => ({ name: i.name, asin: i.asin, quantity: i.quantity, unitPrice: i.unitPrice, condition: i.condition, seller: i.seller?.name, subscriptionFrequency: i.subscriptionFrequency, })), // Include shipments when extracted shipments: o.shipments?.map((s) => ({ shipmentId: s.shipmentId, status: s.status, delivered: s.delivered, trackingId: s.trackingId, carrier: s.carrier, trackingLink: s.trackingLink, itemCount: s.items?.length || 0, })), })), itemCount: result.items.length, shipmentCount: result.shipments.length, errors: result.errors, }, null, 2, ), }, ], }; }