Migrate between Flexport API versions (v1 to v2, Logistics API versions). Use when upgrading API version headers, handling deprecated endpoints, or migrating from legacy Flexport API patterns. Trigger: "upgrade flexport", "flexport API version", "flexport migration".
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.
# 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"
| 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));
// 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
// 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');
}
Flexport-Version header to 2_object to data.recordsFor CI integration during upgrades, see flexport-ci-integration.