flexport-cost-tuning

name	flexport-cost-tuning
description	Optimize Flexport API usage costs through efficient pagination, caching, webhook-driven updates, and monitoring API call volume. Trigger: "flexport costs", "flexport API usage", "reduce flexport calls", "flexport billing".
allowed-tools	Read, Write, Edit
version	1.6.0
license	MIT
author	Jeremy Longshore <[e-mail]>
tags	["saas","logistics","flexport"]
compatibility	Designed for Claude Code

Flexport Cost Tuning

Overview

Reduce Flexport API costs by minimizing unnecessary calls. Key strategies: use webhooks instead of polling, cache aggressively, maximize page sizes, and batch operations.

Instructions

Strategy 1: Webhooks Over Polling

// BAD: Polling every 5 minutes (288 API calls/day per shipment)
setInterval(async () => {
  const shipment = await flexport(`/shipments/${id}`);
  if (shipment.data.status !== lastStatus) updateDB(shipment);
}, 5 * 60 * 1000);

// GOOD: Webhook-driven (0 API calls — Flexport pushes updates)
app.post('/webhooks/flexport', (req, res) => {
  const event = req.body;
  if (event.type === 'shipment.milestone') {
    updateDB(event.data);  // Only processes real changes
  }
  res.sendStatus(200);
});
// Savings: 100 shipments * 288 calls/day = 28,800 calls/day eliminated

Strategy 2: Maximize Page Size

// BAD: Default pagination (per=25)
// 1000 shipments = 40 API calls

// GOOD: Max pagination (per=100)
// 1000 shipments = 10 API calls (75% reduction)
const shipments = await flexport('/shipments?per=100&page=1');

Strategy 3: Cache with Smart TTLs

Data Type	Change Frequency	Cache TTL	Impact
Products	Rarely	1 hour	~95% fewer calls
Shipment list	Every few hours	5 minutes	~90% fewer calls
Shipment detail	On milestones	Until webhook	~99% fewer calls
Purchase orders	Daily	15 minutes	~85% fewer calls
Freight invoices	Monthly	1 hour	~95% fewer calls

Strategy 4: Monitor API Usage

// Track API call volume per endpoint
const apiMetrics = new Map<string, { count: number; lastReset: Date }>();

function trackAPICall(endpoint: string) {
  const key = endpoint.split('?')[0];  // Strip query params
  const metric = apiMetrics.get(key) || { count: 0, lastReset: new Date() };
  metric.count++;
  apiMetrics.set(key, metric);
}

// Report daily usage
function reportUsage() {
  console.log('=== Flexport API Usage ===');
  for (const [endpoint, { count }] of apiMetrics) {
    console.log(`  ${endpoint}: ${count} calls`);
  }
}

Cost Reduction Checklist

• Replace polling with webhooks for shipment tracking
• Use per=100 on all list endpoints
• Cache product catalog (1hr TTL)
• Cache shipment data, invalidate on webhooks
• Eliminate duplicate calls in page loads
• Monitor API call volume weekly

Resources

• Flexport Webhook Endpoints
• Flexport API Reference

Next Steps

For architecture design, see flexport-reference-architecture.