Home Learn Blog About Book a call
· ~9 min read

How to Approach Maersk API Integration: A Developer's Guide

Learn how to seamlessly integrate Maersk APIs with this step-by-step developer's guide, ensuring smooth app registration and testing.

How to Approach Maersk API Integration: A Developer's Guide

You integrate Maersk APIs by registering on the Maersk Developer Portal, creating an app to get OAuth2 consumer keys, and testing against staging before switching to production endpoints. The core APIs worth prioritizing are Tracking, Shipments, and Scheduling. Follow this sequence:

Key Takeaways

Successful Maersk API integration depends on correct OAuth2 token handling per environment, webhook-first architecture, and standardized error handling built from day one.

Point Details
Register before building Create a Developer Portal app to get consumer keys before writing any integration code.
Separate test and production tokens Testing and production use different token endpoints; never mix credentials across environments.
Pin your Api-Version header Explicitly set Api-Version on every request to avoid silent response changes when Maersk updates defaults.
Fix permission errors at the account level 403 errors on Shipments calls are usually tariffCode or locationId issues, not code bugs.
Automate the email and document layer Tools like Logentic handle carrier emails and documents that never arrive as clean API payloads, feeding data straight into your TMS.

Table of Contents

Maersk API Integration Prerequisites: Accounts and OAuth2 Authentication

Every Maersk shipping API call starts with an app registered on the Maersk Developer Portal. Once you register your account, you create an app there to receive a set of consumer keys tied to your organization, not just your personal login.

Authentication runs on OAuth 2.0 using the client_credentials grant. You exchange your consumer key and secret for an access token, and testing and production each use a separate token endpoint, so a token minted in staging will never authenticate against live infrastructure.

Every request needs three headers at minimum:

Some write operations, particularly around Shipments, also depend on account-level settings like locationId or tariffCode that Maersk configures on the back end. If a call fails for reasons that have nothing to do with your code, that’s usually the cause.

Pro Tip: If your account lacks the tariffCode or contract permissions a Shipments call expects, don’t burn hours debugging your request body. Contact your Maersk sales representative first. This is one of the most common points of friction in freight API solutions, and it has nothing to do with your integration logic.

Which Maersk APIs Handle Which Logistics Tasks

Choosing the right endpoint set upfront saves you from rebuilding your data model halfway through a project. Here’s how the primary Maersk API Solutions map to common workflows:

Most shipping management API projects start with Tracking, since it requires no write permissions, then expand into Shipments once account configuration is confirmed.

Step-by-Step Checklist From First Call to Production

Maersk’s own documentation outlines a straightforward five-step onboarding path: register, create an app, get consumer keys, try the APIs, then build. In practice, a production-ready integration needs a few more checkpoints along the way.

  1. Register on the Developer Portal and create your app to receive consumer keys.
  2. Retrieve a token from the testing token endpoint using client_credentials, and confirm the response includes a valid expiry.
  3. Make a basic GET call (Tracking is the easiest starting point) to confirm your headers, including Api-Version, are accepted.
  4. Build retry and backoff logic for transient failures, and standardize how your system parses Maersk’s JSON error responses.
  5. Subscribe to webhooks for the events you need, and verify delivery against a test endpoint you control.
  6. Run end-to-end tests covering the full flow: authentication, request, response parsing, and webhook receipt.
  7. Swap to production consumer keys and base URLs only after every step above passes cleanly.

Pro Tip: Treat step 5 as non-negotiable even if your first release only needs polling. Webhook infrastructure is far easier to build early, when data volume is low, than to retrofit once your system depends on scheduled polling jobs.

Skipping the staging phase is the single most common reason teams hit unexplained failures right after launch.

Technical Reference: Endpoints, Headers, and Key Fields

Maersk’s developer documentation separates production and testing environments at the token endpoint level, so double-check which base URL and token endpoint pair you’re pointing at before debugging anything else.

Environments and token endpoints

Environment Purpose Token behavior
Testing Sandbox development, staging validation Separate token endpoint, isolated from live data
Production Live shipment and tracking data Requires production consumer keys, distinct base URL

