Controlled Flexport Integration Migration

Overview

Migration is a sequence of read-only comparison, explicit field mapping, shadow evaluation, and one controlled write owner. Never dual-book freight or dual-create trade records merely to compare systems.

Prerequisites

• Endpoint/tool inventory with read/write classification
• Captured account default version and any Flexport-Version overrides
• Business-key mapping, rollback plan, and reconciliation owner

Instructions

Step 1: Inventory reality

Trace every legacy path, version header, response assumption, event name, expansion, credential, and mutation.

Step 2: Map to documented targets

Choose current v3 REST endpoints or MCP tools by outcome. Record unsupported fields/operations rather than guessing equivalents.

Step 3: Build tolerant readers

Accept documented envelopes and additive fields, preserve opaque identifiers, and add sanitized fixtures for old/new differences.

Step 4: Shadow reads only

Compare current and target read paths over an approved sample. Normalize only business facts and investigate discrepancies.

Step 5: Cut over one writer

Freeze the legacy mutation queue, reconcile in-flight operations, switch one authoritative writer, and retain a rapid rollback that cannot produce concurrent writes.

Step 6: Verify and retire

Reconcile provider resources, events, and local operation keys across the cutover window before removing old credentials/code.

Authentication

REST calls authenticate with a cached OAuth 2.0 client-credentials Bearer token using audience https://api.flexport.com, or an explicitly accepted broad API key. Use distinct credentials per workload and never log credentials or tokens. MCP calls use the authenticated connection to https://mcp.flexport.com/mcp and remain subject to each tool's documented account permissions.

Tool Discipline

Use Read and Grep for discovery and evidence. Use Write or Edit only for the approved artifact, code, configuration, test, or receipt described by this workflow; do not make an unapproved Flexport-side change.

Output

• Scoped decision or implementation artifact
• Redacted operation and validation receipt
• Failure, rollback, and follow-up ownership record

Return a machine-reviewable receipt in this shape; adapt the operation values, but never place credentials or provider payloads in it:

surface: rest-v3
operation: shipment-read
decision: approved
outcome: verified
evidence:
  release_sha: recorded-out-of-band
  provider_reference: redacted
rollback_owner: logistics-platform

Examples

A v2-era shipment reader moves to v3 with an explicit version override and tolerant fields. Its booking path remains unchanged until a separate approved cutover can guarantee one writer and reconcile every in-flight booking.

Error Handling

Failure	Response
No mapping for a legacy field	Escalate the business dependency; do not fabricate a target.
Read comparison diverges	Pause cutover and verify version, expansion, pagination, and semantics.
Both writers become active	Freeze both, reconcile provider state, and restore one owner.
Rollback could duplicate freight	Do not execute it until operation identities are reconciled.

Resources

• First-party source notes
• Versioning
• Flexport v3 API reference
• MCP tools