Installation

Open Claude Code and run this command:

/plugin install flexport-pack@claude-code-plugins-plus

Use --global to install for all projects, or --project for current project only.

Skills (24)

flexport-ci-integration SKILL.md View full skill →

Configure CI/CD pipelines for Flexport logistics integrations with GitHub Actions, automated API contract testing, and deployment workflows.

ReadWriteEditBash(npm:*)Grep

Flexport CI Integration

Overview

Set up CI/CD for Flexport logistics integrations: run unit tests with mocked shipment and tracking responses on every PR, execute live API contract validation against the Flexport sandbox on merge to main. Flexport's API covers shipments, booking, customs documentation, and real-time tracking, so CI pipelines verify data transforms for shipment lifecycle events and ensure API contract compatibility across versions.

GitHub Actions Workflow


# .github/workflows/flexport-ci.yml
name: Flexport CI
on:
  pull_request:
    paths: ['src/flexport/**', 'tests/**']
  push:
    branches: [main]

jobs:
  unit-tests:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm test -- --reporter=verbose

  integration-tests:
    if: github.ref == 'refs/heads/main'
    needs: unit-tests
    runs-on: ubuntu-latest
    environment: staging
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4
        with: { node-version: '20' }
      - run: npm ci
      - run: npm run test:integration
        env:
          FLEXPORT_API_KEY: ${{ secrets.FLEXPORT_API_KEY }}

Mock-Based Unit Tests


// tests/flexport-service.test.ts
import { describe, it, expect, vi } from 'vitest';
import { getShipmentStatus } from '../src/flexport-service';

vi.mock('../src/flexport-client', () => ({
  FlexportClient: vi.fn().mockImplementation(() => ({
    getShipment: vi.fn().mockResolvedValue({
      id: 'shp_abc123',
      status: 'in_transit',
      origin: { port: 'CNSHA', country: 'CN' },
      destination: { port: 'USLAX', country: 'US' },
      containers: [{ id: 'MSKU1234567', type: '40ft_hc' }],
      estimated_arrival: '2026-04-15T00:00:00Z',
    }),
    listShipments: vi.fn().mockResolvedValue({ data: [], total_count: 0 }),
  })),
}));

describe('Flexport Service', () => {
  it('returns shipment tracking status', async () => {
    const status = await getShipmentStatus('shp_abc123');
    expect(status.status).toBe('in_transit');
    expect(status.origin.port).toBe('CNSHA');
  });
});

Integration Tests


// tests/integration/flexport.integration.test.ts
import { describe, it, expect } from 'vitest';

const hasKey = !!process.env.FLEXPORT_API_KEY;

describe.skipIf(!hasKey)('Flexport Live API', () => {
  it('lists shipments from sandbox', async () => {
    const res = await fetch('https://api.flexport.com/shipments?per=1', {
      headers: {
        'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,


                
                  
                  
                  flexport-common-errors
                  SKILL.md
                  View full skill →
                
                
                  Diagnose and fix common Flexport API errors including HTTP status codes, webhook failures, and data validation issues.
                  
                      ReadGrepBash(curl:*)
                    
                
                
                  Flexport Common Errors
Overview
Quick reference for the most common Flexport API v2 errors. The API returns standard HTTP codes with JSON error bodies containing code, message, and sometimes details fields.
Error Reference
401 Unauthorized — Invalid or Missing API Key

{ "error": { "code": "UNAUTHORIZED", "message": "Invalid API key" } }

Causes: Missing Authorization header, expired JWT token, revoked API key.
Fix:

# Verify key is set
echo $FLEXPORT_API_KEY | head -c 10
# Test with cURL
curl -s -o /dev/null -w "%{http_code}" \
  -H "Authorization: Bearer $FLEXPORT_API_KEY" \
  -H "Flexport-Version: 2" \
  https://api.flexport.com/shipments?per=1

403 Forbidden — Insufficient Permissions
Causes: API key lacks required scope, IP whitelist blocking, sandbox key used on production.
Fix: Check key permissions in Flexport Portal > Settings > Developer. Ensure key scope includes the endpoint you are calling.
404 Not Found — Resource Does Not Exist

{ "error": { "code": "NOT_FOUND", "message": "Shipment shp_xxx not found" } }

Causes: Wrong ID format, resource deleted, using test ID in production.
Fix: List resources first to get valid IDs:

curl -s -H "Authorization: Bearer $FLEXPORT_API_KEY" \
     -H "Flexport-Version: 2" \
     https://api.flexport.com/shipments?per=1 | jq '.data.records[0].id'

422 Unprocessable Entity — Validation Failed

{ "error": { "code": "VALIDATION_ERROR", "message": "Invalid port code", "details": [...] } }

Common validation failures:

Field
Issue
Fix


origin_port.code
Not a valid UN/LOCODE
Use CNSHA, USLAX, DEHAM format


hs_code
Wrong format
Use 6-10 digit codes like 8479.89


cargoreadydate
In the past
Use future ISO date


freight_type
Unsupported value
Use ocean, air, or trucking


incoterm
Invalid
Use FOB, CIF, EXW, DDP


429 Too Many Requests


                
                  
                  
                  flexport-core-workflow-a
                  SKILL.md
                  View full skill →
                
                
                  Execute Flexport primary workflow: shipment booking and purchase order management.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Flexport Core Workflow A: Bookings & Purchase Orders
Overview
The primary Flexport integration path: create purchase orders, book shipments, and track cargo through the supply chain. The API v2 uses RESTful endpoints at https://api.flexport.com with JSON payloads.
Prerequisites

Completed flexport-install-auth setup
Understanding of Flexport freight types (ocean FCL/LCL, air, trucking)
Valid shipper/consignee addresses configured in Flexport Portal

Instructions
Step 1: Create a Purchase Order

const BASE = 'https://api.flexport.com';
const headers = {
  'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
  'Flexport-Version': '2',
  'Content-Type': 'application/json',
};

// POST /purchase_orders — create a PO to track inbound goods
const po = await fetch(`${BASE}/purchase_orders`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'PO-2025-001',
    status: 'open',
    buyer: { name: 'Acme Corp', address: { country: 'US' } },
    seller: { name: 'Shanghai Supplier', address: { country: 'CN' } },
    line_items: [
      { sku: 'WIDGET-A', quantity: 500, unit_of_measure: 'pieces' },
      { sku: 'WIDGET-B', quantity: 200, unit_of_measure: 'pieces' },
    ],
    cargo_ready_date: '2025-04-15',
    must_arrive_by: '2025-05-20',
  }),
}).then(r => r.json());

console.log(`PO created: ${po.data.id}`);

Step 2: Create a Booking

// POST /bookings — book freight against a purchase order
const booking = await fetch(`${BASE}/bookings`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    freight_type: 'ocean',          // ocean, air, trucking
    incoterm: 'FOB',                // FOB, CIF, EXW, DDP, etc.
    origin_port: { code: 'CNSHA' }, // Shanghai
    destination_port: { code: 'USLAX' }, // Los Angeles
    cargo_ready_date: '2025-04-15',
    purchase_order_ids: [po.data.id],
    wants_freight_management: true,
    wants_customs_service: true,
  }),
}).then(r => r.json());

console.log(`Booking: ${booking.data.id} | Status: ${booking.data.status}`);

Step 3: Track Shipment Milestones

// GET /shipments/:id — once booking is confirmed, a shipment is created
// Milestones include: cargo_ready, departed, arrived, customs_cleared, delivered
const shipment = await fetch(
  `${BASE}/shipments/${booking.data.shipment_id}`, { headers }
).then(r => r.json());

console.log(`Shipment ${shipment.data.id}:`);
console.log(`  Status: ${shipment.data.status}`);
console.log(`  ETD: ${shipment.data.estimated_departure_date}`);
console.log(`  ETA: ${shipment.data.estimated_arrival


                
                  
                  
                  flexport-core-workflow-b
                  SKILL.md
                  View full skill →
                
                
                  Execute Flexport secondary workflow: commercial invoices, products catalog, and freight invoices.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Flexport Core Workflow B: Invoices & Products
Overview
Manage Flexport commercial invoices for customs clearance, maintain the product catalog for landed cost calculations, and handle freight billing. These APIs complement the booking/shipment workflow in flexport-core-workflow-a.
Prerequisites

Completed flexport-install-auth setup
Existing shipments or bookings (from workflow A)
Product SKUs defined in your system

Instructions
Step 1: Manage Product Catalog

const BASE = 'https://api.flexport.com';
const headers = {
  'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
  'Flexport-Version': '2',
  'Content-Type': 'application/json',
};

// POST /products — add products to the Flexport Product Library
const product = await fetch(`${BASE}/products`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    name: 'Industrial Widget Type A',
    sku: 'WIDGET-A',
    hs_code: '8479.89',              // Harmonized System code for customs
    country_of_origin: 'CN',
    unit_cost: { amount: 12.50, currency: 'USD' },
    weight: { value: 2.5, unit: 'kg' },
    dimensions: { length: 30, width: 20, height: 15, unit: 'cm' },
  }),
}).then(r => r.json());

console.log(`Product: ${product.data.id} | SKU: ${product.data.sku}`);

Step 2: Create Commercial Invoices

// POST /commercial_invoices — required for customs clearance
const invoice = await fetch(`${BASE}/commercial_invoices`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    shipment_id: 'shp_abc123',
    invoice_number: 'CI-2025-001',
    seller: { name: 'Shanghai Supplier Co.' },
    buyer: { name: 'Acme Corp' },
    line_items: [
      {
        product_id: product.data.id,
        quantity: 500,
        unit_price: { amount: 12.50, currency: 'USD' },
        total_price: { amount: 6250.00, currency: 'USD' },
      },
    ],
    total_value: { amount: 6250.00, currency: 'USD' },
    currency: 'USD',
    incoterm: 'FOB',
  }),
}).then(r => r.json());

console.log(`Invoice: ${invoice.data.id} | Total: $${invoice.data.total_value.amount}`);

Step 3: Retrieve Freight Invoices

// GET /freight_invoices — Flexport billing for freight services
const freightInvoices = await fetch(
  `${BASE}/freight_invoices?status=outstanding&per=10`, { headers }
).then(r => r.json());

freightInvoices.data.records.forEach((inv: any) => {
  console.log(`${inv.invoice_number} | ${inv.status} | $${inv.total.amount}`);
  inv.line_items?.forEach((li: any) => {
    console.log(`  ${li.description}: $${li.amount.amount}`);
  });
});

                
              

                
                  
                  
                  flexport-cost-tuning
                  SKILL.md
                  View full skill →
                
                
                  Optimize Flexport API usage costs through efficient pagination, caching, webhook-driven updates, and monitoring API call volume.
                  
                      ReadWriteEdit
                    
                
                
                  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-data-handling
                  SKILL.md
                  View full skill →
                
                
                  Implement data handling for Flexport supply chain data including PII redaction, shipment data retention, GDPR compliance, and secure document management.
                  
                      ReadWriteEdit
                    
                
                
                  Flexport Data Handling
Overview
Flexport logistics data encompasses shipment records, bills of lading, customs declarations, commercial invoices, tracking events, and trade compliance documents. This data crosses international borders and regulatory jurisdictions, requiring strict handling for PII (shipper/consignee contacts), controlled export data (HS codes, ITAR items), and financial records (invoices, duty payments). All integrations must enforce GDPR/CCPA compliance, customs data retention mandates, and C-TPAT supply chain security standards.
Data Classification

Data Type
Sensitivity
Retention
Encryption


Shipment records
Medium
1 year post-delivery
AES-256 at rest


Customs declarations
High (trade compliance)
5 years (CBP requirement)
AES-256 + TLS


Commercial invoices
High (financial)
7 years (tax/audit)
AES-256 at rest


Contact PII (shipper/consignee)
High
Until deletion request
Field-level encryption


Tracking events
Low
90 days
TLS in transit


Data Import

interface FlexportShipment {
  id: string; ref: string; status: string;
  shipper: { name: string; email: string; address: string };
  consignee: { name: string; email: string; address: string };
  hsCode: string; incoterm: string; cargoReadyDate: string;
}

async function importShipments(cursor?: string): Promise<FlexportShipment[]> {
  const allShipments: FlexportShipment[] = [];
  let nextCursor = cursor;
  do {
    const res = await fetch(`https://api.flexport.com/v2/shipments?page[after]=${nextCursor || ''}`, {
      headers: { Authorization: `Bearer ${process.env.FLEXPORT_API_TOKEN}` },
    });
    const data = await res.json();
    for (const s of data.data) {
      if (!s.id || !s.attributes.ref) throw new Error(`Invalid shipment: missing required fields`);
      allShipments.push(s.attributes);
    }
    nextCursor = data.links?.next ? new URL(data.links.next).searchParams.get('page[after]') : null;
  } while (nextCursor);
  return allShipments;
}

