Migrating from FourKites

This guide covers the ocean tracking portion only. FourKites road, rail, and LTL tracking are out of scope here; keep them in FourKites unless you are replacing them with another provider.

If you have FourKites ocean tracking in production, this page maps it onto Terminal49 field by field, so you can cut over without reverse-engineering our schema. Terminal49 is a direct-integration ocean and North American terminal API, self-serve, with holds and fees out of the box. FourKites is multi-modal, enterprise-priced, and centered on their broader visibility platform. This guide addresses only the ocean container portion. There is no compatibility shim. You will change your request code and your response parsing. For most integrations that is an afternoon.

Start in sixty seconds

You do not need to talk to anyone to try this.

Create an account

Create an account — the free Developer Key tracks up to 10 active containers.

Generate an API key

Generate a key at app.terminal49.com/developers/api-keys.

Run your first curl

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, which simulate success, failure, and edge-case outcomes.

The architectural shift

FourKites tracks shipments across modes in a single enterprise platform. Ocean is one product among many, organized around loads and shipments with nested segments. Terminal49 splits ocean tracking in two. You register a tracking request once. We keep it updated and push changes to your webhook.

Before — FourKites

Query the FourKites platform for shipment or load state, often across ocean, road, and rail segments. Extract ocean data from the multi-modal shipment model. Polling, enterprise contract, and broad visibility scope.

After — Terminal49

POST /tracking_requests once → Terminal49 polls carriers, terminals, and rail → we POST to your endpoint as things change → write to your database. No cache layer, no dedupe logic. Ocean only, direct terminal data.

You can keep polling if you prefer — point your existing scheduler at 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

	FourKites	Terminal49
