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.

Prerequisites

• Protected CI environments with sandbox secrets available only to trusted jobs.
• Fictional shipment fixtures, approved data mappings, and a named deployment/rollback owner.

Instructions

1. Run unit and schema tests with mocked data on pull requests and do not expose secrets to forks.
2. Limit authenticated sandbox checks to protected merges, with minimum scopes and redacted output.
3. Validate destination allowlists, idempotency, and failure paths before an approved canary deployment.

Output

Publish a CI receipt with commit SHA, fixture version, checks run, aggregate result, sandbox approval, and redacted failure reference. Exclude logistics payloads, documents, and credentials.

Examples

A pull request validates a fictional port-to-status mapping without credentials. A protected post-merge job processes one sandbox event and fails the release if an unexpected field or destination appears, retaining only the opaque event ID.

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: …

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.

Prerequisites

• An authorized support role, opaque correlation ID, redacted telemetry, and a safe sandbox or read-only reproduction path.
• An incident owner for credentials, shipment data, customs documents, and external notifications.

Instructions

1. Classify the failure as authentication, authorization, schema, throttling, upstream availability, or delivery.
2. Reproduce with a fictional or read-only sandbox request before retrying a production operation.
3. Check scoped credentials, environment, payload schema, target/destination policy, and queue state in order.
4. Apply the smallest reversible correction, verify success and safe failure behavior, and escalate possible exposure immediately.

Error Handling

• Do not retry permission failures with broader keys; route them to the authorized owner.
• Bound retry/backoff, maintain idempotency, and quarantine exhausted work for review.
• Redact commercial terms, addresses, invoices, documents, and headers from support evidence.

Output

Return a diagnostic receipt with the error category, opaque correlation ID, safe reproduction result, corrective action, verification, owner, and follow-up. Keep shipment records, commercial documents, addresses, and credentials in authorized systems rather than the receipt.

Examples

Use a synthetic booking to trigger a controlled validation error, correct the field mapping, and verify the result using only an opaque identifier. On a permission failure, pause the worker until the approved owner validates a least-privilege sandbox request.

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 Fou…

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.

Output

Create an auditable workflow receipt with opaque booking/PO identifiers, authorized owner, validation state, approved destination, idempotency result, and next action. Keep commercial terms, addresses, documents, and cargo details inside the authorized system of record.

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…

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.

Output

Maintain an approved workflow receipt with opaque invoice/product identifiers, authorized owner, source-validation status, approved destination, idempotency outcome, and next action. Keep commercial terms, invoice contents, tariff data, and documents in the authorized system of record.

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…

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.

Prerequisites

• Current contract/billing data and provider limits reviewed by the account owner, not inferred from this guide.
• Aggregate usage metrics, an approved target/data policy, and a named budget owner.
• Synthetic staging workload plus a rollback switch for caching, polling, or batch changes.

Output

Record a cost-control receipt with measurement window, aggregate usage, approved optimization, owner decision, expected effect, verification date, and rollback state. Do not include invoices, commercial terms, shipment content, or credentials.

Error Handling

• Stop a change if it violates freshness, access, retention, or target policy even if it reduces calls.
• Reduce load and use bounded retries on throttles; do not increase polling after a delivery gap.
• Revert a cache or webhook switch if reconciliation detects missed or duplicate events.

Examples

Compare a fictional webhook-driven workflow with a low-frequency staging poll using only request counts and synthetic event delivery. Promote the reduction only if reconciliation proves no missed/duplicate event and the data-access policy remains unchanged.

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

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.

Prerequisites

• A documented data inventory, authorized processing purpose, owners, destination allowlist, retention/deletion schedule, and legal review where required.
• Encryption, access control, redaction, and secure-evidence procedures appropriate to each classified data type.

Instructions

1. Minimize imports to approved fields and process sensitive records only in authorized systems.
2. Enforce access and retention at every storage and downstream handoff; use opaque IDs in diagnostics.
3. Test mappings with fictional data, reconcile only approved aggregate values, and obtain owner approval before cutover.
4. Quarantine unknown fields, unapproved destinations, and retention conflicts for review instead of forwarding them.

