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

Next Steps

For architecture design, see flexport-reference-architecture.