API Integration for Freight Management: Implementation Guide

Manual freight management is expensive. Your team spends hours weekly on data entry: copying tracking numbers, updating ERP systems, reconciling invoices, and chasing status updates. API integration eliminates this friction.

The ROI Case

For a company shipping 50+ containers monthly, manual freight management typically costs:

• Tracking updates: 3-5 hours/week checking portals and emails
• Data entry: 2-4 hours/week entering shipment data into internal systems
• Invoice reconciliation: 2-3 hours/week matching invoices to shipments
• Status inquiries: 1-2 hours/week responding to internal "where's my shipment" requests

At $50/hour fully-loaded cost, that's $20,000-35,000 annually in administrative overhead that API integration can largely eliminate.

Beyond Cost Savings

API integration also enables:

• Real-time visibility: Automatic updates in your systems without manual checks
• Proactive alerting: Push notifications for exceptions before they become problems
• Automated workflows: Trigger actions based on shipment events
• Accurate reporting: Complete freight data in your BI tools without manual compilation

Modern freight forwarders offer APIs covering the full shipment lifecycle. Here's what to expect:

Rate/Quote API

Request quotes programmatically:

• Input: Origin, destination, cargo details, service level
• Output: Available rates with transit times, carriers, and validity periods
• Use case: Automated rate comparison, dynamic pricing in e-commerce checkout

Booking API

Create and confirm bookings without manual intervention:

• Input: Shipment details, selected rate, documentation
• Output: Booking confirmation, reference numbers
• Use case: Automated PO-to-booking workflows, scheduled shipments

Tracking API

Retrieve shipment status and milestone events:

• Input: Shipment reference or container number
• Output: Current status, location, milestone history, ETA
• Use case: Dashboard displays, ERP updates, customer notifications

Document API

Upload and download shipping documents:

• Input/Output: Commercial invoices, packing lists, bills of lading, certificates
• Use case: Automated document collection, customs filing integration

Webhook Subscriptions

Receive push notifications for events:

• Events: Status changes, ETD/ETA updates, exceptions, document availability
• Use case: Real-time alerts, automated workflow triggers

Every Cubic account includes API access. This guide covers freight APIs in general and uses the Cubic API as a concrete example where it applies. The full documentation lives at developers.gocubic.io, and a customer-facing overview is on the Cubic API page.

What you get

• Shipments as JSON: Status, service type, route milestones with estimated and actual dates, vessel names, voyage and flight numbers per leg
• Bookings and bills: Master and house bills, booking numbers, cargo cutoffs, free days at destination
• Cargo detail: Container numbers, seals and types; package counts, dimensions and weights in the units they were recorded
• Last mile: Parcel carrier and tracking numbers on DDP and courier shipments, plus Amazon FBA identifiers
• Your identifiers: Filter by PO number, search by container, master bill or FBA ID

How it is built

• REST over HTTPS with a Bearer API key you create yourself in the Cubic app under Settings. No approval process.
• OpenAPI 3.1 document at developers.gocubic.io/openapi.json for generating typed clients
• Cursor pagination and an updatedSince filter, so a poll only returns what changed
• RFC 9457 errors with a stable code and a hint that tells you how to fix the request
• Written for AI agents: every docs page is available as markdown, and there is a dedicated For AI agents page. Paste the docs URL into your coding assistant and describe the integration you want. A working script typically takes minutes.

Where it is going

The API is expanding. Watch the changelog for new endpoints and capabilities as they ship.

Tracking integration is the recommended starting point. It carries no risk to your data, is high-value, and validates your integration infrastructure.

Polling vs. Webhooks

Polling: Your system periodically requests status for each shipment.

• Simpler to implement
• You control the schedule
• Higher API call volume (potential rate limiting)
• Updates not immediate (depends on poll frequency)

Webhooks: Forwarder pushes updates to your endpoint when events occur.

• Real-time updates
• Lower API call volume
• Requires endpoint infrastructure
• Must handle retry/failure scenarios

