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
GoComet gives you a shipment-centric model where you call their API with a reference number and get back current state with attached events. You own the schedule, the cache, and the deduplication. Terminal49 splits this in two. You register a tracking request once. We keep it updated and push changes to your webhook.Before: GoComet
GET to your provider’s shipment resource with a reference number, diff against your cache, dedupe events, then write to your database. Freshness is capped by your polling interval.After: Terminal49
POST /tracking_requests once. Terminal49 polls carriers, terminals, and rail, then POSTs to your endpoint as things change. No cache layer, no dedupe logic.GET /v2/shipments or GET /v2/containers. But webhooks are the reason the API is shaped this way, and terminal data (holds, fees, last free day) changes on a cadence that polling tends to miss.
Quick comparison
Authentication
Move from your provider’s API key header format to ours.Token prefix. It is not Bearer.Request parameter mapping
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
GoComet returns a flat events array with event names or codes attached to each shipment. 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 GoComet 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
Ocean-only scope
Ocean-only scope
Tracking requests are asynchronous
Tracking requests are asynchronous
POST /tracking_requests returns immediately with a pending status. The shipment appears once the carrier responds. Subscribe to tracking_request.succeeded and tracking_request.failed rather than expecting shipment data in the creation response. A request may also land in awaiting_manifest if the carrier has not manifested the shipment yet, and we retry automatically. See Tracking Request Lifecycle.JSON:API responses are verbose
JSON:API responses are verbose
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.Auth header format
Auth header format
Authorization: Token YOUR_KEY. It is not Bearer, not Basic, and not X-API-Key. A missing or wrong prefix returns 401 even with a valid key.Error handling
GoComet likely returns errors embedded in the response body. Terminal49 uses standard HTTP status codes. 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 GoComet
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. GoComet lists substantially more through aggregators. 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. GoComet covers multi-modal freight. 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. Keep GoComet for rate management and procurement. 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-request lookup.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 GoComet code, shadows every GoComet 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 (GoComet 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 existingGoCometClient, 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 GoComet 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 GoComet code, env vars, dependencies, and dedupe logic.