Data Export

async function exportShipmentsCSV(shipments: FlexportShipment[], dest: string) {
  const REDACT_FIELDS = ['email', 'phone', 'street_address', 'tax_id'];
  const sanitized = shipments.map(s => {
    const copy = JSON.parse(JSON.stringify(s));
    for (const field of REDACT_FIELDS) {
      if (copy.shipper?.[field]) copy.shipper[field] = '[REDACTED]';
      if (copy.consignee?.[field]) copy.consignee[field] = '[REDACTED]';
    }
    return copy;
  });
  // Validate no restricted HS codes in export paylo

                

              

                
                  
                  
                  flexport-debug-bundle
                  SKILL.md
                  View full skill →
                
                
                  Collect Flexport API debug evidence for support tickets and troubleshooting.
                  
                      ReadBash(curl:*)Bash(tar:*)Bash(jq:*)Grep
                    
                
                
                  Flexport Debug Bundle
Overview
Collect all necessary diagnostic information for Flexport support tickets. The bundle captures API connectivity, authentication status, recent shipment data, and error logs while automatically redacting secrets.
Instructions
Step 1: Create Debug Bundle Script

#!/bin/bash
# flexport-debug.sh — run with: bash flexport-debug.sh
set -euo pipefail

BUNDLE="flexport-debug-$(date +%Y%m%d-%H%M%S)"
mkdir -p "$BUNDLE"

echo "=== Flexport Debug Bundle ===" | tee "$BUNDLE/summary.txt"
echo "Generated: $(date -u +%Y-%m-%dT%H:%M:%SZ)" >> "$BUNDLE/summary.txt"
echo "Node: $(node --version 2>/dev/null || echo 'not found')" >> "$BUNDLE/summary.txt"
echo "API Key set: ${FLEXPORT_API_KEY:+YES}" >> "$BUNDLE/summary.txt"

Step 2: Test API Connectivity

# API health and auth check
echo -e "\n--- API Connectivity ---" >> "$BUNDLE/summary.txt"
RESPONSE=$(curl -s -w "\n%{http_code}" \
  -H "Authorization: Bearer $FLEXPORT_API_KEY" \
  -H "Flexport-Version: 2" \
  https://api.flexport.com/shipments?per=1 2>&1)

HTTP_CODE=$(echo "$RESPONSE" | tail -1)
BODY=$(echo "$RESPONSE" | head -n -1)

echo "HTTP Status: $HTTP_CODE" >> "$BUNDLE/summary.txt"
echo "$BODY" | jq '{total_count: .data.total_count, has_records: (.data.records | length > 0)}' \
  >> "$BUNDLE/api-test.json" 2>/dev/null || echo "Parse failed" >> "$BUNDLE/api-test.json"

Step 3: Capture Recent Errors

# Collect recent error logs (redacted)
echo -e "\n--- Recent Errors ---" >> "$BUNDLE/summary.txt"
grep -i "flexport\|FLEXPORT" /var/log/app/*.log 2>/dev/null | \
  tail -50 | \
  sed 's/Bearer [^ ]*/Bearer ***REDACTED***/g' \
  >> "$BUNDLE/errors.txt" 2>/dev/null || echo "No app logs found" >> "$BUNDLE/errors.txt"

# Capture env config (redacted)
env | grep -i FLEXPORT | sed 's/=.*/=***REDACTED***/' >> "$BUNDLE/env-redacted.txt"

Step 4: Check Status Page and Package

# Flexport platform status
echo -e "\n--- Platform Status ---" >> "$BUNDLE/summary.txt"
curl -s https://status.flexport.com/api/v2/status.json | \
  jq '{status: .status.description, updated: .page.updated_at}' \
  >> "$BUNDLE/status.json" 2>/dev/null || echo "Status page unreachable" >> "$BUNDLE/status.json"

# Package and output
tar -czf "$BUNDLE.tar.gz" "$BUNDLE"
rm -rf "$BUNDLE"
ec

                

              

                
                  
                  
                  flexport-deploy-integration
                  SKILL.md
                  View full skill →
                
                
                  Deploy Flexport logistics integrations to Vercel, Fly.
                  
                      ReadWriteEditBash(npm:*)Bash(fly:*)Bash(gcloud:*)Grep
                    
                
                
                  Flexport Deploy Integration
Overview
Deploy Flexport-powered applications to production. Webhook receivers need always-on hosting. Dashboards can use serverless. Background sync workers suit containers.
Instructions
Option A: Vercel (Dashboard + Webhook Routes)

// app/api/webhooks/flexport/route.ts (Next.js App Router)
import crypto from 'crypto';

export async function POST(req: Request) {
  const body = await req.text();
  const sig = req.headers.get('x-hub-signature') || '';
  const expected = 'sha256=' + crypto.createHmac('sha256', process.env.FLEXPORT_WEBHOOK_SECRET!)
    .update(body).digest('hex');
  if (!crypto.timingSafeEqual(Buffer.from(sig), Buffer.from(expected))) {
    return new Response('Invalid signature', { status: 401 });
  }
  const event = JSON.parse(body);
  // Process milestone, booking, invoice events
  return new Response('OK');
}

Option B: Fly.io (Always-On Webhook Receiver)

# fly.toml
app = "flexport-webhooks"
primary_region = "iad"
[http_service]
  internal_port = 3000
  force_https = true
  min_machines_running = 1


fly secrets set FLEXPORT_API_KEY="key" FLEXPORT_WEBHOOK_SECRET="secret"
fly deploy

Option C: Cloud Run (Shipment Sync Worker)

gcloud run deploy flexport-sync \
  --source . --region us-central1 \
  --set-secrets "FLEXPORT_API_KEY=flexport-key:latest" \
  --min-instances 1 --timeout 300

Post-Deploy Verification

curl -X POST https://your-app.fly.dev/webhooks/flexport \
  -H "X-Hub-Signature: sha256=invalid" -d '{"type":"test"}'
# Expected: 401 (signature verification working)

Resources

Flexport Webhooks API
Fly.io Docs
Cloud Run Docs

Next Steps
For webhook event handling, see flexport-webhooks-events.
                
              

                
                  
                  
                  flexport-enterprise-rbac
                  SKILL.md
                  View full skill →
                
                
                  Configure role-based access control for Flexport integrations with scoped API keys, multi-tenant patterns, and organization-level permission management.
                  
                      ReadWriteEdit
                    
                
                
                  Flexport Enterprise RBAC
Overview
Implement role-based access control for Flexport integrations. Since Flexport API keys are scoped at the account level, RBAC is implemented in your application layer with per-role API key allocation and request filtering.
Instructions
Step 1: Define Roles

Role
API Key Scope
Allowed Endpoints
Use Case


Viewer
Read-only
GET /shipments, GET /products
Dashboard users


Operator
Read-write
GET/POST /bookings, GET/PATCH /purchase_orders
Ops team


Finance
Read invoices
GET /freightinvoices, GET /commercialinvoices
Finance team


Admin
Full access
All endpoints
System administrators


Step 2: Application-Layer RBAC

type Role = 'viewer' | 'operator' | 'finance' | 'admin';

const ROLE_PERMISSIONS: Record<Role, { methods: string[]; paths: RegExp[] }> = {
  viewer: {
    methods: ['GET'],
    paths: [/^\/shipments/, /^\/products/, /^\/purchase_orders/],
  },
  operator: {
    methods: ['GET', 'POST', 'PATCH'],
    paths: [/^\/shipments/, /^\/bookings/, /^\/purchase_orders/, /^\/products/],
  },
  finance: {
    methods: ['GET'],
    paths: [/^\/freight_invoices/, /^\/commercial_invoices/, /^\/shipments/],
  },
  admin: {
    methods: ['GET', 'POST', 'PATCH', 'DELETE'],
    paths: [/.*/],
  },
};

function checkPermission(role: Role, method: string, path: string): boolean {
  const perms = ROLE_PERMISSIONS[role];
  return perms.methods.includes(method) && perms.paths.some(p => p.test(path));
}

// Middleware
function rbacMiddleware(role: Role) {
  return (req: Request, res: Response, next: NextFunction) => {
    const flexportPath = req.params.flexportPath;
    if (!checkPermission(role, req.method, `/${flexportPath}`)) {
      return res.status(403).json({ error: 'Insufficient permissions' });
    }
    next();
  };
}

Step 3: Multi-Tenant API Key Management

// Each tenant/team gets their own Flexport API key
interface TenantConfig {
  tenantId: string;
  flexportApiKey: string;
  role: Role;
  allowedShipmentPrefixes?: string[];  // Filter visible data
}

class MultiTenantFlexport {
  private configs: Map<string, TenantConfig>;

  async request(tenantId: string, path: string, options: RequestInit = {}) {
    const config = this.configs.get(tenantId);
    if (!config) throw new Error('Unknown tenant');
    if (!checkPermission(config.role, options.method || 'GET', path)) {
      

                

              

                
                  
                  
                  flexport-hello-world
                  SKILL.md
                  View full skill →
                
                
                  Create a minimal working Flexport example — list shipments and track containers.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)
                    
                
                
                  Flexport Hello World
Overview
List shipments and retrieve tracking milestones using the Flexport REST API v2. Flexport has no npm SDK -- you call https://api.flexport.com directly with bearer token auth and a Flexport-Version: 2 header.
Prerequisites

FLEXPORTAPIKEY environment variable set
Completed flexport-install-auth setup
Node.js 18+ (uses native fetch)

Instructions
Step 1: List Your Shipments

// src/flexport/hello.ts
const BASE = 'https://api.flexport.com';
const headers = {
  'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
  'Flexport-Version': '2',
  'Content-Type': 'application/json',
};

// List shipments with pagination
const res = await fetch(`${BASE}/shipments?per=5&page=1`, { headers });
const { data } = await res.json();

data.records.forEach((shipment: any) => {
  console.log(`${shipment.id} | ${shipment.status} | ${shipment.freight_type}`);
  console.log(`  Origin: ${shipment.origin_port?.name ?? 'N/A'}`);
  console.log(`  Dest:   ${shipment.destination_port?.name ?? 'N/A'}`);
});

Step 2: Get Shipment Details with Milestones

// Retrieve a single shipment with tracking milestones
const shipmentId = data.records[0].id;
const detail = await fetch(`${BASE}/shipments/${shipmentId}`, { headers }).then(r => r.json());

console.log(`\nShipment ${detail.data.id}:`);
console.log(`  Status: ${detail.data.status}`);
console.log(`  Cargo ready: ${detail.data.cargo_ready_date}`);
console.log(`  Containers: ${detail.data.containers?.length ?? 0}`);

Step 3: List Containers on a Shipment

// Get container details for ocean freight shipments
const containers = await fetch(
  `${BASE}/shipments/${shipmentId}/containers`, { headers }
).then(r => r.json());

containers.data.records.forEach((c: any) => {
  console.log(`Container ${c.container_number} | ${c.container_type} | ${c.status}`);
});

Output

shp_abc123 | in_transit | ocean
  Origin: Shanghai Port
  Dest:   Los Angeles Port

Shipment shp_abc123:
  Status: in_transit
  Cargo ready: 2025-03-01
  Containers: 2

Container MSKU1234567 | 40ft_hc | in_transit

Error Handling

Error
Cause
Solution


401 Unauthorized
Invalid API key
Check FLEXPORTAPIKEY env var


404 Not Found
Wrong shipment ID
Verify ID from /shipments list


422 Unprocessable
Bad query params
Check per/page are integers


Empty records array
                
              
                
                  
                  
                  flexport-incident-runbook
                  SKILL.md
                  View full skill →
                
                
                  Execute Flexport incident response for API outages, webhook failures, and supply chain data sync issues with triage and mitigation steps.
                  
                      ReadBash(curl:*)Bash(jq:*)Grep
                    
                
                
                  Flexport Incident Runbook
Overview
Incident response procedures for Flexport logistics API integration failures. Covers shipment tracking outages, customs data sync failures, webhook delivery loss, and API degradation scenarios. Flexport powers real-time supply chain visibility, so incidents directly impact shipment tracking, booking workflows, and customs compliance reporting. Classify severity immediately using the matrix below, then follow the matching playbook.
Severity Levels

Level
Definition
Response Time
Example


P1 - Critical
Full API outage or customs data loss
15 min
Flexport API returns 5xx on all endpoints


P2 - High
Partial failure or webhook delivery loss
30 min
Webhook events not arriving, stale shipment data


P3 - Medium
Degraded performance or rate limiting
2 hours
429 responses, elevated latency on tracking calls


P4 - Low
Single endpoint issue or key rotation
8 hours
One shipment query failing, API key nearing expiry


Diagnostic Steps

# Check API health
curl -s -o /dev/null -w "HTTP %{http_code}\n" \
  -H "Authorization: Bearer $FLEXPORT_API_KEY" \
  -H "Flexport-Version: 2" \
  https://api.flexport.com/shipments?per=1

# Check platform status
curl -s https://status.flexport.com/api/v2/status.json | jq -r '.status.description'

# Check rate limit remaining
curl -s -D - -o /dev/null \
  -H "Authorization: Bearer $FLEXPORT_API_KEY" \
  -H "Flexport-Version: 2" \
  https://api.flexport.com/shipments?per=1 2>/dev/null | grep -i "x-ratelimit"

Incident Playbooks
API Outage

Confirm via status.flexport.com and diagnostic script above
Enable circuit breaker to serve cached shipment data
Notify downstream consumers that tracking data is stale
Queue failed requests for replay once API recovers
Monitor status page for Flexport resolution updates

Authentication Failure

Verify API key is set and not expired: check $FLEXPORTAPIKEY
Test with a minimal authenticated request (see diagnostics)
If 401: rotate API key in Flexport portal, deploy new key
If 403: check API key scopes match required permissions
Revoke compromised keys after new key is confirmed working

Data Sync Failure

Check webhook endpoint health — is your receiver returning 200?
Query /webhooks to verify subscription is active
Identify missed events by comparing last processed timestamp
Trigger manual sync for affected shipments via /sh

                

              

                
                  
                  
                  flexport-install-auth
                  SKILL.md
                  View full skill →
                
                
                  Install and configure Flexport API authentication with API keys or OAuth credentials.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)Grep
                    
                
                
                  Flexport Install & Auth
Overview
Configure Flexport API authentication for logistics and supply chain integration. Flexport offers two auth methods: API Keys (simple bearer tokens that never expire) and API Credentials (client ID/secret pairs that issue JWTs valid for 24 hours). The v2 REST API base URL is https://api.flexport.com and speaks JSON.
Prerequisites

Flexport account at flexport.com
API key or credentials from Flexport Portal > Settings > Developer > API Credentials
Node.js 18+ or Python 3.9+

Instructions
Step 1: Obtain API Credentials
Navigate to Flexport Portal > Settings > Developer. Two options:

Auth Method
Format
Lifetime
Use Case


API Key
Bearer token string
Permanent
Simple integrations, scripts


API Credentials
Client ID + Secret
JWT, 24h
Production apps, rotating tokens


Step 2: Configure Environment Variables

# .env (NEVER commit — add to .gitignore)
FLEXPORT_API_KEY=your_api_key_here

# OR for OAuth credentials flow:
FLEXPORT_CLIENT_ID=your_client_id
FLEXPORT_CLIENT_SECRET=your_client_secret
FLEXPORT_API_URL=https://api.flexport.com

Step 3: Authenticate with API Key

// src/flexport/client.ts
const FLEXPORT_BASE = 'https://api.flexport.com';

async function flexportRequest(path: string, options: RequestInit = {}) {
  const res = await fetch(`${FLEXPORT_BASE}${path}`, {
    ...options,
    headers: {
      'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
      'Content-Type': 'application/json',
      'Flexport-Version': '2',
      ...options.headers,
    },
  });
  if (!res.ok) throw new Error(`Flexport ${res.status}: ${await res.text()}`);
  return res.json();
}

Step 4: OAuth Credentials Flow (Production)

let tokenCache: { token: string; expiresAt: number } | null = null;

async function getAccessToken(): Promise<string> {
  if (tokenCache && Date.now() < tokenCache.expiresAt) return tokenCache.token;

  const res = await fetch('https://api.flexport.com/oauth/token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      client_id: process.env.FLEXPORT_CLIENT_ID,
      client_secret: process.env.FLEXPORT_CLIENT_SECRET,
      grant_type: 'client_credentials',
    }),
  });
  const { access_token, expires_in } = await res.json();
  tokenCache = { token: access_token, expiresAt: Date.now() + (expires_in - 60) * 1000 };
  return access_token;
}
<
                
              

                
                  
                  
                  flexport-local-dev-loop
                  SKILL.md
                  View full skill →
                
                
                  Configure Flexport local development with mock API responses and testing.
                  
                      ReadWriteEditBash(npm:*)Bash(pnpm:*)Grep
                    
                
                
                  Flexport Local Dev Loop