Tracking model	Poll via enterprise platform	Register once, then push or poll
Authentication	OAuth2 bearer token or API key header	`Authorization: Token` header
Base URL	`https://fourkites.com`	`https://api.terminal49.com/v2`
Content type	`application/json`	`application/vnd.api+json`
Response format	Custom JSON	JSON:API
Webhooks	Available	30+ events, HMAC-signed
Carrier identification	SCAC or internal mapping	`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	Available	North American Class I and short-line
Multi-modal scope	Ocean, road, rail, freight	Ocean and North American terminals only
Getting an API key	Enterprise contract	Self-serve

Authentication

Move from OAuth2 bearer tokens or API key headers to a single Authorization: Token header.

curl "https://fourkites.com/[your provider's shipment resource]" \
  -H "Authorization: Bearer YOUR_FOURKITES_TOKEN"

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.

Request parameter mapping

FourKites parameter	Terminal49 equivalent	Notes
`[provider's shipment identifier]`	`request_number`
`[provider's container identifier]`	`request_type: "container"` + `request_number`
`[provider's bill of lading field]`	`request_type: "bill_of_lading"`	Master or house BOL
`[provider's booking number field]`	`request_type: "booking_number"`
SCAC / carrier code	`scac`	Same SCAC values for most carriers
`[provider's auto-detect option]`	Omit `scac`, or call Infer Tracking Number	Returns the predicted SCAC and number type
`[provider's refresh option]`	`POST /v2/containers/{id}/refresh`	Forces an immediate pull from all sources
`[provider's route field]`	Always included	See Routing

FourKites organizes around shipments and loads that may contain multiple segments across modes. Terminal49 takes one ocean identifier per tracking request. 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 to sideload related resources in one call instead of chasing IDs.

Shipment level

FourKites	Terminal49
`[provider's bill of lading field]`	`shipment.attributes.bill_of_lading_number`
`[provider's carrier scac 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]`	`shipment.attributes.port_of_lading_*` (place of receipt)
`[provider's port of loading]`	`shipment.relationships.port_of_lading`
`[provider's port of discharge]`	`shipment.relationships.port_of_discharge`
`[provider's destination]`	`shipment.relationships.destination` (inland)
`[provider's ETA field]`	`shipment.attributes.pod_eta_at`

Container level

FourKites	Terminal49
`[provider's container number field]`	`container.attributes.number`
`[provider's equipment code field]`	`container.attributes.equipment_type` + `equipment_length` + `equipment_height`
`[provider's container status field]`	`container.attributes.current_status`
`[provider's event list]`	Container timestamps, transport events, and webhook events

FourKites may return an 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

FourKites	Terminal49
`[provider's port name field]`	`port.attributes.name`
`[provider's port code field]`	`port.attributes.code`
`[provider's port coordinates]`	`port.attributes.latitude` / `.longitude`
`[provider's port timezone]`	`port.attributes.time_zone`
`[provider's port country]`	`port.attributes.country_code`
`[provider's terminal name field]`	`terminal.attributes.name`
`[provider's terminal smdg code]`	`terminal.attributes.smdg_code`
`[provider's terminal bic code]`	`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
`[provider's vessel call sign / flag]`	Not returned

Milestone and event mapping

FourKites returns milestones within your shipment or load resource. Terminal49 exposes the same milestones as normalized transport events and pushes each one to your webhook. Where mappings exist:

FourKites milestone	Terminal49 event
`[provider's vessel loaded event]`	`container.transport.vessel_loaded`
`[provider's vessel departed event]`	`container.transport.vessel_departed`
`[provider's vessel arrived event]`	`container.transport.vessel_arrived`
`[provider's vessel discharged event]`	`container.transport.vessel_discharged`
`[provider's full out / gated out event]`	`container.transport.full_out`
`[provider's full in / gated in event]`	`container.transport.full_in`
—	`container.transport.empty_out`
—	`container.transport.empty_in`

Terminal49 also emits milestones with no FourKites ocean equivalent:

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.

Registering a webhook

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 for signature verification, and 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 FourKites equivalent.

Holds

holds_at_pod_terminal is an array of active holds blocking pickup:

{
  "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:

{
  "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:

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.

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 for the features that do require account enablement — rail LFD and the embeddable widget are the main ones.

Gotchas that will bite you

Enterprise contract vs self-serve pricing

FourKites is an enterprise platform. Terminal49 is self-serve with a Developer Key that tracks up to 10 containers free. If you need volume pricing, it exists, but you do not need a contract to start.

FourKites event vocabulary differs from normalized transport events

FourKites event names and codes are specific to their platform. You will need a mapping table to translate them onto Terminal49’s normalized events such as container.transport.vessel_discharged. Where exact mappings do not exist, handle the Terminal49 events directly.

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 — we retry automatically. See Tracking Request Lifecycle.

Timestamps are UTC with a separate timezone field

FourKites may return local time or timestamps with offset. Terminal49 stores event timestamps in UTC and returns the matching IANA timezone alongside. Convert for display rather than assuming local time. See Event Timestamps.

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

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.

Error handling

FourKites returns errors within the response body of their platform API. Terminal49 uses standard HTTP status codes. Replace body 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
5xx	Terminal49 or an upstream carrier or terminal is unavailable

Rough equivalence for the FourKites errors you are handling today:

FourKites error	Terminal49
`[provider's auth error]`	HTTP 401
`[provider's permission error]`	HTTP 403
`[provider's rate limit error]`	HTTP 429
`[provider's validation error]`	HTTP 400 or 422
`[provider's not found error]`	HTTP 404
`[provider's upstream unavailable error]`	Not surfaced — we retry internally

The TypeScript SDK maps these to typed errors (AuthenticationError, ValidationError, RateLimitError, UpstreamError, FeatureNotEnabledError, AuthorizationError, NotFoundError) and retries rate-limit and server errors automatically with exponential backoff.

Where we are narrower than FourKites

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. 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 road, rail, or LTL tracking. FourKites is multi-modal. Terminal49 is ocean and North American terminals only. 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

Self-serve at app.terminal49.com/developers/api-keys. Copy it immediately — it is shown once.

Switch authentication

Move from OAuth2 bearer or API key to Authorization: Token. Note the Token prefix.

Check your carrier mix

Compare your FourKites carrier values against the carrier list. Flag anything missing before you cut over.

Extract ocean segments

Identify the ocean leg of each FourKites shipment. Discard road, rail, and LTL for this migration.

Create tracking requests

One POST /tracking_requests per BOL, booking, or container, replacing the per-request lookup.

Handle the async lifecycle

Tracking requests start pending. Handle succeeded, failed, and awaiting_manifest rather than expecting data on creation.

Update response parsing

JSON:API structure, split equipment fields, UTC timestamps with a separate timezone.

Update error handling

Replace body checks with HTTP status codes.

Backfill active shipments

Submit tracking requests for everything currently in transit. Send us the list if it is large and we will load it.

Add the terminal fields

Holds, fees, and LFD are the reason to do this properly rather than porting like for like.

Then pick one

Webhook path
Polling path

Expose an HTTPS endpoint that accepts our POST payloads.
Register a webhook and subscribe only to events you act on.
Verify HMAC signatures.
Whitelist our IPs if your firewall restricts inbound traffic.
Trigger a test delivery before going live.
Retire your polling job and your dedupe layer.

See webhook best practices for retries and idempotency.

Store the tracking request ID and shipment ID from the creation response.
Repoint your existing scheduler at GET /v2/shipments or GET /v2/containers.
Keep your existing cadence.

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

Terminal49 migration agent prompt

You are migrating this codebase from the FourKites ocean tracking API to Terminal49.

Context you already have:
- The existing integration uses FourKites for ocean container tracking.
- Environment variables FOURKITES_BASE_URL and FOURKITES_API_KEY are in use.
- The app polls for shipment state and stores events in the database.

Your task:
1. Replace all FourKites ocean API calls with Terminal49 equivalents.
2. Remove polling for ocean shipments; register webhooks for
   container.transport.vessel_discharged, container.transport.available,
   container.pickup_lfd.changed, tracking_request.succeeded, and tracking_request.failed.
3. Parse JSON:API responses and map fields:
   - shipment.attributes.bill_of_lading_number
   - shipment.attributes.shipping_line_scac
   - shipment.attributes.shipping_line_name
   - container.attributes.number
   - container.attributes.equipment_type / equipment_length / equipment_height
   - container.attributes.holds_at_pod_terminal
   - container.attributes.fees_at_pod_terminal
   - container.attributes.pickup_lfd
   - container.attributes.available_for_pickup
4. Handle async tracking request lifecycle: succeeded, failed, awaiting_manifest.
5. Update error handling to use HTTP status codes and typed SDK errors.
6. Keep road, rail, and LTL tracking in FourKites or leave stubs pointing elsewhere.
7. Add holds_at_pod_terminal and fees_at_pod_terminal to the data model.
8. Write tests for webhook signature verification and container.updated changeset parsing.
9. Do not change anything outside the ocean tracking module.
10. Use the Terminal49 TypeScript SDK where possible.

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.

API reference

Every endpoint, with request and response schemas

TypeScript SDK

Typed client with retries and pagination built in

Coverage

Carriers, terminals, rail, and field availability

Test numbers

Simulate success, failure, and edge cases

​Start in sixty seconds

​The architectural shift

Before — FourKites

After — Terminal49

​Quick comparison

​Authentication

​Request parameter mapping

​Response field mapping

​Shipment level

​Container level

​Locations, facilities, and vessels

​Milestone and event mapping

​Registering a webhook

​What you gain

​Holds

​Fees

​Last free day

​Release readiness

​Gotchas that will bite you

​Error handling

​Where we are narrower than FourKites

​Migration checklist

​Base path

​Then pick one

​Migrate with an AI coding agent

​Getting help

API reference

TypeScript SDK

Coverage

Test numbers

Start in sixty seconds

The architectural shift

Quick comparison

Authentication

Request parameter mapping

Response field mapping

Shipment level

Container level

Locations, facilities, and vessels

Milestone and event mapping

Registering a webhook

What you gain

Holds

Fees

Last free day

Release readiness

Gotchas that will bite you

Error handling

Where we are narrower than FourKites

Migration checklist

Base path

Then pick one

Migrate with an AI coding agent

Getting help