Recommendation: Start with polling to validate integration, then add webhooks for real-time capability. The Cubic API supports polling with an updatedSince filter, so each poll returns only shipments that changed; see the Poll for changes recipe.

Data Model Considerations

Map forwarder tracking events to your internal data model:

• Shipment reference: Your PO number vs. forwarder's booking number vs. container number
• Status mapping: Translate forwarder status codes to your system's status taxonomy
• Milestone standardization: Different carriers report different milestones; normalize them
• Timestamp handling: Ensure timezone consistency (UTC recommended)

Example Implementation Flow

1. Create shipment in forwarder's system (via booking API or manual)
2. Store forwarder reference with your internal shipment record
3. Periodically poll for updates or receive webhooks
4. Map received data to your internal model
5. Update internal systems (ERP, WMS, customer portal)
6. Trigger workflows based on status (e.g., notify warehouse of arrival)

After tracking integration is stable, extend to quote and booking APIs for end-to-end automation.

Quote API Implementation

Request structure:

• Origin (port/city/zip code format varies by API)
• Destination (same considerations)
• Cargo details (commodity, weight, dimensions, hazmat status)
• Service requirements (transit time, equipment type)
• Shipping date or date range

Response handling:

• Parse multiple rate options with different trade-offs
• Store rate validity periods (quotes expire)
• Handle "no rates available" scenarios gracefully
• Cache rates where appropriate (with expiration)

Booking API Implementation

Required data:

• Selected quote reference
• Complete shipper/consignee information
• Cargo details confirmed
• Required documentation (commercial invoice, packing list)
• Special instructions

Validation before booking:

• Quote still valid (not expired)
• All required fields present
• Document formats accepted
• No conflicting bookings

Confirmation handling:

• Store booking reference and carrier booking number
• Confirm VGM submission requirements
• Schedule document submission follow-ups
• Initiate tracking for booked shipment

Document APIs eliminate the email-and-attachment workflow that consumes significant administrative time.

Document Upload

Automate document submission to forwarders:

• Commercial Invoice: Export from your invoicing system, upload via API
• Packing List: Generate from WMS data, submit automatically
• Certificates: Store in document management system, attach to bookings
• Special documentation: Letters of credit, licenses, permits

Implementation considerations:

• File format requirements (PDF preferred, some accept Excel)
• File size limits (typically 10-25MB)
• Naming conventions required by forwarder
• Batch upload capability for multiple documents

Document Download

Retrieve shipping documents automatically:

• Bill of Lading: Download when issued, store in your systems
• Arrival Notice: Trigger customs preparation workflow
• Delivery Receipt: Close out shipment, trigger invoicing

Automation opportunities:

• Auto-file documents in your document management system
• Extract data from documents for reconciliation
• Forward documents to customers automatically
• Trigger workflows based on document availability

The Cubic API delivers updates through polling with the updatedSince filter today, which is enough for most syncs. The rest of this section is general guidance for when a forwarder offers webhooks.

Webhooks enable real-time responsiveness to freight events. Here's how to implement them reliably.

Endpoint Requirements

Your webhook endpoint must:

• Accept POST requests with JSON payload
• Respond with 2xx status within timeout period (typically 5-30 seconds)
• Be accessible from forwarder's servers (firewall considerations)
• Use HTTPS with valid SSL certificate

Payload Processing

Design for reliability:

• Acknowledge quickly: Return 200 immediately, process asynchronously
• Idempotency: Handle duplicate deliveries (forwarders retry on failure)
• Order independence: Events may arrive out of order; don't assume sequence
• Schema validation: Validate payload structure before processing

Event Types to Subscribe

Common webhook events:

• shipment.status.changed: Status updates (departed, arrived, delivered)
• shipment.eta.updated: ETA changes (critical for planning)
• shipment.exception: Delays, holds, problems
• document.available: New document ready for download
• booking.confirmed: Booking acceptance

Failure Handling

Plan for webhook delivery failures:

• Implement retry logic on your side (if you miss a webhook)
• Periodic polling as backup for critical shipments
• Alerting when webhook processing fails
• Manual reconciliation capability