Overview
Set up a fast, reproducible local development workflow for Flexport integrations. Since Flexport has no official SDK, the dev loop centers on a typed HTTP client wrapper with mock responses for testing.
Instructions
Step 1: Project Structure

flexport-integration/
├── src/
│   ├── flexport/
│   │   ├── client.ts          # Typed Flexport API client
│   │   ├── types.ts           # API response types
│   │   └── mock-data.ts       # Test fixtures
│   └── index.ts
├── tests/
│   ├── flexport.test.ts       # Unit tests with mocks
│   └── integration.test.ts   # Live API tests (CI only)
├── .env.local                 # Local secrets (git-ignored)
├── .env.example
└── package.json

Step 2: Typed Client Wrapper

// src/flexport/types.ts
interface FlexportShipment {
  id: string;
  status: 'booked' | 'in_transit' | 'arrived' | 'delivered';
  freight_type: 'ocean' | 'air' | 'trucking';
  origin_port: { code: string; name: string };
  destination_port: { code: string; name: string };
  cargo_ready_date: string;
  estimated_arrival_date: string;
}

interface FlexportResponse<T> {
  data: { records: T[]; total_count: number };
}

// src/flexport/client.ts
export class FlexportClient {
  private base = 'https://api.flexport.com';
  private headers: Record<string, string>;