Required headers on every request:

Maersk manages versioning through the Api-Version header rather than versioned URL paths, which means your client code doesn’t need to change its base path when a new version rolls out. Omit the header and requests typically default to the latest supported version, which can quietly change your response shape if you’re not pinning it explicitly.

Key Shipments fields to get right: locationId (must match an account-approved location), serviceCode, tariffCode, payType, and the housebill identifier used to generate or fetch shipment documents.

Maersk’s error handling uses standardized JSON responses across common HTTP statuses:

Testing and Sandbox Best Practices for Maersk Shipping API

Isolating test data from real shipment records is the first rule of safe Maersk API integration testing. Staging environments exist specifically so you can run destructive tests, malformed payloads, and load simulations without touching anything your customers depend on.

  1. Run every new feature against the testing token endpoint first, and never reuse production consumer keys in a staging build, even temporarily.
  2. Build contract tests against Maersk’s published OpenAPI specifications so a schema change surfaces in your CI pipeline before it reaches a customer-facing workflow.
  3. Simulate webhook payloads with stubbed events to validate your status-change handling logic without waiting for real container movements.
  4. Run basic load and rate-limit tests in staging to understand how your retry logic behaves under throttling, since production limits are not the place to discover this.

Common Maersk API Errors and How to Fix Them

Most integration failures fall into a handful of predictable categories, and Maersk’s documented error table makes diagnosis fast once you know where to look.

Pro Tip: Keep a running log of which error codes correlate with which fixes on your team’s side. Most “mystery” Maersk API errors turn out to be the same three or four root causes repeating across different endpoints.

If retries and payload checks don’t resolve the issue, escalate to Maersk support with your app’s consumer key, timestamp, and the exact request payload attached.

Hands holding phone with error logs blurred

How Logentic Connects Maersk Events to TMS Workflows

A typical automated pattern looks like this: Maersk webhooks fire on a status change, Logentic’s AI agent Alex picks up the associated email or document, extracts the relevant data, and pushes normalized fields directly into your TMS.

The gap most integrations miss isn’t the API call itself. It’s everything downstream of it: the email that references a shipment update, the PDF attachment nobody parses automatically, the manual re-entry that turns an eight-second job into a fifteen-minute one.

This is the layer where raw carrier data usually stalls before it ever reaches a TMS record.

Why Webhook Architecture Beats Polling for Most Teams

Why Webhook Architecture Beats Polling for Most Teams — overview diagram

Webhook-driven architecture wins over polling for nearly every Maersk integration, because status changes reach you within seconds instead of on whatever interval your polling job runs. Reserve polling for edge cases where webhook delivery genuinely isn’t available.

Whatever architecture you choose, invest early in observability. Request traces, webhook delivery logs, and alerting on failed deliveries catch problems long before a customer notices a stale tracking status. This is exactly the layer where a system like Logentic plugs in, turning validated events into TMS-ready data without a human touching the keyboard.

— Bogdan

Turn Maersk API Data Into TMS Entries Automatically

Building and maintaining a Maersk API integration handles the data feed. It doesn’t handle what happens when a booking confirmation, a rate update, or a document arrives as an email attachment instead of a clean webhook payload, which is still how a large share of carrier communication actually flows. Logentic’s AI agent Alex reads those emails and documents, extracts the same fields you’d pull from an API call, and writes them into your TMS in about eight seconds, without a developer maintaining a parser for every carrier’s email format.

Logentic

That means faster onboarding than a custom-built integration layer, fewer manual touchpoints for your operations team, and TMS records that stay synchronized whether the data arrived through Maersk’s API or through someone’s inbox. If your team is weighing how much engineering time a full Maersk shipping API build will actually cost versus automating the email and document side first, start with Email Automation and see how much of that manual work disappears in the first week.

Authoritative Maersk API Documentation and Resources

Bookmark these before you start building:

Sources

Written with BabyLoveGrowth technology

Want to see how Logentic automates this work?

Book a call →

← All articles