Start in sixty seconds
You do not need to talk to anyone to try this.Create an account
Generate an API key
Make your first request
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.Before: Vizion
After: Terminal49
Quick comparison
Authentication
Move from Vizion’s key header to Terminal49’sToken prefix. Note the content type change.
Token prefix. It is not Bearer.x-api-key, the change is the same: move the value into Authorization: Token YOUR_T49_KEY.
Request parameter mapping
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 theinclude parameter to sideload related resources in one call instead of chasing IDs.
Shipment level
Container level
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
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.- Vessel berthed:
container.transport.vessel_berthed - Available for pickup:
container.transport.availableand.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
Registering a webhook
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:
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.
Fees
fees_at_pod_terminal carries type, amount, and currency:
demurrage, extended_dwell_time, exam, total, and other.
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
Release readiness
Two fields answer “can I pick this up?”available_for_pickup and the holds array:
Gotchas that will bite you
Reference IDs vs tracking_request IDs
Reference IDs vs tracking_request IDs
tracking_request.id where you stored reference.id.JSON:API response shape
JSON:API response shape
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.Timestamps are UTC with a separate timezone field
Timestamps are UTC with a separate timezone field
Empty arrays are the normal state
Empty arrays are the normal state
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.container.updated carries a changeset
container.updated carries a changeset
container.updated with a changeset showing old value first, new value second. Use it instead of diffing state yourself.Async lifecycle
Async lifecycle
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.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.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 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 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
Get a key
Switch authentication
Authorization: Token. Note the Token prefix.Check your carrier mix
Create tracking requests
POST /tracking_requests per BOL, booking, or container, replacing the per-reference creation.Handle the async lifecycle
succeeded, failed, and awaiting_manifest rather than expecting data on creation.Update response parsing
Update error handling
Backfill active shipments
Add the terminal fields
Then pick one
- Webhook path
- Polling path
Expose an HTTPS endpoint
Register a webhook
Verify HMAC signatures
Whitelist our IPs
Trigger a test delivery
Retire your polling job
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.How to use this prompt
How to use this prompt
- Open your repo in your AI coding tool.
- Add this page as a documentation source, or paste its URL into the chat.
- Copy the prompt below into a new chat and send it.
- Answer the agent’s discovery questions (Vizion client location, env var names, carrier mix).
- Review each PR the agent opens. It should ship in small, reviewable steps: client, shadow, parity harness, cutover, cleanup.
What the agent will produce
What the agent will produce
- A
Terminal49Clientalongside your existingVizionClient, 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.