  constructor(apiKey: string) {
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Flexport-Version': '2',
      'Content-Type': 'application/json',
    };
  }

  async listShipments(page = 1, per = 25): Promise<FlexportResponse<FlexportShipment>> {
    const res = await fetch(`${this.base}/shipments?page=${page}&per=${per}`, {
      headers: this.headers,
    });
    if (!res.ok) throw new Error(`Flexport ${res.status}: ${await res.text()}`);
    return res.json();
  }
}

Step 3: Mock Data for Testing

// src/flexport/mock-data.ts
export const mockShipment: FlexportShipment = {
  id: 'shp_test_001',
  status: 'in_transit',
  freight_type: 'ocean',
  origin_port: { code: 'CNSHA', name: 'Shanghai' },
  destination_port: { code: 'USLAX', name: 'Los Angeles' },
  cargo_ready_date: '2025-04-01',
  estimated_arrival_date: '2025-05-15',
};

export function mockFlexportFetch(path: string) {
  if (path.includes('/shipments')) {
    return { data: { records: [mockShipment], total_count: 1 } };
  }
  throw new Error(`No mock for ${path}`);
}

Step 4: Vitest Unit Tests

// tests/flexport.test.ts
import { describe, it, expect, vi, beforeEach } from 'vitest';
import { FlexportClient } from '../src/flexport/client

                

              

                
                  
                  
                  flexport-migration-deep-dive
                  SKILL.md
                  View full skill →
                
                
                  Execute major migration strategies for Flexport including migrating from legacy freight forwarders, ERP system integration, and strangler fig patterns.
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Flexport Migration Deep Dive
Overview
Guide for migrating to Flexport from legacy freight forwarders, manual spreadsheet workflows, or other logistics platforms. Uses a strangler fig pattern to gradually move operations to the Flexport API while maintaining existing systems.
Migration Scenarios

From
To
Complexity
Timeline