Output

Create a processing receipt with source reference, field classification, approved destination, retention rule, aggregate validation outcome, owner, and exception state. Keep source payloads, documents, addresses, and credentials outside the receipt.

Examples

Transform a fictional shipment containing invented contact and product data using a field allowlist. Confirm the destination receives only approved fields, logs contain an opaque ID and aggregate counts, and the test data is removed on the defined schedule.

Data Classification

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; car…

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.

Prerequisites

• An incident owner, secure evidence location, retention date, and redaction rules for logistics and credential data.
• An opaque correlation ID and a safe sandbox/read-only reproduction path.

Output

Create a redacted evidence index with runtime versions, configuration references, opaque correlation ID, aggregate diagnostics, access owner, retention date, and next action. Store sensitive originals only in the approved incident location.

Error Handling

• Stop bundle generation if it contains a key, address, invoice, customs document, or raw shipment payload; rotate credentials if exposure is possible.
• Record diagnostic gaps explicitly rather than broadening collection.
• Escalate suspected data exposure before continuing support work.

Examples

For a synthetic rate-limit failure, retain only the runtime version, opaque request ID, configured policy reference, and aggregate retry count. Review the archive for sensitive data, grant it solely to the incident owner, and delete it at the stated retention date.

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

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.

Prerequisites

• A deployment owner, approved logistics-data destinations, scoped secret-manager references, and tested rollback path.
• A staging environment with fictional shipments and a policy that excludes commercial documents from logs and health checks.

Output

Record the release/image identifier, environment, integration owner, approved destinations, canary result, aggregate health metrics, and rollback outcome. Do not include credentials, bills of lading, addresses, invoices, or shipment payloads.

Error Handling

• Stop promotion on signature, permission, destination, or idempotency failures.
• Pause workers and rotate scoped credentials when an exposure is suspected.
• Preserve only redacted incident evidence and use the rollback path before replaying events.

Examples

Deploy a staging receiver with a fictional shipment event, verify the signature and opaque event ID, then simulate an upstream failure. The service must return a generic health result, avoid logging the payload, and roll back the canary before production sync is enabled.

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 \
 …

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.

Prerequisites

• A role owner, current access matrix, least-privilege credential allocation, and periodic access-review schedule.
• Approved endpoint/data classifications and synthetic fixtures that can test authorization without a real shipment.

Output

Maintain an RBAC receipt with role, allowed operation class, policy version, access-review date, approver, and revocation outcome. Never include credentials, customer identifiers, commercial records, or documents.

Error Handling

• Deny unknown roles, paths, methods, and cross-tenant requests by default.
• Alert the policy owner on repeated authorization failures and suspend a credential if misuse is suspected.
• Preserve redacted evidence only and require review before expanding a role or endpoint policy.

Examples

Give a temporary test role access to a fictional shipment status only, attempt an invoice read, and verify it is denied. Remove the role and confirm the status access is revoked, recording only opaque test IDs and decisions.

Instructions

Step 1: Define Roles

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 =…

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

• FLEXPORT_API_KEY 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

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.

Prerequisites

• An incident commander, communication owner, secure evidence location, credential-revocation path, and rollback operator.
• Redaction rules for commercial terms, addresses, customs documents, invoice details, and shipment payloads.

Instructions

1. Assign severity and an opaque incident ID; pause unsafe booking, sync, or notification workflows.
2. Classify the event as availability, authorization, delivery, data-integrity, policy, or suspected exposure.
3. Apply the smallest safe mitigation, verify recovery using a sandbox/read-only probe, and test a safe failure path.
4. Rotate/revoke credentials when exposure is possible and resume queues only after idempotency and destination checks pass.
5. Record the timeline, impact, mitigation, owner, and post-incident follow-up.

Output

