Flexport Cost Tuning Skill

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.

Agent Skills: Flexport Cost Tuning

Install this agent skill to your local

Skill Files