Freight APIs handle sensitive business data. Implement security properly.

Authentication Methods

API Keys: Simple but less secure. Suitable for server-to-server communication.

• Store keys securely (never in code)
• Rotate keys periodically
• Use separate keys for test/production

OAuth 2.0: More secure, token-based authentication.

• Tokens expire, limiting breach impact
• Supports scoped permissions
• Industry standard, well-documented

Security Best Practices

• HTTPS only: Never transmit credentials or data over HTTP
• Credential storage: Use secrets management (Vault, AWS Secrets Manager, etc.)
• IP allowlisting: Restrict API access to known IP addresses if supported
• Logging: Log API calls (without credentials) for audit trail
• Webhook verification: Validate webhook signatures to confirm authenticity

Rate Limiting

Most APIs have rate limits. Handle them gracefully:

• Implement exponential backoff on 429 (Too Many Requests) responses
• Queue requests during high-volume periods
• Cache data where appropriate to reduce API calls
• Monitor usage against limits

Robust error handling is essential for production reliability.

Error Categories

Client errors (4xx):

• 400 Bad Request: Invalid input data
• 401 Unauthorized: Authentication failure
• 403 Forbidden: Permission denied
• 404 Not Found: Resource doesn't exist
• 429 Too Many Requests: Rate limit exceeded

Server errors (5xx):

• 500 Internal Server Error: Forwarder system issue
• 502/503: Service unavailable, retry later
• 504 Gateway Timeout: Request took too long

Retry Strategy

Implement intelligent retry logic:

• Retry on 5xx errors and network failures
• Don't retry on 4xx errors (except 429)
• Use exponential backoff: 1s, 2s, 4s, 8s, 16s
• Set maximum retry count (typically 3-5)
• Log all retries for debugging

Monitoring and Alerting

Track integration health:

• API response times: Detect performance degradation
• Error rates: Alert on elevated failure rates
• Data freshness: Alert if shipment data becomes stale
• Webhook delivery: Monitor webhook receipt rates

Set up alerts for:

• API error rate exceeds threshold
• Critical shipments without recent updates
• Authentication failures
• Webhook endpoint downtime

Thorough testing prevents production issues. Follow this testing strategy:

Development Testing

Test against your own account with a live key. Your real shipments are the test data:

• Verify the key with GET /v1/me
• List shipments and spot-check a few against what you see in the app
• Verify data mapping is correct
• Test error handling by sending a bad reference and a bad parameter

Integration Testing

Test the complete flow:

1. Run the sync once and confirm shipments appear in your system
2. Change nothing, run it again, and confirm nothing is duplicated
3. Wait for a real milestone update and confirm it flows through
4. Run it on a schedule and check the next day

Production Validation

Before going live:

• Compare a day of API output against what you see in the app
• Monitor error rates closely
• Have rollback plan ready

Ongoing Validation

Continuous quality assurance:

• Periodic reconciliation between API data and source of truth
• Automated tests for regression detection
• Watch the API changelog for new fields and endpoints

The old answer was "months". That is no longer true. With a modern REST API and an AI coding agent such as Claude Code or Codex, a working integration is a matter of minutes, not weeks.

First working integration: minutes

With the Cubic API, the path is: create an API key in the Cubic app, paste the documentation link into your coding agent, and describe what you want. The docs include a page written for AI agents and an OpenAPI document, so the agent knows every field and every edge case without guessing. A script that pulls your active shipments with ETAs, or exports everything to a spreadsheet, is typically running within five minutes.

Connecting to your systems: hours to a few days

Wiring the data into an ERP, WMS, or BI tool takes longer, but the time goes into your side of the mapping, not the freight API. Decide which fields you need, where they land, and how often to refresh. Most importers have a scheduled sync running in an afternoon.

Expanding scope: as the API grows

Start with tracking and visibility, because that is where the manual work is. As your forwarder ships more endpoints, extend the same integration rather than starting over.

The point: do not budget a quarter for this. Budget an afternoon, and see what you get.