Produce a redacted incident receipt with severity, opaque ID, impact, mitigation, recovery verification, rollback/revocation decision, and follow-ups. Sensitive evidence stays in the approved incident store.

Examples

For a simulated webhook outage, pause the staging worker and verify no milestone is replayed twice. Restore one synthetic canary event after health recovers, then resume only when the incident commander records the recovery evidence.

Severity Levels

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 | j…

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.

Output

Record only the authentication method, approved scope, secret-manager reference, validation time, owner, and revocation/rotation procedure. Do not include an API key, token, client secret, or any logistics response data.

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:

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: p…

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.

Prerequisites

• Fictional fixtures only, a local directory excluded from version control, and an approved sandbox/read-only test path.
• Separate developer credentials supplied through an approved secret manager, never copied into fixtures or shell history.

Output

Produce a local test receipt with fixture version, schema/contract result, opaque correlation IDs, and redacted failures. No real shipment, address, invoice, customs, or credential data belongs in the repository.

Error Handling

• Stop fixture generation if it contains real exports, documents, or identifiers; replace with synthetic values.
• Treat schema and authorization mismatches as review items rather than widening scope or retrying production actions.
• Revoke a test credential and report a redacted incident if exposure is possible.

Examples

Test a fictional container event with an opaque ID and invented ports. Run offline unit tests, confirm no network call is made, then validate a read-only sandbox probe separately. Ensure deleting the fixture removes every local derived artifact.

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>…

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.

Prerequisites

• Authorized migration scope, owners for product/shipment/document data, retention requirements, and legal/compliance review where required.
• An inventory of source fields, approved target mappings, sandbox fixtures, rollback, and reconciliation owners.

Output

Maintain a migration receipt with source/target scope, field classification, staged validation, aggregate reconciliation, approver, rollback status, and unresolved exceptions. Keep invoices, customs documentation, addresses, and commercial terms in approved systems only.

Error Handling

• Stop a migration batch on unknown mapping, unauthorized destination, or aggregate reconciliation mismatch.
• Quarantine failures by opaque ID and route them to the data owner instead of retrying with expanded permissions.
• Restore the prior integration path before repeating a failed production cutover.

Examples

Migrate a fictional product and shipment record through staging, compare only approved identifiers and aggregate counts, then deliberately introduce an unknown tariff field. Confirm the batch stops for review without exposing the source record or proceeding to production.