Spreadsheet/email
Flexport API
Low
2-4 weeks


Legacy freight forwarder API
Flexport API
Medium
4-8 weeks


ERP (SAP, Oracle)
ERP + Flexport
High
8-16 weeks


Multiple forwarders
Flexport consolidated
High
6-12 weeks


Instructions
Phase 1: Data Migration — Product Catalog

// Migrate product catalog from legacy system to Flexport Product Library
async function migrateProducts(legacyProducts: LegacyProduct[]) {
  const results = { success: 0, failed: 0, errors: [] as string[] };

  for (const legacy of legacyProducts) {
    try {
      await fetch('https://api.flexport.com/products', {
        method: 'POST',
        headers,
        body: JSON.stringify({
          name: legacy.description,
          sku: legacy.partNumber,
          hs_code: legacy.tariffCode,
          country_of_origin: legacy.originCountry,
          unit_cost: { amount: legacy.unitCost, currency: legacy.currency },
          weight: { value: legacy.weightKg, unit: 'kg' },
        }),
      });
      results.success++;
    } catch (err) {
      results.failed++;
      results.errors.push(`${legacy.partNumber}: ${err}`);
    }
  }

  console.log(`Products migrated: ${results.success}/${legacyProducts.length}`);
  return results;
}

Phase 2: Strangler Fig — Dual-Write

// During migration, write to both systems
class DualWriteShipmentService {
  constructor(
    private legacy: LegacyForwarderClient,
    private flexport: FlexportClient,
    private featureFlags: FeatureFlags,
  ) {}

  async createBooking(params: BookingParams) {
    // Always write to legacy during migration
    const legacyResult = await this.legacy.createBooking(params);

    // Write to Flexport if enabled for this route
    if (this.featureFlags.isEnabled('flexport_booking', { route: params.route })) {
      try {
        const fpResult = await this.flexport.createBooking(params);
        // Compare results for validation
        this.compareResults(legacyResult, fpResult);
      } catch (err) {
        // Log but don't fail — legacy is still primary
        logger.warn({ err, route: params.route }, 'Flexport dual-write failed');
      }
    }

    return legacyResult;  // Legacy is source of truth during migration
  }
}

<
                
              

                
                  
                  
                  flexport-multi-env-setup
                  SKILL.md
                  View full skill →
                
                
                  Configure Flexport API across dev, staging, and production environments with isolated API keys, separate webhook endpoints, and environment guards.
                  
                      ReadWriteEditGrep
                    
                
                
                  Flexport Multi-Environment Setup
Overview
Configure isolated Flexport environments for development, staging, and production with separate API keys, webhook endpoints, and safety guards to prevent production data access from dev.
Instructions
Environment Configuration

// src/config/flexport.ts
interface FlexportConfig {
  apiKey: string;
  baseUrl: string;
  webhookSecret: string;
  cacheTtlMs: number;
  logLevel: 'debug' | 'info' | 'warn';
}

const configs: Record<string, FlexportConfig> = {
  development: {
    apiKey: process.env.FLEXPORT_API_KEY_DEV!,
    baseUrl: 'https://api.flexport.com',  // Same base, different key scope
    webhookSecret: process.env.FLEXPORT_WEBHOOK_SECRET_DEV!,
    cacheTtlMs: 30_000,   // 30s in dev for fast iteration
    logLevel: 'debug',
  },
  staging: {
    apiKey: process.env.FLEXPORT_API_KEY_STAGING!,
    baseUrl: 'https://api.flexport.com',
    webhookSecret: process.env.FLEXPORT_WEBHOOK_SECRET_STAGING!,
    cacheTtlMs: 60_000,
    logLevel: 'info',
  },
  production: {
    apiKey: process.env.FLEXPORT_API_KEY!,
    baseUrl: 'https://api.flexport.com',
    webhookSecret: process.env.FLEXPORT_WEBHOOK_SECRET!,
    cacheTtlMs: 300_000,  // 5min in prod
    logLevel: 'warn',
  },
};

export function getFlexportConfig(): FlexportConfig {
  const env = process.env.NODE_ENV || 'development';
  const config = configs[env];
  if (!config) throw new Error(`No Flexport config for env: ${env}`);
  if (!config.apiKey) throw new Error(`Missing FLEXPORT_API_KEY for ${env}`);
  return config;
}

Environment Variable Template

# .env.example
# Development (read-only scope, limited data access)
FLEXPORT_API_KEY_DEV=fp_dev_...
FLEXPORT_WEBHOOK_SECRET_DEV=whsec_dev_...

# Staging (read-write scope, test data)
FLEXPORT_API_KEY_STAGING=fp_stg_...
FLEXPORT_WEBHOOK_SECRET_STAGING=whsec_stg_...

# Production (full scope, real shipments)
FLEXPORT_API_KEY=fp_prod_...
FLEXPORT_WEBHOOK_SECRET=whsec_prod_...

Production Safety Guard

// Prevent accidental production API calls from dev/test
function assertNotProduction(operation: string) {
  if (process.env.NODE_ENV === 'production') return;
  const config = getFlexportConfig();
  if (config.apiKey.startsWith('fp_prod_')) {
    throw new Error(`SAFETY: ${operation} blocked — production key detected in ${process.env.NODE_ENV}`);
  }
}

// Usage in destructive operations
async function deleteProduct(id: string) {
  assertNotProduction('deleteProduct');
  await flexport(`/products/${id}`, { method: 'DELETE' });
}

Environment Matrix

Aspect
Dev
Staging
Production


API key scope
Read-on
                
              
                
                  
                  
                  flexport-observability
                  SKILL.md
                  View full skill →
                
                
                  Set up observability for Flexport logistics integrations with metrics, structured logging, distributed tracing, and alerting dashboards.
                  
                      ReadWriteEditBash(npm:*)
                    
                
                
                  Flexport Observability
Overview
Full observability stack for Flexport integrations: Prometheus metrics for API health, pino structured logging for debugging, OpenTelemetry tracing for latency analysis, and Grafana dashboards for monitoring.
Instructions
Step 1: Prometheus Metrics

import { Counter, Histogram, Gauge, register } from 'prom-client';

const flexportRequests = new Counter({
  name: 'flexport_api_requests_total',
  help: 'Total Flexport API requests',
  labelNames: ['method', 'endpoint', 'status'],
});

const flexportLatency = new Histogram({
  name: 'flexport_api_latency_seconds',
  help: 'Flexport API response time',
  labelNames: ['endpoint'],
  buckets: [0.1, 0.25, 0.5, 1, 2.5, 5, 10],
});

const flexportRateLimit = new Gauge({
  name: 'flexport_rate_limit_remaining',
  help: 'Remaining API calls in current window',
});

// Instrumented fetch wrapper
async function instrumentedFlexport(path: string, options: RequestInit = {}) {
  const endpoint = path.split('?')[0];
  const timer = flexportLatency.startTimer({ endpoint });
  try {
    const res = await fetch(`https://api.flexport.com${path}`, { ...options, headers: { ...headers, ...options.headers } });
    flexportRequests.inc({ method: options.method || 'GET', endpoint, status: res.status.toString() });
    const remaining = res.headers.get('X-RateLimit-Remaining');
    if (remaining) flexportRateLimit.set(parseInt(remaining));
    timer();
    return res;
  } catch (err) {
    flexportRequests.inc({ method: options.method || 'GET', endpoint, status: 'error' });
    timer();
    throw err;
  }
}

Step 2: Structured Logging

import pino from 'pino';

const logger = pino({
  name: 'flexport-integration',
  level: process.env.LOG_LEVEL || 'info',
  redact: ['headers.Authorization', 'apiKey'],
});

// Log every API call with context
async function loggedFlexport(path: string, options: RequestInit = {}) {
  const start = Date.now();
  const res = await instrumentedFlexport(path, options);
  logger.info({
    service: 'flexport',
    path,
    method: options.method || 'GET',
    status: res.status,
    latencyMs: Date.now() - start,
    rateRemaining: res.headers.get('X-RateLimit-Remaining'),
  }, 'Flexport API call');
  return res;
}

Step 3: Alert Rules

