> ## Documentation Index
> Fetch the complete documentation index at: https://terminal49.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.
# Migrating from Vizion
> Map Vizion container tracking reference IDs, webhooks, and API fields to their Terminal49 equivalents. Includes authentication, request mapping, and migration checklist.
If you have the Vizion tracking API in production, this page maps it onto Terminal49 field by field, so you can cut over without reverse-engineering our schema.
There is no compatibility shim. You will change your request code and your response parsing. Because Vizion and Terminal49 are architecturally similar, this is mostly a rename and reshape migration.
## Start in sixty seconds
You do not need to talk to anyone to try this.
Sign up at [app.terminal49.com](https://app.terminal49.com). The free Developer Key tracks up to 10 active containers.
Create a key at [app.terminal49.com/developers/api-keys](https://app.terminal49.com/developers/api-keys).
```bash theme={null}
curl -X POST https://api.terminal49.com/v2/tracking_requests \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Token YOUR_API_KEY" \
-d '{
"data": {
"type": "tracking_request",
"attributes": {
"request_number": "YOUR_BOL_NUMBER",
"request_type": "bill_of_lading",
"scac": "MAEU"
}
}
}'
```
The full API key is shown once, right after you create it. Copy it before you navigate away. After that it is masked and cannot be revealed. If you miss it, create a new key and delete the old one.
If you want to test without a live shipment, use the [test tracking numbers](/docs/api-docs/useful-info/test-numbers), which simulate success, failure, and edge-case outcomes.
## The architectural shift
Vizion and Terminal49 already think the same way: create a reference once, receive updates via webhooks or poll the reference. The shift is what we attach to that reference.
Create a reference via POST /references. Poll GET /references/{id}/updates or receive webhooks. Parse flat JSON responses and map Vizion event names to your internal model.
POST /tracking\_requests once. Terminal49 polls carriers, terminals, and rail, then POSTs to your endpoint as things change. Container objects carry holds, fees, and last free day directly.
The biggest difference is not the workflow. It is the data surface. Terminal49 integrates directly with terminals, not just carriers, so the container object carries operational data that has no Vizion equivalent.
## Quick comparison
| | Vizion | Terminal49 |
| ----------------------- | ------------------------------------------------- | ------------------------------------- |
| Tracking model | Reference subscription, then push or poll | Register once, then push or poll |
| Authentication | API key header (format varies by plan) | `Authorization: Token` header |
| Base URL | `https://api.vizionapi.com` | `https://api.terminal49.com/v2` |
| Content type | `application/json` | `application/vnd.api+json` |
| Response format | Custom JSON | JSON:API |
| Webhooks | Subscription-based | 30+ events, HMAC-signed |
| Carrier identification | Carrier reference or SCAC | `scac`, or omit and use Infer |
| Terminal holds and fees | Not available | Included on the container object |
| Last free day | Not available | Included, with per-source breakdown |
| Rail milestones | Limited | North American Class I and short-line |
| Getting an API key | Typically requires sales contact for higher tiers | Self-serve |
## Authentication
Move from Vizion's key header to Terminal49's `Token` prefix. Note the content type change.
```bash Vizion theme={null}
curl -X POST https://api.vizionapi.com/v1/references \
-H "Content-Type: application/json" \
-H "Authorization: YOUR_VIZION_KEY" \
-d '{"container": "MRKU9465770", "carrier": "MAEU"}'
```
```bash Terminal49 theme={null}
curl -X POST https://api.terminal49.com/v2/tracking_requests \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Token YOUR_T49_KEY" \
-d '{"data":{"type":"tracking_request","attributes":{
"request_number":"MRKU9465770",
"request_type":"container",
"scac":"MAEU"}}}'
```
Note the `Token` prefix. It is not `Bearer`.
Vizion's exact header format varies by plan or integration type. If you pass the key in a custom header like `x-api-key`, the change is the same: move the value into `Authorization: Token YOUR_T49_KEY`.
## Request parameter mapping
| Vizion parameter | Terminal49 equivalent | Notes |
| ------------------------------- | ------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `container` or `bill_of_lading` | `request_number` | One identifier per tracking request |
| `carrier` | `scac` | Same SCAC values for most carriers |
| `carrier` omitted | Omit `scac`, or call [Infer Tracking Number](/docs/api-docs/in-depth-guides/auto-detect-carrier) | Returns the predicted SCAC and number type |
| `callback_url` | `POST /v2/webhooks` | Register once, subscribe to specific events |
| \[provider's refresh field] | `POST /v2/containers/{id}/refresh` | Forces an immediate pull from all sources |
| \[provider's reference tagging] | `shipment.attributes.reference_numbers` | Tag shipments with your internal IDs |
Vizion accepts a carrier reference or name alongside the number. Terminal49 takes a SCAC (`request_type` + `scac`) or omits the SCAC to use Infer. Track by BOL and we return every container on that bill of lading as related container resources.
## Response field mapping
Terminal49 is JSON:API compliant, so relationships between shipments, containers, ports, and terminals are explicit rather than something you reassemble from ID references.
Use the [`include` parameter](/docs/api-docs/in-depth-guides/including-resources) to sideload related resources in one call instead of chasing IDs.
### Shipment level
| Vizion | Terminal49 |
| ---------------------------------------- | -------------------------------------------- |
| \[provider's shipment number field] | `shipment.attributes.bill_of_lading_number` |
| \[provider's carrier field] | `shipment.attributes.shipping_line_scac` |
| \[provider's carrier name field] | `shipment.attributes.shipping_line_name` |
| \[provider's shipment status field] | Derived from container status and milestones |
| \[provider's origin location field] | `shipment.relationships.port_of_lading` |
| \[provider's destination location field] | `shipment.relationships.port_of_discharge` |
| \[provider's inland destination field] | `shipment.relationships.destination` |
| \[provider's ETA field] | `shipment.attributes.pod_eta_at` |
| \[provider's vessel name field] | `shipment.attributes.pod_vessel_name` |
| \[provider's vessel IMO field] | `shipment.attributes.pod_vessel_imo` |
### Container level
| Vizion | Terminal49 |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| \[provider's container number field] | `container.attributes.number` |
| \[provider's ISO code field] | `container.attributes.equipment_type` + `equipment_length` + `equipment_height` |
| \[provider's container size/type field] | Same three fields above |
| \[provider's container status field] | `container.attributes.current_status` |
| \[provider's events array] | Container timestamps, [transport events](/docs/api-docs/api-reference/containers/get-a-containers-transport-events), and webhook events |
Vizion returns a single ISO code string like `45G1`. Terminal49 splits this into three normalized fields: type (dry, reefer, open top, flat rack, tank, hard top), length (20, 40, 45, 50), and height (standard, high cube). If you were parsing ISO codes yourself, you can delete that code.
### Locations, facilities, and vessels
| Vizion | Terminal49 |
| ------------------------------------------ | ------------------------------------------------------------------------------------------- |
| \[provider's port name field] | `port.attributes.name` |
| \[provider's port UN/LOCODE field] | `port.attributes.code` |
| \[provider's port lat/lng fields] | `port.attributes.latitude` / `.longitude` |
| \[provider's port timezone field] | `port.attributes.time_zone` |
| \[provider's port country field] | `port.attributes.country_code` |
| \[provider's terminal name field] | `terminal.attributes.name` |
| \[provider's terminal SMDG field] | `terminal.attributes.smdg_code` |
| \[provider's terminal BIC field] | `terminal.attributes.bic_code` |
| \[provider's vessel name field] | `shipment.attributes.pod_vessel_name` |
| \[provider's vessel IMO field] | `shipment.attributes.pod_vessel_imo` |
| \[provider's vessel MMSI field] | Available via the [Vessels API](/docs/api-docs/api-reference/vessels/get-a-vessel-using-the-imo) |
| \[provider's vessel call sign/flag fields] | Not returned |
## Milestone and event mapping
Vizion returns event arrays via updates or webhooks. Terminal49 exposes the same milestones as normalized transport events and pushes each one to your webhook.
| Vizion event | Milestone | Terminal49 event |
| -------------------------------- | ----------------------------- | --------------------------------------- |
| \[provider's loaded event] | Loaded on vessel at origin | `container.transport.vessel_loaded` |
| \[provider's departed event] | Vessel departed origin | `container.transport.vessel_departed` |
| \[provider's arrived event] | Vessel arrived at destination | `container.transport.vessel_arrived` |
| \[provider's discharged event] | Discharged from vessel | `container.transport.vessel_discharged` |
| \[provider's gated out event] | Gated out at destination | `container.transport.full_out` |
| \[provider's gated in event] | Gated in at origin | `container.transport.full_in` |
| \[provider's empty pickup event] | Empty picked up at origin | `container.transport.empty_out` |
| \[provider's empty return event] | Empty returned at destination | `container.transport.empty_in` |
Terminal49 also emits milestones Vizion has no equivalent for:
* **Vessel berthed:** `container.transport.vessel_berthed`
* **Available for pickup:** `container.transport.available` and `.not_available`
* **Transshipment:** arrived, discharged, loaded, departed
* **Feeder vessel and barge:** arrived, discharged, loaded, departed
* **Rail:** loaded, departed, arrived, unloaded, plus `arrived_at_inland_destination`
See the full [event catalog](/docs/api-docs/webhooks/event-catalog).
### Registering a webhook
```bash theme={null}
curl -X POST https://api.terminal49.com/v2/webhooks \
-H "Content-Type: application/vnd.api+json" \
-H "Authorization: Token YOUR_API_KEY" \
-d '{
"data": {
"type": "webhook",
"attributes": {
"url": "https://your-endpoint.example.com/t49",
"active": true,
"events": [
"container.transport.vessel_discharged",
"container.transport.available",
"container.pickup_lfd.changed"
]
}
}
}'
```
Payloads are HMAC-signed. See [webhook setup](/docs/api-docs/in-depth-guides/webhooks) for signature verification, and [List webhook IPs](/docs/api-docs/api-reference/webhooks/list-webhook-ips) if your firewall restricts inbound traffic.
## What you gain
This is the part worth reading even if the rest is mechanical. Terminal49 integrates with terminals directly, not only carriers, so the container object carries operational data that has no Vizion equivalent.
### Holds
`holds_at_pod_terminal` is an array of active holds blocking pickup:
```json theme={null}
{
"holds_at_pod_terminal": [
{ "name": "customs", "status": "hold", "description": "CBP HOLD" },
{ "name": "freight", "status": "hold", "description": null }
]
}
```
Hold names are `freight`, `customs`, `USDA`, `VACIS`, `TMF`, and `other`. Status is `hold` or `pending`. When a hold clears, the object is removed from the array. There is no released state.
Hold names are case-sensitive. `USDA`, `VACIS`, and `TMF` are uppercase; `freight`, `customs`, and `other` are lowercase. Match exactly.
### Fees
`fees_at_pod_terminal` carries type, amount, and currency:
```json theme={null}
{
"fees_at_pod_terminal": [
{ "type": "demurrage", "amount": 850.00, "currency_code": "USD" },
{ "type": "exam", "amount": 450.00, "currency_code": "USD" }
]
}
```
Fee types are `demurrage`, `extended_dwell_time`, `exam`, `total`, and `other`.
Some terminals report a `total` line item alongside individual fees. Filter it out before summing or you will double-count.
### Last free day
`pickup_lfd` is a coalesced value that follows a fixed source priority: shipping line, then terminal, then rail. It does not pick the earliest date. The individual sources are available separately on `import_deadlines`:
* `pickup_lfd_line`: the shipping line's LFD (per diem deadline)
* `pickup_lfd_terminal`: the terminal's LFD (demurrage deadline)
* `pickup_lfd_rail`: the rail carrier's LFD at the inland destination
Each has its own webhook event, so you can alert on whichever source your operation cares about.
### Release readiness
Two fields answer "can I pick this up?" `available_for_pickup` and the holds array:
```javascript theme={null}
function isReadyForPickup(container) {
const { available_for_pickup, holds_at_pod_terminal } = container.attributes;
const hasActiveHolds = holds_at_pod_terminal.some(h => h.status === 'hold');
return available_for_pickup === true && !hasActiveHolds;
}
```
Full detail in [Holds, Fees, and Release Readiness](/docs/api-docs/in-depth-guides/holds-and-fees).
Holds, fees, LFD, and availability come back on the container object wherever the terminal is a supported source. They are not a paid add-on and they do not require a sales conversation. See [Entitlements](/docs/api-docs/useful-info/entitlements) for the features that do require account enablement. Rail LFD and the embeddable widget are the main ones.
## Gotchas that will bite you
Vizion calls them references. Terminal49 calls them tracking requests. The lifecycle is the same: create, poll or webhook, delete. Just rename your internal variable and store the `tracking_request.id` where you stored `reference.id`.
Relationships are ID references into an `included` array. Use a JSON:API client library, or use `include` to sideload exactly what you need. Parsing raw JSON works but you will write more code than you expect.
Vizion may return local or UTC depending on the field. Terminal49 stores event timestamps in UTC and returns the matching IANA timezone alongside. Convert for display rather than assuming local time. See [Event Timestamps](/docs/api-docs/in-depth-guides/event-timestamps).
`holds_at_pod_terminal: []` and `fees_at_pod_terminal: []` mean no active holds or fees. This is the common case. Do not treat it as missing data.
Terminal changes (fees, holds, LFD, appointment, availability) arrive on `container.updated` with a `changeset` showing old value first, new value second. Use it instead of diffing state yourself.
`POST /tracking_requests` returns immediately with a pending status. The shipment appears once the carrier responds. Subscribe to `tracking_request.succeeded`, `tracking_request.failed`, and `tracking_request.awaiting_manifest` rather than expecting shipment data in the creation response. See [Tracking Request Lifecycle](/docs/api-docs/in-depth-guides/tracking-request-lifecycle).
## Error handling
Vizion returns errors in a response envelope or via HTTP status codes depending on the endpoint. Terminal49 uses standard HTTP status codes consistently. Replace envelope checks and message-string matching with status-code checks.
| Status | Meaning |
| ------ | -------------------------------------------------------------------------- |
| 400 | Malformed request or failed validation |
| 401 | Missing or invalid API key |
| 403 | Key lacks permission, or the feature is not enabled on your plan |
| 404 | Resource does not exist |
| 422 | Valid syntax, rejected content. For example, a malformed container number |
| 429 | Rate limited. See [Rate Limiting](/docs/api-docs/in-depth-guides/rate-limiting) |
| 5xx | Terminal49 or an upstream carrier or terminal is unavailable |
Rough equivalence for the Vizion errors you are handling today:
| Vizion error | Terminal49 |
| ------------------------------------ | ----------------------------------------------------------------------- |
| \[provider auth error] | HTTP 401 |
| \[provider permission error] | HTTP 403 |
| \[provider rate limit error] | HTTP 429 |
| \[provider validation error] | HTTP 400 or 422 |
| \[provider carrier not supported] | HTTP 422 |
| \[provider no data found] | `tracking_request.failed`, or `awaiting_manifest` if not yet manifested |
| \[provider temporary unavailability] | Not surfaced. We retry internally. |
The [TypeScript SDK](/docs/sdk/introduction) maps these to typed errors (`AuthenticationError`, `ValidationError`, `RateLimitError`, `UpstreamError`, `FeatureNotEnabledError`) and retries rate-limit and server errors automatically with exponential backoff.
## Where we are narrower than Vizion
Worth knowing before you commit.
**Carrier count.** Terminal49 integrates directly with 36 ocean carriers, plus 2 more enabled on request, as of 14 August 2026. Vizion lists substantially more. Ours are direct integrations covering the lines that move volume into North America, and each is normalized into one schema. Check your carrier mix against the [ocean carrier list](/docs/coverage/ocean-carriers) before cutover, and read the known issues section there. We publish the per-carrier field gaps.
**Terminal data is North America.** Holds, fees, LFD, and availability come from direct terminal integrations concentrated in the US and Canada, with European ports expanding. Ocean milestones work globally; terminal-level operational data does not yet.
**No air, parcel, or road tracking.** If your integration covers those modes, this migration handles only the ocean portion.
**No freight rates or sailing schedules.** We do not offer a rate calculator, rate index, or schedule search.
**Some fields are source-dependent.** Seal number, container weight, and departure or arrival events vary by carrier. The [field availability reference](/docs/coverage/fields) says which fields are always present and which depend on the carrier, terminal, or journey.
## Migration checklist
Everyone does the base path. Then pick a branch.
### Base path
Self-serve at [app.terminal49.com/developers/api-keys](https://app.terminal49.com/developers/api-keys). Copy it immediately, it is shown once.
Move from your Vizion API key header to `Authorization: Token`. Note the `Token` prefix.
Compare your Vizion carrier values against the [carrier list](/docs/coverage/ocean-carriers). Flag anything missing before you cut over.
One `POST /tracking_requests` per BOL, booking, or container, replacing the per-reference creation.
Tracking requests start pending. Handle `succeeded`, `failed`, and `awaiting_manifest` rather than expecting data on creation.
JSON:API structure, split equipment fields, UTC timestamps with a separate timezone.
Replace envelope checks with HTTP status codes.
Submit tracking requests for everything currently in transit. Send us the list if it is large and we will load it.
Holds, fees, and LFD are the reason to do this properly rather than porting like for like.
### Then pick one
Accept our POST payloads at a public URL.
Subscribe only to events you act on.
Reject any payload whose signature does not match.
Only needed if your firewall restricts inbound traffic.
Confirm end-to-end before going live.
Remove your dedupe layer along with it.
See [webhook best practices](/docs/api-docs/webhooks/best-practices) for retries and idempotency.
Keep the tracking request ID and shipment ID from the creation response.
Point it at `GET /v2/shipments` or `GET /v2/containers`.
No change to how often you poll.
Skipped: endpoint setup, signature verification, IP whitelisting, delivery testing.
Terminal data changes on a cadence polling tends to miss. If you only adopt webhooks for one thing, make it `container.updated` and `container.pickup_lfd.changed`.
## Migrate with an AI coding agent
If you use Cursor, Claude Code, Windsurf, Copilot, or another AI coding assistant, hand it the prompt below. It is written to run a **side-by-side migration**: the agent stands up a Terminal49 client next to your existing Vizion code, shadows every Vizion call with a Terminal49 call, diffs the responses, and only cuts over once parity is proven.
Point your agent at this page as context (paste the URL or add it as a doc source). The prompt references the mappings above, so the more of this page the agent can see, the better it does.
1. Open your repo in your AI coding tool.
2. Add this page as a documentation source, or paste its URL into the chat.
3. Copy the prompt below into a new chat and send it.
4. Answer the agent's discovery questions (Vizion client location, env var names, carrier mix).
5. Review each PR the agent opens. It should ship in small, reviewable steps: client, shadow, parity harness, cutover, cleanup.
* A `Terminal49Client` alongside your existing `VizionClient`, sharing the same interface where possible.
* A shadow-mode wrapper that calls both providers and logs response diffs without changing behavior.
* A parity report per shipment: matched fields, diverged fields, and Terminal49-only fields (holds, fees, LFD).
* A feature-flagged cutover: route reads to Terminal49, keep Vizion as fallback until you flip the flag off.
* A webhook receiver with HMAC verification, or a polling scheduler, depending on which path you pick.
* A cleanup PR that removes Vizion code, env vars, dependencies, and dedupe logic.
### The prompt
Copy this into your agent. Replace the bracketed placeholders in the **Repo context** block before sending.
```markdown Terminal49 migration agent prompt expandable icon=robot wrap theme={null}
You are migrating this codebase from the Vizion tracking API to the Terminal49 API,
side by side. Terminal49's authoritative migration guide is at
https://terminal49.com/docs/api-docs/getting-started/migrate-from-vizion. Use it as
the source of truth for field mappings, event names, error codes, and behavior differences.
# Repo context (fill this in before running)
- Vizion client lives at: [path/to/vizion/client.ts]
- Vizion is called from: [list the call sites or "find them"]
- Language and framework: [e.g. TypeScript + Node, Python + FastAPI, Ruby on Rails]
- Storage for tracking state: [e.g. Postgres table `shipments`]
- Current polling schedule: [e.g. cron every 2h via BullMQ]
- Carrier mix (SCACs we track most): [e.g. MAEU, MSCU, CMDU, HLCU, ONEY]
- Deployment target: [e.g. AWS ECS, Vercel, Fly.io]
- Secret store: [e.g. AWS Secrets Manager, `.env`, Doppler]
# Rules
1. Do not delete Vizion code until the cleanup step. Migration is side by side.
2. Ship in small PRs. Each PR must build, pass tests, and be independently revertable.
3. Never invent Terminal49 fields, endpoints, or event names. If the guide does not
confirm a mapping, ask me. Do not guess.
4. Terminal49 uses `Authorization: Token ` (not `Bearer`) and content type
`application/vnd.api+json`. Get this right on the first request.
5. Terminal49 is asynchronous. `POST /tracking_requests` returns pending. Data arrives
via `tracking_request.succeeded`, `tracking_request.failed`, or `awaiting_manifest`
webhooks, or by polling `GET /v2/shipments`. Do not expect shipment data on creation.
6. Timestamps are UTC with a separate IANA `time_zone` field. Do not assume local time.
7. `holds_at_pod_terminal: []` and `fees_at_pod_terminal: []` are the normal state,
not missing data. A fee `amount` of 0 is valid.
8. On `container.updated`, prefer the `changeset` over diffing state yourself.
# Plan (execute in order, one PR per step)
## PR 1 — Discovery and interface
- Grep the repo for every Vizion call site. List them in the PR description.
- Extract the Vizion client's public surface into an interface
(`TrackingProvider` with methods like `track(number, type, scac)`,
`getShipment(id)`, `refresh(id)`).
- Make the existing Vizion client implement it. No behavior change.
## PR 2 — Terminal49 client
- Add a `Terminal49Client` implementing the same `TrackingProvider` interface.
- Auth via `T49_API_KEY` env var, header `Authorization: Token ${key}`.
- Base URL `https://api.terminal49.com/v2`, content type `application/vnd.api+json`.
- Implement:
- `createTrackingRequest({ request_number, request_type, scac })` returning the
tracking request ID.
- `getShipment(id, { include: 'containers,port_of_lading,port_of_discharge,...' })`.
- `getContainer(id)`.
- `refreshContainer(id)` mapping to `POST /v2/containers/{id}/refresh`.
- Normalize responses to the same shape Vizion callers expect today, using the field
mapping from the guide. Split `iso_code` into `equipment_type`, `equipment_length`,
`equipment_height`. Convert timestamps to UTC + `time_zone`.
- Map errors to typed classes: `AuthenticationError` (401), `AuthorizationError` (403),
`ValidationError` (400/422), `RateLimitError` (429), `UpstreamError` (5xx),
`FeatureNotEnabledError` (403 + feature flag response).
- Add unit tests using recorded fixtures. Do not hit the live API in tests.
## PR 3 — Shadow mode
- Add a `ShadowProvider` that wraps both clients. On every read:
- Call Vizion as the primary. Return its response.
- Fire-and-forget a Terminal49 call for the same identifier.
- Log a structured diff: matched fields, diverged fields, T49-only fields.
- Gate with env var `TRACKING_SHADOW_MODE=true`. Off by default.
- Add a parity report script that aggregates shadow logs by SCAC and field.
- Do NOT change what callers see. This step is observation only.
## PR 4 — Backfill script
- Write a one-shot script that reads all active shipments from our database and calls
`POST /tracking_requests` for each (one per BOL, booking, or container).
- Store the returned `tracking_request.id` and eventual `shipment.id` on our records.
- Rate-limit to respect Terminal49's limits (handle 429 with exponential backoff).
- Idempotent: safe to re-run. Skip rows already backfilled.
## PR 5 — Webhook receiver (only if we picked the webhook path)
- Add `POST /webhooks/terminal49` endpoint.
- Verify HMAC signature using the shared secret from `T49_WEBHOOK_SECRET`. Reject on
mismatch with 401.
- Handle these events at minimum:
- `tracking_request.succeeded`, `tracking_request.failed`, `tracking_request.awaiting_manifest`
- `container.transport.vessel_discharged`, `container.transport.available`,
`container.transport.full_out`
- `container.updated` (use the `changeset`, do not diff)
- `container.pickup_lfd.changed`
- Persist events idempotently keyed by event ID.
- Register the webhook via `POST /v2/webhooks` from a bootstrap script, subscribing
only to events we handle.
- If our firewall restricts inbound traffic, whitelist Terminal49 IPs from
`GET /v2/webhooks/ips`.
## PR 6 — Cutover behind a flag
- Add feature flag `TRACKING_PROVIDER` with values `vizion` (default) and `terminal49`.
- Route all reads through the flag. Vizion stays available as a fallback for one
release cycle.
- Flip staging to `terminal49`, verify parity report is clean, then flip production.
## PR 7 — Cleanup
- Delete `VizionClient`, its tests, its env vars, its dedupe cache, and any
ISO-code parsing helpers Terminal49 makes redundant.
- Remove the shadow provider and the feature flag.
- Update README and any runbooks. Note the new webhook endpoint if applicable.
# Definition of done
- All Vizion call sites now go through Terminal49.
- Webhook (or polling) is live in production.
- Parity report shows no unexplained divergences for our top 10 SCACs.
- Holds, fees, and LFD are exposed to whichever downstream system needs them
(dashboard, alerts, customer emails). Do not migrate without wiring these up. They
are the reason to do this properly.
- Vizion dependency, env vars, and dead code are gone from the repo.
# Ask me before you
- Choose between the webhook path and the polling path. Default to webhooks unless our
infra makes an inbound HTTPS endpoint hard.
- Change the shape of any function Vizion callers use today. Prefer a normalization
layer inside the Terminal49 client.
- Add a new dependency. Prefer stdlib and what is already in the repo.
- Touch anything outside the tracking integration.
Start with PR 1. Post the list of Vizion call sites and the proposed
`TrackingProvider` interface, and wait for my review before writing PR 2.
```
The prompt is deliberately opinionated on side-by-side migration and small PRs. If your team prefers a big-bang cutover or a different branching model, edit the **Plan** section before sending it to your agent.
## Getting help
Send us your list of active container and bill of lading numbers and we will load them rather than making you script the backfill.
If something in this mapping is wrong or incomplete, tell us. We would rather fix the page than have you work around it.
Every endpoint, with request and response schemas
Typed client with retries and pagination built in
Carriers, terminals, rail, and field availability
Simulate success, failure, and edge cases