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

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 count:', v2.data?.total_count || 'N/A');
}

Migration Checklist

Update Flexport-Version header to 2
Update response parsing from _object to data.records
Update pagination logic for v2 format
Update error handling for v2 error format
Run test suite against v2 endpoints
Deploy to staging and verify
Monitor error rates after production deployment

Resources

Next Steps

For CI integration during upgrades, see flexport-ci-integration.