Migration Scenarios

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 (e…

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.

Prerequisites

• Distinct environment identities, secret references, webhook routes, approved data destinations, and accountable owners.
• Guardrails that prevent development/PR workloads from querying production or receiving production webhooks.

Output

Record an environment-control receipt with identity references, allowed destinations, policy version, validation outcome, owner, and rollback path. Do not include keys, shipment data, or documents.

Error Handling

• Deny an environment mismatch before an API call and alert the environment owner.
• Rotate/revoke the affected credential after suspected cross-environment access.
• Roll back configuration changes that bypass target, destination, or secret isolation.

Examples

Send a fictional event to staging and verify the development key cannot authenticate there and no staging route can call a production destination. Rotate the staging credential, prove the old key is denied, and store only redacted test evidence.

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_S…

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.

Prerequisites

• An approved telemetry schema using aggregate measurements and opaque correlation IDs.
• Named alert owners, escalation thresholds, secure dashboard access, retention rules, and synthetic alert fixtures.

Output

Publish an observability receipt with metric definitions, dashboard/alert references, threshold tests, owner, and review date. Metrics, traces, and logs must exclude shipment payloads, addresses, invoices, documents, and credentials.

Error Handling

• Reject telemetry fields that contain sensitive logistics data or headers.
• Alert on unexpected destination, queue, access, or integrity anomalies and route them to the incident owner.
• Suppress noise only through a documented time-bound rule that preserves incident visibility.

Examples

Send one successful and one rejected fictional event. Confirm dashboards report only aggregate outcomes and opaque IDs, an alert fires at the agreed threshold, and no payload or secret appears in the alert message.

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 …

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.

Prerequisites

• A redacted baseline for latency, error rate, queue age, and budget/rate use; define freshness requirements per data class.
• Synthetic staging data, bounded concurrency, cache invalidation rules, and a rollback switch.

Output

Publish a performance receipt with baseline/post-change aggregate metrics, cache/concurrency settings, freshness rule, policy owner, and rollback result. Do not put logistics payloads or credentials into telemetry.

Error Handling

• Reduce concurrency and honor throttle responses rather than increasing retries during a limit breach.
• Invalidate or disable a cache when access, freshness, or data-isolation controls cannot be demonstrated.
• Quarantine unexpected results for review and revert the canary before a broad rollout.

Examples

Replay a fictional shipment list in staging at low concurrency, enable a bounded cache, and compare only aggregate latency and cache-hit metrics. Simulate a permission change to ensure the cache does not serve data to an unauthorized consumer; revert if it does.

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(() => f…

Flexport Production Checklist

Overview

Pre-deployment and go-live checklist for Flexport logistics integrations covering API configuration, webhook setup, monitoring, and rollback procedures.

Prerequisites

• A launch owner, approver, rollback operator, approved data-flow inventory, and staging evidence using fictional shipments.
• Redacted monitoring, explicit target/destination policies, and a secure path for credentials and incident evidence.

Instructions

1. Attach evidence or an owner decision for every applicable checklist control; leave no implicit acceptance.
2. Verify scoped secrets, signature validation, idempotent processing, redacted diagnostics, and retention/access behavior.
3. Run a small staging or production canary with synthetic data and observe aggregate health, queue, and delivery outcomes.
4. Stop promotion and invoke rollback on permission, policy, integrity, or safety thresholds; record the decision and recovery test.

Output

Create a go-live receipt with completed controls, evidence links, canary metrics, exceptions, approver, launch/rollback owners, and follow-up dates. Keep documents, addresses, commercial terms, and credentials out of it.

Error Handling

• Pause unsafe automation or notifications on signature, permission, destination, or reconciliation failures.
• Quarantine failed work by opaque ID and rotate credentials if exposure is possible.
• Confirm rollback and no unintended replay before resolving the launch incident.

Examples

Process a fictional shipment milestone through the canary, revoke a test destination’s access, and simulate an upstream outage. Promote only after the designated approver records that the handler paused safely, produced redacted metrics, and rolled back cleanly.

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-s…

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.

Prerequisites

• Current account limits confirmed from the provider, with a named concurrency/budget owner and reviewed exception queue.
• Aggregate telemetry that excludes shipment records, documents, commercial terms, and credentials.
• Sandbox fixtures that exercise throttling, pause/retry, and duplicate prevention.

Output

Produce a rate-control receipt with policy version, concurrency, retry bound, throttle count, queue age, idempotency outcome, and manual dispositions. Do not log payloads or headers containing secrets.

Examples

Run a fictional shipment event under a low concurrency limit, simulate a 429, and confirm the worker honors its bounded wait and processes the opaque event once after recovery. Repeated failures enter review rather than causing a bulk replay.

Rate Limit Headers

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 de…

Flexport Reference Architecture

Overview

Production reference architecture for Flexport logistics integrations. Three core services: Ingest (webhooks + polling), Core (business logic), and Expose (API + dashboard).

Prerequisites

• A data-flow inventory naming system owners, approved destinations, retention rules, endpoint scopes, and trust boundaries.
• Separate identities for ingress, workers, storage, dashboards, and integrations; use synthetic fixtures for every architecture test.

Instructions

1. Verify webhook signatures at ingress and enqueue opaque event IDs for idempotent processing.
2. Apply field allowlists and access checks before storage, dashboard exposure, or downstream notifications.
3. Define cache freshness, rate limits, retry bounds, audit logging, and a disable/rollback switch per service boundary.
4. Promote architecture changes through staging with fictional data and review aggregate canary evidence before production.

Output

Maintain an architecture decision record showing trust boundaries, source-of-truth assignments, data destinations, access/retention controls, owners, and rollback mechanisms. Do not include shipments, documents, commercial terms, or secrets.

Error Handling

• Quarantine events with unknown schemas, destinations, or permissions rather than forwarding them.
• Isolate a failed service boundary, disable unsafe consumers, and preserve only redacted evidence.
• Restore the prior routing/configuration before replaying queued work after an incident.

Examples

Route a fictional milestone through ingress, queue, core, and a staging dashboard. Confirm duplicate suppression, denied access for an unapproved consumer, and a controlled rollback that leaves no shipment payload in logs.

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)           │
└───────────────────────────────────────────────────…

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.

Prerequisites

• Scoped credentials from the secret manager, approved endpoint/destination policies, and fictional sandbox fixtures.
• An idempotency/retry design, redacted telemetry, and a clear owner for schema or permission failures.

Output

Return a client-validation receipt with contract version, fixture version, aggregate schema result, idempotency behavior, owner, and redacted failure reference. Do not log headers, documents, or shipment payloads.

Examples

Use a fictional shipment with an opaque ID to exercise pagination and a schema error. Verify that a retry cannot duplicate a write and that a rejected field is quarantined for review rather than forwarded to an external system.

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.getInst…

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.

Prerequisites

• A named security owner, scoped secret-manager integration, access-review cadence, and approved destinations for logistics data.
• Synthetic shipment fixtures and a defined incident/revocation path.

Instructions

1. Issue least-privilege credentials per environment and integration; never put keys or secrets in source, tickets, shell history, or support bundles.
2. Verify webhook signatures using raw bodies, record opaque event identifiers only, and enforce idempotency before downstream processing.
3. Restrict access to shipping, customs, invoice, and partner data; review connected systems and remove access when the business need ends.
4. Redact diagnostics, encrypt approved exports, and rotate/revoke credentials immediately after suspected exposure.

Output

Maintain a security receipt with access owner, secret reference, approved integration, review date, rotation/revocation outcome, and redacted incident status. Never include data, documents, or keys.

Examples

Use a fictional booking event and scoped staging credential to verify that an invalid signature is rejected, a duplicate is suppressed, and revoking the credential blocks future requests. Keep only the opaque event ID and control outcome in the evidence.

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.st…

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.

Prerequisites

• Current vendor release information and an inventory of version headers, endpoints, mappings, consumers, and retention rules.
• Sandbox access, fictional shipment fixtures, a rollback owner, and explicit reconciliation criteria.

Output

Keep an upgrade receipt listing versions reviewed, affected mappings, sandbox result, canary result, reconciliation evidence, approver, and rollback decision. Exclude commercial documents, addresses, invoice details, and credentials.

Error Handling

• Classify unexpected response changes as schema, permission, pagination, delivery, or retention failures.
• Stop promotion and restore the prior version/mapping on a mismatch; do not bulk replay live bookings or documents to diagnose it.
• Quarantine failed records by opaque identifier for reviewed reconciliation.

Examples

Run old and proposed headers against a fictional sandbox shipment, compare only approved schema fields and aggregate results, and test an unauthorized response. If any mapping or access behavior changes unexpectedly, disable the canary and retain the prior path pending review.

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

// v1 pattern (deprecated)
const res = await fe…

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.

Prerequisites

• A signing secret in the secret manager, raw-body verification, an event ledger, and a reviewed exception queue.
• Approved downstream destinations, data-minimization rules, and synthetic event fixtures.

Output

Return a receipt with opaque event ID, signature result, handler version, idempotency outcome, destination status, and redacted error category. Keep shipment payloads, commercial documents, and credentials out of logs.

Examples

Send a fictional milestone event twice. The receiver verifies its signature, processes the first event once, records the second as a duplicate, and rejects an invalid signature without logging the body or forwarding any data.

Webhook Event Types

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…