# prometheus-alerts.yml
groups:
  - name: flexport
    rules:
      - alert: FlexportAPIErrors
        expr: rate(flexport_api_requests_total{status=~"5.."}[5m]) > 0.1
        for: 5m
        labels: { severity: critical }
        annotations:
          summary: "Flexport API error rate elevated"

      - alert: FlexportRateLimitLow
 

                

              

                
                  
                  
                  flexport-performance-tuning
                  SKILL.md
                  View full skill →
                
                
                  Optimize Flexport API performance with pagination tuning, response caching, parallel requests, and connection pooling for logistics data.
                  
                      ReadWriteEditBash(npm:*)
                    
                
                
                  Flexport Performance Tuning
Overview
Optimize Flexport API integration performance. The API is rate-limited and serves logistics data that changes infrequently (shipments update hourly, products rarely). Cache aggressively for reads, batch writes, and use maximum page sizes.
Instructions
Step 1: Maximize Page Size

// Default per=25. Use per=100 (max) to reduce API calls by 4x
async function fetchAllShipments(): Promise<Shipment[]> {
  const all: Shipment[] = [];
  let page = 1;
  while (true) {
    const res = await flexport(`/shipments?per=100&page=${page}`);
    all.push(...res.data.records);
    if (res.data.records.length < 100) break;
    page++;
  }
  return all;
  // 1000 shipments = 10 API calls instead of 40
}

Step 2: Cache Responses

import { LRUCache } from 'lru-cache';

const cache = new LRUCache<string, any>({
  max: 500,
  ttl: 5 * 60 * 1000,  // 5 min for shipment data
});

// Products change rarely — cache longer
const productCache = new LRUCache<string, any>({
  max: 1000,
  ttl: 60 * 60 * 1000,  // 1 hour
});

async function cachedFlexport(path: string, ttlCache = cache): Promise<any> {
  const cached = ttlCache.get(path);
  if (cached) return cached;
  const data = await flexport(path);
  ttlCache.set(path, data);
  return data;
}

Step 3: Parallel Requests with Concurrency Control

import PQueue from 'p-queue';

const queue = new PQueue({ concurrency: 5, interval: 1000, intervalCap: 10 });

// Fetch details for multiple shipments in parallel
async function enrichShipments(ids: string[]) {
  return Promise.all(
    ids.map(id => queue.add(() => flexport(`/shipments/${id}`)))
  );
}

Step 4: Webhook-Driven Cache Invalidation

// Instead of polling, invalidate cache on webhook events
async function handleWebhook(event: any) {
  if (event.type.startsWith('shipment.')) {
    cache.delete(`/shipments/${event.data.shipment_id}`);
    cache.delete('/shipments');  // Invalidate list cache
  }
  if (event.type.startsWith('product.')) {
    productCache.delete(`/products/${event.data.product_id}`);
  }
}

Performance Targets

Metric
Target
Strategy


Shipment list load
< 500ms
Cache with 5min TTL


Product lookup
< 100ms
Cache with 1hr TTL


Bulk shipment fetch
< 3s for 100
Parallel with p-queue


Dashboard refresh
< 2s
Stale-while-revalidate


Resources

Flexport API Reference

                
                  
                  
                  flexport-prod-checklist
                  SKILL.md
                  View full skill →
                
                
                  Execute Flexport production deployment checklist for logistics integrations.
                  
                      ReadBash(curl:*)Grep
                    
                
                
                  Flexport Production Checklist
Overview
Pre-deployment and go-live checklist for Flexport logistics integrations covering API configuration, webhook setup, monitoring, and rollback procedures.
Pre-Deployment
Authentication & Secrets

[ ] Production API key stored in secret manager (not env files)
[ ] Webhook secret configured and verified
[ ] Key rotation procedure documented
[ ] No keys in git history (git log -p | grep -i flexport_api)

API Integration

[ ] All endpoints tested against production API
[ ] Pagination implemented for list endpoints (/shipments, /products)
[ ] Rate limit handling with exponential backoff
[ ] Retry logic for transient 5xx errors
[ ] Idempotency keys on POST/PATCH operations
[ ] Flexport-Version: 2 header on all requests

Webhooks

[ ] HTTPS endpoint with valid TLS certificate
[ ] X-Hub-Signature verification implemented
[ ] Webhook endpoint responds within 5 seconds
[ ] Dead letter queue for failed webhook processing
[ ] Idempotent webhook handlers (replay-safe)

Data Integrity

[ ] HS codes validated against customs requirements
[ ] UN/LOCODE port codes verified
[ ] Commercial invoice totals cross-checked
[ ] Product catalog synced with Flexport Product Library

Monitoring & Alerting

// Health check endpoint
app.get('/health', async (req, res) => {
  const start = Date.now();
  try {
    const r = await fetch('https://api.flexport.com/shipments?per=1', {
      headers: {
        'Authorization': `Bearer ${process.env.FLEXPORT_API_KEY}`,
        'Flexport-Version': '2',
      },
    });
    res.json({
      status: r.ok ? 'healthy' : 'degraded',
      flexport: { connected: r.ok, latencyMs: Date.now() - start },
    });
  } catch {
    res.status(503).json({ status: 'unhealthy', flexport: { connected: false } });
  }
});

Alert Thresholds

Metric
Warning
Critical


API error rate
> 5%
> 20%


p99 latency
> 3000ms
> 10000ms


429 rate limits
> 5/hour
> 20/hour


Webhook failures
> 2/hour
> 10/hour


Auth failures (401/403)
Any
Any


Rollback Procedure

# Immediate rollback
kubectl rollout undo deployment/flexport-integration
# Or for non-k8s: revert to last known good image/version

Resources


                

              

                
                  
                  
                  flexport-rate-limits
                  SKILL.md
                  View full skill →
                
                
                  Handle Flexport API rate limits with exponential backoff, queue-based throttling, and response header monitoring for logistics API calls.
                  
                      ReadWriteEdit
                    
                
                
                  Flexport Rate Limits
Overview
The Flexport API v2 enforces rate limits per API key. When exceeded, you get a 429 Too Many Requests with Retry-After and X-RateLimit-* headers. Key limits to know: the API returns headers on every response telling you remaining quota.
Rate Limit Headers

Header
Description
Example


X-RateLimit-Limit
Max requests per window
100


X-RateLimit-Remaining
Remaining in current window
47


X-RateLimit-Reset
Unix timestamp when window resets
1711234567


Retry-After
Seconds to wait (only on 429)
30


Instructions
Step 1: Monitor Rate Limit Headers

class RateLimitTracker {
  remaining = Infinity;
  resetAt = 0;

  update(headers: Headers) {
    this.remaining = parseInt(headers.get('X-RateLimit-Remaining') || '100');
    this.resetAt = parseInt(headers.get('X-RateLimit-Reset') || '0') * 1000;
  }

  async waitIfNeeded() {
    if (this.remaining <= 2 && Date.now() < this.resetAt) {
      const wait = this.resetAt - Date.now() + 100;
      console.log(`Rate limit near. Waiting ${wait}ms`);
      await new Promise(r => setTimeout(r, wait));
    }
  }
}

Step 2: Exponential Backoff with Jitter

async function flexportWithRetry<T>(
  fn: () => Promise<Response>,
  maxRetries = 4
): Promise<T> {
  for (let attempt = 0; attempt <= maxRetries; attempt++) {
    const res = await fn();

    if (res.ok) return res.json();

    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('Retry-After') || '60');
      const jitter = Math.random() * 2000;
      const delay = retryAfter * 1000 + jitter;
      console.log(`429 rate limited. Retry in ${(delay / 1000).toFixed(1)}s`);
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    if (res.status >= 500 && attempt < maxRetries) {
      const delay = Math.pow(2, attempt) * 1000 + Math.random() * 1000;
      await new Promise(r => setTimeout(r, delay));
      continue;
    }

    throw new Error(`Flexport ${res.status}: ${await res.text()}`);
  }
  throw new Error('Max retries exceeded');
}

Step 3: Queue-Based Throttling

import PQueue from 'p-queue';

// Limit to 10 requests per second with max 3 concurrent
const flexportQueue = new PQueue({
  concurrency: 3,
  interval: 1000,
  intervalCap: 10,
});

async function throttledRequest(path: string): Promise<any> {

                

              

                
                  
                  
                  flexport-reference-architecture
                  SKILL.md
                  View full skill →
                
                
                  Implement Flexport reference architecture for supply chain integrations with best-practice project layout, service boundaries, and data flow.
                  
                      ReadWriteEdit
                    
                
                
                  Flexport Reference Architecture
Overview
Production reference architecture for Flexport logistics integrations. Three core services: Ingest (webhooks + polling), Core (business logic), and Expose (API + dashboard).
Architecture

┌──────────────────────────────────────────────────────┐
│                    Your Application                   │
├──────────────┬──────────────────┬─────────────────────┤
│  Ingest      │  Core            │  Expose             │
│              │                  │                     │
│  Webhook     │  Shipment        │  REST API           │
│  Receiver    │  Service         │  (your clients)     │
│              │                  │                     │
│  Scheduled   │  Product         │  Dashboard          │
│  Sync        │  Service         │  (Next.js/Astro)    │
│              │                  │                     │
│  Event       │  Invoice         │  Notifications      │
│  Queue       │  Service         │  (email/slack)      │
├──────────────┴──────────────────┴─────────────────────┤
│  Infrastructure: Cache (Redis) │ DB (Postgres) │ Queue │
├───────────────────────────────────────────────────────┤
│  Flexport API v2 (https://api.flexport.com)           │
└───────────────────────────────────────────────────────┘

Project Layout

flexport-integration/
├── src/
│   ├── flexport/
│   │   ├── client.ts           # Singleton API client
│   │   ├── types.ts            # Zod schemas for API responses
│   │   └── webhooks.ts         # Webhook signature + routing
│   ├── services/
│   │   ├── shipment.service.ts # Shipment CRUD + tracking
│   │   ├── product.service.ts  # Product catalog sync
│   │   ├── invoice.service.ts  # Commercial + freight invoices
│   │   └── booking.service.ts  # Booking creation + amendments
│   ├── jobs/
│   │   ├── sync-shipments.ts   # Scheduled full sync (hourly)
│   │   └── cache-warmup.ts     # Pre-populate caches on deploy
│   ├── api/
│   │   ├── routes.ts           # Express/Fastify routes
│   │   └── middleware.ts       # Auth, logging, error handling
│   └── config/
│       ├── flexport.ts         # API config per environment
│       └── cache.ts            # TTL settings per data type
├── tests/
│   ├── unit/                   # Mocked API tests
│   └── integration/            # Live API tests (CI only)
├── .env.example
└── docker-compose.yml          # Redis + Postgres for local dev

Data Flow

Flexport API ──webhook──> Ingest ──queue──> Core ──cache──> Expose
                                    │                │
                                    └── DB (Postgres) ┘


Ingest: Webhook receiver validates signatures, enqueues events
Core: Services process events, sync with Flexport API, update DB
Expose: API/dashboard reads from DB + cache, never directly from Flexport<
                
              

                
                  
                  
                  flexport-sdk-patterns
                  SKILL.md
                  View full skill →
                
                
                  Apply production-ready Flexport API patterns for TypeScript and Python.
                  
                      ReadWriteEdit
                    
                
                
                  Flexport SDK Patterns
Overview
Production-ready patterns for the Flexport REST API v2. Since Flexport has no official npm/pip SDK, you build typed HTTP clients. Key patterns: singleton client, paginated iteration, retry wrapper, and Zod response validation.
Instructions
Pattern 1: Singleton Client with Auto-Retry

// src/flexport/client.ts
import { z } from 'zod';

class FlexportClient {
  private static instance: FlexportClient | null = null;
  private base = 'https://api.flexport.com';
  private headers: Record<string, string>;

  private constructor(apiKey: string) {
    this.headers = {
      'Authorization': `Bearer ${apiKey}`,
      'Flexport-Version': '2',
      'Content-Type': 'application/json',
    };
  }

  static getInstance(): FlexportClient {
    if (!this.instance) {
      const key = process.env.FLEXPORT_API_KEY;
      if (!key) throw new Error('Missing FLEXPORT_API_KEY');
      this.instance = new FlexportClient(key);
    }
    return this.instance;
  }

  async request<T>(path: string, options: RequestInit = {}): Promise<T> {
    const res = await fetch(`${this.base}${path}`, { ...options, headers: { ...this.headers, ...options.headers } });
    if (res.status === 429) {
      const retryAfter = parseInt(res.headers.get('Retry-After') || '60');
      await new Promise(r => setTimeout(r, retryAfter * 1000));
      return this.request(path, options);  // Retry once
    }
    if (!res.ok) {
      const body = await res.text();
      throw new FlexportAPIError(res.status, body, path);
    }
    return res.json();
  }
}

class FlexportAPIError extends Error {
  constructor(public status: number, public body: string, public path: string) {
    super(`Flexport ${status} on ${path}: ${body}`);
    this.name = 'FlexportAPIError';
  }
}

Pattern 2: Paginated Iterator

// Iterate all pages of a Flexport list endpoint
async function* paginate<T>(path: string, perPage = 25): AsyncGenerator<T> {
  const client = FlexportClient.getInstance();
  let page = 1;
  while (true) {
    const separator = path.includes('?') ? '&' : '?';
    const res = await client.request<{ data: { records: T[]; total_count: number } }>(
      `${path}${separator}page=${page}&per=${perPage}`
    );
    for (const record of res.data.records) yield record;
    if (res.data.records.length < perPage) break;
    page++;
  }
}

// Usage: iterate all shipments
for await (const shipment of paginate<Shipment>('/shipments')) {
  console.log(shipment.id, shipment.status);
}

Pattern 3: Zod Response Validation

const ShipmentSchema = z.object({
  id: z.string(),
  status: z.enum(['booked', 'in_transit', &#

                

              

                
                  
                  
                  flexport-security-basics
                  SKILL.md
                  View full skill →
                
                
                  Apply Flexport API security best practices including webhook signature verification, API key rotation, and least-privilege access patterns.
                  
                      ReadWriteGrep
                    
                
                
                  Flexport Security Basics
Overview
Flexport manages global freight logistics containing shipping manifests, customs declarations, commercial invoices, and supply chain partner data. A breach exposes trade routes, commodity values, importer/exporter identities, and customs brokerage details. Secure API credentials, webhook endpoints, and any pipeline that processes shipment tracking or purchase order data.
API Key Management

function createFlexportClient(): { apiKey: string; baseUrl: string } {
  const apiKey = process.env.FLEXPORT_API_KEY;
  if (!apiKey) {
    throw new Error("Missing FLEXPORT_API_KEY — store in secrets manager, never in .env in production");
  }
  // Never log the key; log only a hash suffix for debugging
  console.log("Flexport client initialized (key suffix:", apiKey.slice(-4), ")");
  return { apiKey, baseUrl: "https://api.flexport.com/v2" };
}

Webhook Signature Verification

import crypto from "crypto";
import { Request, Response, NextFunction } from "express";

function verifyFlexportWebhook(req: Request, res: Response, next: NextFunction): void {
  const signature = req.headers["x-hub-signature"] as string;
  const secret = process.env.FLEXPORT_WEBHOOK_SECRET!;
  const expected = "sha256=" + crypto.createHmac("sha256", secret).update(req.body).digest("hex");
  if (!signature || !crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    res.status(401).send("Invalid signature");
    return;
  }
  next();
}

Input Validation

import { z } from "zod";

const ShipmentQuerySchema = z.object({
  shipment_id: z.string().regex(/^FLEX-\d+$/),
  container_number: z.string().regex(/^[A-Z]{4}\d{7}$/).optional(),
  origin_port: z.string().length(5).optional(),
  destination_port: z.string().length(5).optional(),
  hs_code: z.string().regex(/^\d{6,10}$/).optional(),
});

function validateShipmentQuery(data: unknown) {
  return ShipmentQuerySchema.parse(data);
}

Data Protection

const FLEXPORT_SENSITIVE_FIELDS = ["customs_value", "commercial_invoice", "importer_tax_id", "broker_credentials", "hs_code"];

function redactFlexportLog(record: Record<string, unknown>): Record<string, unknown> {
  const redacted = { ...record };
  for (const field of FLEXPORT_SENSITIVE_FIELDS) {
    if (field in redacted) redacted[field] = "[REDACTED]";
  }
  return redacted;
}

Security Checklist

[ ] API keys stored in secrets manager, .env files in .gitignore
[ ] Webhook signatures verified on every inbound request
[ ] Different keys for dev/st
                
              

                
                  
                  
                  flexport-upgrade-migration
                  SKILL.md
                  View full skill →
                
                
                  Migrate between Flexport API versions (v1 to v2, Logistics API versions).
                  
                      ReadWriteEditBash(npm:*)Grep
                    
                
                
                  Flexport Upgrade & Migration
Overview
Guide for migrating between Flexport API versions. The main API uses Flexport-Version header (currently 2). The Logistics API has dated versions (2023-10, 2024-04). Breaking changes are versioned -- old versions remain available during deprecation windows.
Instructions
Step 1: Identify Current API Usage

# Find all Flexport API calls in your codebase
grep -rn "Flexport-Version\|api.flexport.com\|logistics-api.flexport.com" src/ --include="*.ts" --include="*.py"

# Check which version header you're sending
grep -rn "Flexport-Version" src/ --include="*.ts"

Step 2: API v1 to v2 Migration

Change
v1
v2


Header
Flexport-Version: 1
Flexport-Version: 2


Response wrapper
{ "_object": "Shipment", ... }
{ "data": { ... } }


Pagination
{ "next": "/shipments?page=2" }
{ "data": { "records": [], "total_count": N } }


Error format
{ "errors": [...] }
{ "error": { "code": "...", "message": "..." } }


Date format
Mixed
ISO 8601 consistently



// v1 pattern (deprecated)
const res = await fetch(`${BASE}/shipments`, { headers: { 'Flexport-Version': '1' } });
const { _object, id, status } = await res.json();

// v2 pattern (current)
const res = await fetch(`${BASE}/shipments`, { headers: { 'Flexport-Version': '2' } });
const { data } = await res.json();
data.records.forEach(s => console.log(s.id, s.status));

Step 3: Logistics API Version Migration

// The Logistics API has separate versioned URLs
// Old: https://docs.logistics-api.flexport.com/2023-10/
// New: https://docs.logistics-api.flexport.com/2024-04/

// Check OpenAPI spec for changes
// https://logistics-api.flexport.com/logistics/api/2024-04/documentation/raw

Step 4: Dual-Version Testing

// Run both versions in parallel during migration
async function migrateEndpoint(path: string) {
  const [v1Res, v2Res] = await Promise.all([
    fetch(`${BASE}${path}`, { headers: { ...auth, 'Flexport-Version': '1' } }),
    fetch(`${BASE}${path}`, { headers: { ...auth, 'Flexport-Version': '2' } }),
  ]);

  const v1 = await v1Res.json();
  const v2 = await v2Res.json();

  // Compare key fields to verify migration correctness
  console.log('v1 count:', v1.total || 'N/A');
  console.log('v2 co

                

              

                
                  
                  
                  flexport-webhooks-events
                  SKILL.md
                  View full skill →
                
                
                  Implement Flexport webhook event handling for shipment milestones, booking updates, purchase order events, and invoice notifications.
                  
                      ReadWriteEditBash(npm:*)Bash(curl:*)
                    
                
                
                  Flexport Webhooks & Events
Overview
Flexport sends webhook notifications for shipment milestones, booking confirmations, PO updates, invoice events, and document availability. Webhooks are configured in Portal > Settings with a secret token for HMAC-SHA256 signature verification via the X-Hub-Signature header.
Webhook Event Types

Category
Events
Use Case


Milestones
cargoready, departed, arrived, customscleared, delivered
Shipment tracking


Transit
estimateddeparture, estimatedarrival, actual_departure
ETA updates


Bookings
bookingconfirmed, bookingamended
Booking lifecycle


Purchase Orders
pocreated, poupdated, po_archived
PO management


Invoices
invoicecreated, freightinvoice_ready
Billing


Documents
documentuploaded, billofladingready
Document management


Container
containerloaded, containerunloaded
Container tracking


Instructions
Step 1: Create Webhook Endpoint in Flexport
Navigate to Portal > Settings > Webhooks > Add Endpoint:

URL: https://your-app.com/webhooks/flexport
Secret: Generate a strong random string
Events: Select event types to subscribe to

Step 2: Implement Webhook Handler

import crypto from 'crypto';
import express from 'express';

const app = express();

// IMPORTANT: Use raw body for signature verification
app.post('/webhooks/flexport', express.raw({ type: '*/*' }), async (req, res) => {
  // Step 1: Verify signature
  const signature = req.headers['x-hub-signature'] as string;
  const expected = 'sha256=' + crypto
    .createHmac('sha256', process.env.FLEXPORT_WEBHOOK_SECRET!)
    .update(req.body)
    .digest('hex');

  if (!crypto.timingSafeEqual(Buffer.from(signature), Buffer.from(expected))) {
    console.error('Invalid webhook signature');
    return res.status(401).send('Invalid signature');
  }

  // Step 2: Parse and route event
  const event = JSON.parse(req.body.toString());
  console.log(`Webhook: ${event.type} | ID: ${event.data?.id}`);

  try {
    await routeEvent(event);
    res.status(200).send('OK');
  } catch (err) {
    console.error('Webhook processing failed:', err);
    res.status(500).send(&#

                

              

          

        


      
      

      
      

      
      

      
      
  Ready to use flexport-pack?
  
    
    
  




      
      
          Related Plugins
          
            
                excel-analyst-pro
                Professional financial modeling toolkit for Claude Code with auto-invoked Skills and Excel MCP integration. Build DCF models, LBO analysis, variance reports, and pivot tables using natural language.
              
                brand-strategy-framework
                A 7-part brand strategy framework for building comprehensive brand foundations - the same methodology top agencies use with Fortune 500 clients.
              
                clay-pack
                Complete Clay integration skill pack with 30 skills covering data enrichment, waterfall workflows, AI agents, and GTM automation. Flagship+ tier vendor pack.
              
                instantly-pack
                Complete Instantly integration skill pack with 24 skills covering cold email, outreach automation, and lead generation. Flagship tier vendor pack.
              
                apollo-pack
                Complete Apollo integration skill pack with 24 skills covering sales engagement, prospecting, sequencing, analytics, and outbound automation. Flagship tier vendor pack.
              
                juicebox-pack
                Complete Juicebox integration skill pack with 24 skills covering people data, enrichment, contact search, and AI-powered discovery. Flagship tier vendor pack.
              
          
        

      
      
          Tags
          
            flexportsaassdkintegration
          
        
    

  

  

    

    
    
        
            
                Stay in the Loop
                
                    
                    
                    
                
                No spam. Unsubscribe anytime.
            

            
                
                    Product
                    
                        Explore
                        Skills
                        Cowork
                        Compare
                        Tools
                    
                
                
                    Resources
                    
                        Docs
                        Changelog
                        Collections
                        Playbooks
                        Research
                        Learning
                    
                
                
                    Company
                    
                        Community
                        Spotlight
                        GitHub
                    
                
                
                    Legal
                    
                        Privacy
                        Terms
                        Acceptable Use
                    
                
            

            
                Tons of Skills by Intent Solutions. Marine. Citadel Grad. 20 years ops → self-taught dev → AI architect.
                © 2026 Tons of Skills | Intent Solutions

Field	Issue	Fix
`origin_port.code`	Not a valid UN/LOCODE	Use `CNSHA`, `USLAX`, `DEHAM` format
`hs_code`	Wrong format	Use 6-10 digit codes like `8479.89`
`cargoreadydate`	In the past	Use future ISO date
`freight_type`	Unsupported value	Use `ocean`, `air`, or `trucking`
`incoterm`	Invalid	Use `FOB`, `CIF`, `EXW`, `DDP`

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

Data Type	Sensitivity	Retention	Encryption
Shipment records	Medium	1 year post-delivery	AES-256 at rest
Customs declarations	High (trade compliance)	5 years (CBP requirement)	AES-256 + TLS
Commercial invoices	High (financial)	7 years (tax/audit)	AES-256 at rest
Contact PII (shipper/consignee)	High	Until deletion request	Field-level encryption
Tracking events	Low	90 days	TLS in transit

Role	API Key Scope	Allowed Endpoints	Use Case
Viewer	Read-only	`GET /shipments`, `GET /products`	Dashboard users
Operator	Read-write	`GET/POST /bookings`, `GET/PATCH /purchase_orders`	Ops team
Finance	Read invoices	`GET /freightinvoices`, `GET /commercial``invoices`	Finance team
Admin	Full access	All endpoints	System administrators