Carrier API Integration Guide 18/02/26, 6:23 PM

Carrier API Integration Guide

Table of Contents
1. Quick Reference
2. Authentication
3. Environment Variables
4. API #1: Maersk Track & Trace
5. API #2: Maersk Deadlines
6. API #3: Maersk Demurrage & Detention
7. API #4: Hapag-Lloyd Track & Trace
8. API #5: Hapag-Lloyd Point-to-Point Routes
9. API #6: Hapag-Lloyd Vessel Schedules
10. DCSA Event Types Reference
11. Cut-off Code Mapping
12. Document Lifecycle Tracking
13. Data Availability Matrix
14. Fields NOT Available in Any API
15. Rate Limits & Best Practices
16. Real Data Examples
17. Integration Gotchas

[Link] Page 1 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

Carrier API Integration Guide

Version: 1.0 | Date: February 18, 2026 Carriers Covered: Maersk (3 APIs), Hapag-Lloyd (3 APIs) Based on: Live API
testing with real shipments

Table of Contents

1. Quick Reference
2. Authentication
3. Environment Variables
4. API #1: Maersk Track & Trace
5. API #2: Maersk Deadlines
6. API #3: Maersk Demurrage & Detention
7. API #4: Hapag-Lloyd Track & Trace
8. API #5: Hapag-Lloyd Point-to-Point Routes
9. API #6: Hapag-Lloyd Vessel Schedules
10. DCSA Event Types Reference
11. Cut-off Code Mapping
12. Document Lifecycle Tracking
13. Data Availability Matrix
14. Fields NOT Available
15. Rate Limits & Best Practices
16. Real Data Examples
17. Integration Gotchas

[Link] Page 2 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

1. Quick Reference

APIs at a Glance

# Carrier API Base URL Purpose

Track & [Link] Container/booking

1 Maersk
Trace private/events tracking events

Port cut-off times

2 Maersk Deadlines [Link]
per vessel/voyage

Demurrage
[Link] D&D charges,
3 Maersk & Deten-
charges/import/{DMR\|DET} LFD, free days
tion

Track &
Container/booking
4 Hapag Trace [Link]
tracking events
Events v2

Point-to-
[Link] Route options
5 Hapag Point
to-point-routes with cut-offs
Routes v1

Vessel
[Link] Full port rotation
6 Hapag Schedules
schedules with ETA/ETD
v1

Query Capability Matrix

Query By Maersk API Hapag API

Booking Number Track & Trace Track & Trace

Container Number Track & Trace Track & Trace

Bill of Lading Track & Trace + D&D Track & Trace

POL + POD (route) – P2P Routes

Vessel Name / IMO – Vessel Schedules

Vessel + Voyage + Port Deadlines Vessel Schedules

Service Code – Vessel Schedules

[Link] Page 3 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

2. Authentication

Maersk: OAuth 2.0 (Client Credentials)

POST [Link]
Content-Type: application/x-www-form-urlencoded

Headers:
Consumer-Key: {MAERSK_CUSTOMER_KEY}

Body:
client_id={MAERSK_CUSTOMER_KEY}
&client_secret={MAERSK_CONSUMER_SECRET}
&grant_type=client_credentials

Response:

{
"access_token": "eyJhbGciOi...",
"token_type": "bearer",
"expires_in": 7200,
"scope": "..."
}

All subsequent Maersk API calls require:

Headers:
Authorization: Bearer {access_token}
Consumer-Key: {MAERSK_CUSTOMER_KEY}
Accept: application/json

Token caching: Token is valid for 7200 seconds (2 hours). Cache it and refresh 5 minutes before expiry. Do NOT re-
quest a new token per API call.

Hapag-Lloyd: Static API Keys

No OAuth flow required. Pass credentials directly in every request:

Headers:
X-IBM-Client-Id: {HAPAG_CLIENT_ID}
X-IBM-Client-Secret: {HAPAG_CLIENT_SECRET}
Accept: application/json

[Link] Page 4 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

For Schedules API (v1), also include:

API-Version: 1

[Link] Page 5 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

3. Environment Variables

# Maersk
MAERSK_CONSUMER_KEY= # OAuth consumer key
MAERSK_CONSUMER_SECRET= # OAuth consumer secret
MAERSK_CUSTOMER_KEY= # API consumer key (goes in header)
MAERSK_CUSTOMER_CODE= # Customer ID (for D&D queries)
MAERSK_API_BASE_URL=[Link]
MAERSK_TOKEN_URL=[Link]

# Hapag-Lloyd
HAPAG_CLIENT_ID= # X-IBM-Client-Id header
HAPAG_CLIENT_SECRET= # X-IBM-Client-Secret header
HAPAG_API_BASE_URL=[Link]

[Link] Page 6 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

4. API #1: Maersk Track & Trace

Endpoint

GET [Link]

Query Parameters

Parameter Required Type Description

One of 3 re-
carrierBookingReference string Booking number
quired

One of 3 re-
transportDocumentReference string Bill of Lading number
quired

One of 3 re-
equipmentReference string Container number (e.g., MRKU6651831 )
quired

Comma-separated:
eventType No string
SHIPMENT,TRANSPORT,EQUIPMENT

Filter: gte:2026-01-
eventCreatedDateTime No string
01T00:00:00Z

limit No integer Max events to return

cursor No string Pagination cursor

At least one of carrierBookingReference , transportDocumentReference , or

equipmentReference is required.

Response Structure

{
"events": [
{
"eventID": "14203378004",
"eventType": "SHIPMENT | TRANSPORT | EQUIPMENT",
"eventDateTime": "2026-01-21T04:12:00+05:30",
"eventCreatedDateTime": "2026-01-21T04:15:00Z",
"eventClassifierCode": "ACT | EST | PLN",

// --- SHIPMENT event fields ---

[Link] Page 7 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

"shipmentEventTypeCode": "RECE | DRFT | PENA | PENU | REJE | APPR | ISSU |

SURR | SUBM | VOID | CONF | REQS | CMPL | HOLD | RELS",
"documentTypeCode": "SHI | TRD | VGM | BKG | SRM",
"documentID": "263706417",
"reason": "Optional reason text",
"references": [
{ "referenceType": "EQ | CR | FF | SI | PO | AAO", "referenceValue":
"MRKU6651831" }
],

// --- TRANSPORT event fields ---

"transportEventTypeCode": "ARRI | DEPA",
"delayReasonCode": "WEA",
"changeRemark": "Weather delay",
"documentReferences": [
{ "documentReferenceType": "BKG", "documentReferenceValue": "263706417"
},
{ "documentReferenceType": "TRD", "documentReferenceValue": "263706417"
}
],
"transportCall": {
"transportCallID": "...",
"carrierServiceCode": "TP6",
"exportVoyageNumber": "603W",
"importVoyageNumber": "603E",
"UNLocationCode": "INPPV",
"facilityCode": "VPAVT",
"facilityCodeListProvider": "SMDG",
"facilityTypeCode": "POTE",
"otherFacility": "Pipavav Port Terminal, Gujarat, India",
"modeOfTransport": "VESSEL | RAIL | TRUCK | BARGE",
"location": {
"locationName": "Pipavav",
"UNLocationCode": "INPPV"
},
"vessel": {
"vesselIMONumber": "9245756",
"vesselName": "CORNELIA MAERSK",
"vesselFlag": "DK",
"vesselCallSignNumber": "OXML2",
"vesselOperatorCarrierCode": "MAEU"
}
},

// --- EQUIPMENT event fields ---

"equipmentEventTypeCode": "LOAD | DISC | GTIN | GTOT | STUF | STRP | PICK
| DROP | RSEA | RMVD | INSP",
"equipmentReference": "MRKU6651831",
"ISOEquipmentCode": "22G1",

[Link] Page 8 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

"emptyIndicatorCode": "EMPTY | LADEN",

"seals": [
{ "sealNumber": "IN3129431", "sealSource": "CAR | SHI | PHY | VET |
CUS", "sealType": "KLP | BLT | WIR" }
],
"eventLocation": {
"locationName": "Pipavav",
"UNLocationCode": "INPPV"
}
}
]
}

Reference Types (on Shipment Events)

Code Meaning Example

EQ Equipment (container) MRKU6651831

CR Carrier Reference (booking) 263706417

FF Freight Forwarder ref Forwarder’s internal ref

SI Shipping Instructions ref SI number

PO Purchase Order Buyer’s PO

AAO Additional reference Other

[Link] Page 9 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

5. API #2: Maersk Deadlines

Endpoint

GET [Link]

Query Parameters (all required)

Parameter Type Description Example

ISOCountryCode string 2-letter country code IN , US , OM

Pipavav ,
portOfLoad string City name (exact match required) Salalah ,
Shanghai

vesselIMONumber string 7-digit IMO number 9245756

voyage string Voyage number 603W

Response Structure

[
{
"shipmentDeadlines": {
"terminalName": "APM Terminals Pipavav",
"deadlines": [
{
"deadlineName": "Commercial Cargo Cutoff",
"deadlineLocal": "2026-01-20T22:00:00"
},
{
"deadlineName": "Shipping Instructions Deadline",
"deadlineLocal": "2026-01-16T17:00:00"
},
{
"deadlineName": "Commercial Verified Gross Mass Deadline",
"deadlineLocal": "2026-01-16T17:00:00"
},
{
"deadlineName": "Special Cargo Documentation Deadline",
"deadlineLocal": "2026-01-19T19:00:00"
},

[Link] Page 10 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

{
"deadlineName": "Final DGD Submission deadline",
"deadlineLocal": "2026-01-21T00:00:00"
},
{
"deadlineName": "Empty Container Pickup Deadline",
"deadlineLocal": "2026-01-22T17:00:00"
},
{
"deadlineName": "Shipping Instructions Deadline for Advance Manifest
Cargo",
"deadlineLocal": "2026-01-25T16:00:00"
}
]
}
}
]

Known Deadline Names

Deadline Name Description

Commercial Cargo Cutoff Last time to deliver full container to terminal

Shipping Instructions Deadline SI submission deadline

Shipping Instructions Deadline for Advance Manifest Cargo SI deadline for AMS/ENS cargo

Commercial Verified Gross Mass Deadline VGM submission deadline

Special Cargo Documentation Deadline OOG/special cargo docs

Final DGD Submission deadline Dangerous goods declaration

Empty Container Pickup Deadline Last time to pick up empty container

[Link] Page 11 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

6. API #3: Maersk Demurrage & Detention

Endpoints

GET [Link] # Demurrage

GET [Link] # Detention

Query Parameters (all required)

Parameter Type Description Example

billOfLadingNumber string 9-char alphanumeric B/L 262444238

carrierCustomerCode string Your Maersk customer ID 33104620597

MAEU , SEAU ,
carrierCode string Carrier code SEJJ , MCPU ,
MAEI

Optional, YYYY-MM-DD (default: +30

chargesEndDate string 2026-03-01
days)

Response Structure

{
"billOfLadingNumber": "262444238",
"carrierCustomerCode": "33104620597",
"carrierCode": "MAEU",
"chargeType": "DMR",
"chargeName": "Demurrage",
"isInvalidFreeTime": false,
"currencyCode": "USD",
"location": {
"countryCode": "US",
"countryName": "United States",
"cityName": "Newark",
"locationName": "Newark - Maher Terminal",
"UNLocationCode": "USEWR",
"UNRegionCode": "NJ",
"UNRegionName": "New Jersey",
"carrierSiteGeoID": "1D0KF47J1OI2N"
},
"equipmentCharges": [

[Link] Page 12 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

{
"equipmentReference": "MRKU9294928",
"isFinalCharge": true,
"chargesCalculatedDateTime": "2026-02-07T07:35:26",
"systemMessage": "Optional system message",
"freePeriod": {
"freeDays": 4,
"estimatedFreeStartDate": "2026-02-06",
"actualFreeStartDate": "2026-02-06",
"originalLastFreeDate": "2026-02-11",
"estimatedLastFreeDate": "2026-02-11",
"actualLastFreeDate": "2026-02-11"
},
"chargeablePeriod": {
"startDate": "2026-02-12",
"endDate": "2026-03-01",
"forceMajeureDaysDetails": [],
"chargesByDates": [
{
"chargesByDate": "2026-02-12",
"amount": 150,
"chargeableDays": 1,
"rateTiers": [
{ "rate": 150, "numberOfDays": 1 }
]
}
]
}
}
]
}

Key Fields for LFD (Last Free Day)

Field Description

[Link] Number of free days granted

[Link] When free period actually started

[Link] Original LFD before any amendments

[Link] Current/actual LFD

[Link] Estimated LFD (before container arrives)

Important: D&D data is only available AFTER container is discharged at destination. Queries for in-transit shipments
return 404.

[Link] Page 13 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

[Link] Page 14 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

7. API #4: Hapag-Lloyd Track & Trace

Endpoint

GET [Link]

Query Parameters

Parameter Required Type Description

equipmentReference One of 3 required string Container number

carrierBookingReference One of 3 required string Booking number

transportDocumentReference One of 3 required string Bill of Lading number

SHIPMENT ,
TRANSPORT ,
eventType No string
EQUIPMENT (comma-sep-
arated)

Filter: ISSU , CONF ,

shipmentEventTypeCode No string
RECE , APPR

transportEventTypeCode No string Filter: ARRI , DEPA

Filter: LOAD , DISC ,

equipmentEventTypeCode No string GTIN , GTOT , STUF ,
STRP

documentTypeCode No string Filter: BKG , TRD

exportVoyageNumber No string Filter by voyage

UNLocationCode No string Filter by port

Filter: :gte , :gt ,

eventCreatedDateTime No string
:lte , :lt , :eq

Response Structure

Returns a flat array of events (NOT wrapped in {events: []} like Maersk):

[
{

[Link] Page 15 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

"eventID": "uuid-string",
"eventType": "SHIPMENT | TRANSPORT | EQUIPMENT",
"eventDateTime": "2025-09-26T13:49:11Z",
"eventCreatedDateTime": "2025-09-26T13:58:11.936Z",
"eventClassifierCode": "ACT | EST | PLN",

// SHIPMENT events
"shipmentEventTypeCode": "ISSU | CONF | RECE | APPR",
"documentTypeCode": "TRD | BKG",
"documentID": "HLCUDE1250918387",

// TRANSPORT events
"transportEventTypeCode": "ARRI | DEPA",
"transportCall": {
"transportCallId": "uuid",
"exportVoyageNumber": "2533E",
"importVoyageNumber": "2533W",
"UNLocationCode": "INMUN",
"facilityCode": "AMCT",
"facilityCodeListProvider": "SMDG",
"facilityTypeCode": "POTE",
"modeOfTransport": "VESSEL | RAIL | TRUCK",
"location": {
"locationName": "MUNDRA",
"UNLocationCode": "INMUN",
"address": { "name": "ADANI PORT" }
},
"vessel": {
"vesselIMONumber": "9450399",
"vesselName": "TORRENTE"
}
},

// EQUIPMENT events
"equipmentEventTypeCode": "LOAD | DISC | GTIN | GTOT | STUF | STRP",
"equipmentReference": "TCNU1425767",
"ISOEquipmentCode": "45GP",
"emptyIndicatorCode": "EMPTY | LADEN",
"seals": [
{ "sealNumber": "ML-IN2349382", "sealSource": "CAR", "sealType": "BLT" }
],
"eventLocation": {
"locationName": "MUNDRA",
"UNLocationCode": "INMUN",
"address": { "name": "ADANI PORT" }
}
}
]

[Link] Page 16 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

Key Difference from Maersk

Aspect Maersk Hapag

Response wrapper { "events": [...] } Flat array [...]

4 codes (ISSU, CONF, RECE,

Shipment event codes 13 codes
APPR)

6 codes (LOAD, DISC, GTIN,

Equipment event codes 11 codes
GTOT, STUF, STRP)

Container query returns SHIPMENT No (only EQUIPMENT + TRANS-

Yes
events PORT)

delayReasonCode Yes No

reason field Yes No

references[] on events Yes No

otherFacility (full address) Yes No

[Link] Page 17 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

8. API #5: Hapag-Lloyd Point-to-Point Routes

Endpoint

GET [Link]

Headers (additional)

API-Version: 1

Query Parameters

Parameter Required Type Description Example

placeOfReceipt Yes string Origin UN/LOCODE INMUN

placeOfDelivery Yes string Destination UN/LOCODE USNYC

departureStartDate No string YYYY-MM-DD 2026-02-17

departureEndDate No string YYYY-MM-DD 2026-03-15

arrivalStartDate No string YYYY-MM-DD

arrivalEndDate No string YYYY-MM-DD

maxTranshipment No integer Max transshipment stops 2

receiptTypeAtOrigin No enum CY / SD / CFS

deliveryTypeAtDestination No enum CY / SD / CFS

limit No integer Max results 5

cursor No string Pagination

Response Structure

[
{
"solutionNumber": 1,
"transitTime": 26,

[Link] Page 18 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

"receiptTypeAtOrigin": "CY",
"deliveryTypeAtDestination": "CY",
"placeOfReceipt": {
"facilityTypeCode": "POTE",
"location": {
"locationName": "MUNDRA",
"UNLocationCode": "INMUN"
},
"dateTime": "2026-02-19T01:00:00+05:30"
},
"placeOfDelivery": {
"facilityTypeCode": "POTE",
"location": {
"locationName": "NEW YORK",
"UNLocationCode": "USNYC"
},
"dateTime": "2026-03-17T10:00:00-04:00"
},
"cutOffTimes": [
{ "cutOffDateTimeCode": "DCO", "cutOffDateTime": "2026-02-
15T17:00:00+05:30" },
{ "cutOffDateTimeCode": "FCO", "cutOffDateTime": "2026-02-
17T13:00:00+05:30" },
{ "cutOffDateTimeCode": "DGC", "cutOffDateTime": "2026-02-
17T13:00:00+05:30" },
{ "cutOffDateTimeCode": "OBC", "cutOffDateTime": "2026-02-
17T13:00:00+05:30" },
{ "cutOffDateTimeCode": "RCO", "cutOffDateTime": "2026-02-
17T13:00:00+05:30" },
{ "cutOffDateTimeCode": "TCO", "cutOffDateTime": "2026-02-
17T13:00:00+05:30" },
{ "cutOffDateTimeCode": "VCO", "cutOffDateTime": "2026-02-
17T13:00:00+05:30" }
],
"legs": [
{
"sequenceNumber": 1,
"transport": {
"modeOfTransport": "VESSEL",
"vessel": {
"vesselIMONumber": "9450399",
"name": "TORRENTE",
"flag": "LR",
"callSign": "5LRS5"
},
"universalServiceReference": "SR12345A",
"universalExportVoyageReference": "2533E",
"servicePartners": [
{
"carrierCode": "HLC",

[Link] Page 19 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

"carrierServiceName": "IOS - India Ocean Service",

"carrierServiceCode": "IO1",
"carrierExportVoyageNumber": "2533E"
}
]
},
"departure": {
"location": { "UNLocationCode": "INMUN", "locationName": "MUNDRA" },
"dateTime": "2026-02-19T01:00:00+05:30"
},
"arrival": {
"location": { "UNLocationCode": "USNYC", "locationName": "NEW YORK" },
"dateTime": "2026-03-17T10:00:00-04:00"
}
}
]
}
]

[Link] Page 20 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

9. API #6: Hapag-Lloyd Vessel Schedules

Endpoint

GET [Link]

Headers (additional)

API-Version: 1

Query Parameters (at least one filter required besides dates)

Parameter Required Type Description Example

vesselIMONumber One filter req string IMO number 9450399

vesselName One filter req string Vessel name TORRENTE

carrierServiceCode One filter req string Service code AA7

universalServiceReference One filter req string Universal service ref

carrierVoyageNumber One filter req string Voyage number 2533E

UNLocationCode One filter req string Port code INMUN

facilitySMDGCode No string Terminal SMDG code AMCT

vesselOperatorCarrierCode No string Carrier SCAC HLC

2026-02-
startDate No string YYYY-MM-DD
01

2026-04-
endDate No string YYYY-MM-DD
01

limit No integer Max results 5

cursor No string Pagination

Response Structure

[Link] Page 21 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

{
"carrierServiceName": "IOS - India Ocean Service",
"carrierServiceCode": "IO1",
"universalServiceReference": "SR12345A",
"vesselSchedules": [
{
"vessel": {
"vesselIMONumber": "9450399",
"name": "TORRENTE",
"flag": "LR",
"callSign": "5LRS5",
"operatorCarrierCode": "HLC",
"MMSINumber": "636092708"
},
"isDummyVessel": false,
"transportCalls": [
{
"portVisitReference": "PVREF123",
"transportCallReference": "6084822",
"carrierImportVoyageNumber": "2533W",
"carrierExportVoyageNumber": "2533E",
"universalImportVoyageReference": "...",
"universalExportVoyageReference": "...",
"location": {
"UNLocationCode": "INMUN",
"locationName": "MUNDRA",
"facilitySMDGCode": "AMCT",
"address": { "city": "MUNDRA", "countryCode": "IN" }
},
"timestamps": [
{
"eventTypeCode": "ARRI",
"eventClassifierCode": "EST",
"eventDateTime": "2026-05-05T14:00:00+05:30"
},
{
"eventTypeCode": "DEPA",
"eventClassifierCode": "EST",
"eventDateTime": "2026-05-07T01:00:00+05:30"
}
],
"cutOffTimes": [
{ "cutOffDateTimeCode": "FCO", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "VCO", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "DOC", "cutOffDateTime": "2026-05-
04T18:00:00+05:30" },

[Link] Page 22 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

{ "cutOffDateTimeCode": "DGD", "cutOffDateTime": "2026-05-

04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "OOG", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "REF", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "SHI", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "EFC", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "LCO", "cutOffDateTime": "2026-05-
04T19:00:00+05:30" },
{ "cutOffDateTimeCode": "DBC", "cutOffDateTime": "2026-04-
30T10:00:00+05:30" }
]
}
]
}
]
}
]

[Link] Page 23 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

10. DCSA Event Types Reference

Event Types

Type Description Maersk Hapag

SHIPMENT Document lifecycle events Yes Yes

TRANSPORT Vessel/vehicle arrivals & departures Yes Yes

EQUIPMENT Container physical movements Yes Yes

Event Classifier Codes

Code Meaning Description

ACT Actual Event has occurred

EST Estimated Expected to occur

PLN Planned Scheduled/planned

Shipment Event Type Codes

[Link] Page 24 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

Code Meaning Maersk Hapag When it fires

RECE Received Yes Yes Document received by carrier

CONF Confirmed Yes Yes Booking confirmed

DRFT Drafted Yes No Draft B/L created

Document pending approval (e.g., B/L

PENA Pending Approval Yes No
surrender)

PENU Pending Update Yes No Document pending update

REJE Rejected Yes No Document rejected

APPR Approved Yes Yes Document approved

ISSU Issued Yes Yes Document issued (B/L issued)

SURR Surrendered Yes No B/L surrendered

SUBM Submitted Yes No Document submitted

VOID Void Yes No Document voided

REQS Requested Yes No Action requested

CMPL Completed Yes No Process completed

HOLD On Hold Yes No Document on hold

RELS Released Yes No Document released from hold

Document Type Codes

Code Document Maersk Hapag

BKG Booking No Yes

SHI Shipping Instructions Yes No

TRD Transport Document (B/L) Yes Yes

VGM Verified Gross Mass Yes No

SRM Surrender Request Message Yes No

Transport Event Type Codes

[Link] Page 25 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

Code Meaning Maersk Hapag

ARRI Arrived Yes Yes

DEPA Departed Yes Yes

Equipment Event Type Codes

Code Meaning Maersk Hapag Description

LOAD Loaded Yes Yes Container loaded onto vessel/rail

Container discharged from ves-

DISC Discharged Yes Yes
sel/rail

GTIN Gated In Yes Yes Container entered terminal/depot

GTOT Gated Out Yes Yes Container left terminal/depot

STUF Stuffed Yes Yes Cargo loaded into container

STRP Stripped Yes Yes Cargo unloaded from container

PICK Pick-up Yes No Container picked up

DROP Drop-off Yes No Container dropped off

RSEA Resealed Yes No Container resealed

RMVD Removed Yes No Seal/item removed

INSP Inspected Yes No Container inspected

Mode of Transport

Code Meaning

VESSEL Ocean vessel

RAIL Railway

TRUCK Road transport

BARGE Inland waterway

ISO Equipment Codes (Container Types)

[Link] Page 26 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

Code Size Type

22G1 20ft Standard dry

42G1 40ft Standard dry

45G1 40ft HC High cube dry

45GP 40ft HC High cube dry (Hapag variant)

22R1 20ft Reefer

42R1 40ft Reefer

22U1 20ft Open top

42U1 40ft Open top

22P1 20ft Flat rack

[Link] Page 27 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

11. Cut-off Code Mapping

Hapag P2P vs Vessel Schedule codes (different codes, same concept)

Cut-off Type P2P Code Vessel Schedule Code Maersk Name

Commercial Cargo
FCL Cargo Delivery FCO FCO
Cutoff

Documentation DCO DOC –

Final DGD Submission

Dangerous Goods DGC DGD
deadline

Special Cargo Docu-

OOG/Special Cargo OBC OOG
mentation Deadline

Reefer RCO REF –

Commercial Verified
VGM VCO VCO
Gross Mass Deadline

Transhipment TCO – –

Shipping Instructions
Shipping Instructions – SHI
Deadline

Earliest Full Container – EFC –

LCL Delivery – LCO –

Dry Bulk Container – DBC –

Empty Container Pick-

Empty Container Pickup – –
up Deadline

SI Deadline for Ad-

SI for Advance Manifest – –
vance Manifest Cargo

[Link] Page 28 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

12. Document Lifecycle Tracking

Maersk: Full B/L lifecycle (5 stages tracked)

RECE + SHI → Shipping Instructions received (timestamp)

DRFT + TRD → Draft B/L created (timestamp)
RECE + VGM → VGM submitted (timestamp, can repeat)
ISSU + TRD → B/L issued (timestamp)
PENA + SRM → B/L surrender request pending (timestamp)

Additional codes exist in Maersk spec but weren’t observed in test data: - SURR + TRD = B/L surrendered - RELS
+ TRD = B/L released - HOLD + TRD = B/L on hold

Hapag: Minimal (2 stages only)

CONF + BKG → Booking confirmed (timestamp)

ISSU + TRD → B/L issued (timestamp)

No SI received, no draft B/L, no VGM, no surrender tracking.

Booking Date Availability

Maersk Hapag

Booking
confirmation No (no BKG event) Yes ( CONF + BKG with timestamp)
date

Earliest
available SI Received ( RECE + SHI ) Booking Confirmed ( CONF + BKG )
event

Container-level vs Booking-level

Query By Maersk returns SHIPMENT events? Hapag returns SHIPMENT events?

Booking
Yes (all document events) Yes (CONF + ISSU only)
number

Container
Yes (same document events) No (only EQUIPMENT + TRANSPORT)
number

B/L number Yes Yes

[Link] Page 29 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

[Link] Page 30 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

13. Data Availability Matrix

What you CAN get from APIs

Data Point Maersk Hapag API Used

Container tracking
Yes Yes Track & Trace
(LOAD/DISC/GTIN/GTOT)

Vessel arrivals/departures Yes Yes Track & Trace

ETD / ETA Yes Yes Track & Trace (EST events)

Vessel name & IMO Yes Yes Track & Trace

Voyage number Yes Yes Track & Trace

Port UN/LOCODE Yes Yes Track & Trace

Terminal/facility code Yes Yes Track & Trace

Mode of transport (VES-

Yes Yes Track & Trace
SEL/RAIL/TRUCK)

Container type (ISO code) Yes Yes Track & Trace

Empty/Laden indicator Yes Yes Track & Trace

Seal number Yes Yes Track & Trace

B/L Issued timestamp Yes Yes Track & Trace (SHIPMENT)

B/L Draft timestamp Yes No Track & Trace

SI Received timestamp Yes No Track & Trace

VGM Submitted timestamp Yes No Track & Trace

B/L Surrender tracking Yes No Track & Trace

Booking Confirmed date No Yes Track & Trace

Delay reason code Yes No Track & Trace

Cut-off times (origin) Yes Yes Deadlines / P2P Routes / VS

Cut-off times (all ports on rotation) No Yes Vessel Schedules

Transit time No Yes P2P Routes

Route options (POL→POD) No Yes P2P Routes

Full vessel rotation No Yes Vessel Schedules

Service name/code No Yes Vessel Schedules

LFD (Last Free Day) - Demurrage Yes No D&D API

[Link] Page 31 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

LFD (Last Free Day) - Detention Yes No D&D API

Free days at destination Yes No D&D API

Daily D&D charge breakdown Yes No D&D API

D&D rate tiers Yes No D&D API

Currency of charges Yes No D&D API

[Link] Page 32 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

14. Fields NOT Available in Any API

Data Point Maersk Hapag Where to Get Instead

Spot vs Contract booking Maersk Offers API / Hapag Contract API (separate
No No
type commercial APIs)

Rate / Price / Freight cost No No Commercial APIs (not tracking APIs)

Booking expiry date No No Carrier email/portal

VGM weight value (kg) No No EDI VERMAS message, carrier portal

Container/cargo gross
No No VGM certificate, packing list
weight

Container tare weight No No BIC container database

Arrival Notice document No No Carrier email only

Invoice document No No Carrier email/portal only

Credit/Debit notes No No Carrier email/portal only

Customs clearance status No No CBP ACE (US), ICEGATE (India), customs broker

Customs hold/release No No Customs authority systems

AMS/ISF/ENS filing status No No Customs broker systems

HTS codes / Duty amounts No No Commercial invoice, customs entry

Commodity description No No B/L / commercial invoice

Shipper / Consignee names No No B/L (not exposed in tracking APIs)

Contract number No No Carrier commercial portal

No (Maersk
D&D charges at destination No Hapag portal only
has)

[Link] Page 33 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

15. Rate Limits & Best Practices

Rate Limits

Maersk Hapag

Track & Trace 4,000/hour, 60/minute 50/hour (Tryout plan)

Deadlines 2,000/hour, 60/minute N/A

D&D 2,000/hour, 100/minute N/A

Schedules N/A 50/hour (Tryout plan)

Best Practices

1. Maersk token caching: Cache the OAuth token for its full TTL (7200s). Refresh 5 min before expiry.

2. Hapag call spacing: Add 1.5s delay between consecutive calls to stay under the Tryout limit. For production, re-
quest a higher-tier plan.

3. Batch container tracking: For N containers, space API calls to stay within rate limits:

Maersk: 60 calls/min = 1 per second is safe

Hapag: 50/hour = 1 per 72 seconds on Tryout plan

4. Idempotent polling: Track events by eventID or eventCreatedDateTime to avoid reprocessing.

5. Error handling:

404 from Maersk = no data yet (booking too new, or container not discharged for D&D)
429 = rate limited, back off exponentially
500 / timeout = transient, retry after 30s

6. Maersk Deadlines port name gotcha: Use exact city names, NOT UN/LOCODEs. “Pipavav” works, “JNPT”
doesn’t, “Nhava Sheva” doesn’t. Test each port name against the API before hardcoding.

7. Hapag cut-off code mapping: P2P routes and Vessel Schedules use DIFFERENT codes for the same concept
(see Section 11). Normalize both to a single internal representation.

[Link] Page 34 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

16. Real Data Examples

Example 1: Maersk Multi-Leg Shipment (Booking 263706417)

Route: Ludhiana ICD → Pipavav → Salalah → Shanghai → Los Angeles Container: MRKU6651831 (22G1 = 20ft stan-
dard) 20 events total: 5 Shipment + 8 Transport + 7 Equipment

Document lifecycle:
Jan 10 RECE SHI SI Received
Jan 10 DRFT TRD Draft B/L Created
Jan 14 RECE VGM VGM Submitted (1st)
Jan 18 RECE VGM VGM Submitted (2nd)
Feb 13 ISSU TRD B/L Issued

Container journey:
Jan 03 GTOT INSWA EMPTY Empty pickup at Ludhiana ICD
Jan 14 GTIN INLUH LADEN Gate in laden at Ludhiana depot
Jan 14 GTOT INLUH LADEN Gate out laden (rail to Pipavav)
Jan 19 GTIN INPPV LADEN Gate in at Pipavav port
Jan 20 LOAD INPPV LADEN Loaded on CORNELIA MAERSK
Jan 26 DISC OMSLL LADEN Discharged at Salalah (transshipment)
Jan 28 LOAD OMSLL LADEN Loaded on ROTTERDAM EXPRESS

Vessel movements:
Jan 14 EST DEPA INLUH Rail depart Ludhiana
Jan 18 EST ARRI INPPV Rail arrive Pipavav
Jan 21 ACT DEPA INPPV CORNELIA MAERSK departs Pipavav
Jan 26 ACT ARRI OMSLL CORNELIA MAERSK arrives Salalah
Jan 28 ACT DEPA OMSLL ROTTERDAM EXPRESS departs Salalah
Feb 18 EST ARRI CNSHA ROTTERDAM EXPRESS arrives Shanghai
Feb 25 EST DEPA CNSHA GUTHORM MAERSK departs Shanghai
Mar 11 EST ARRI USLAX GUTHORM MAERSK arrives Los Angeles

Example 2: Hapag Full Container Journey (Booking 14252782)

Route: Gurgaon ICD → Mundra → Salalah → Norfolk → Detroit Container: TCNU1425767 (45GP = 40ft high-cube)
B/L: HLCUDE1250918387 19 events total: 2 Shipment + 2 Transport + 15 Equipment

Document lifecycle:
Sep 19 CONF BKG Booking Confirmed
Sep 26 ISSU TRD B/L Issued (HLCUDE1250918387)

Container journey:
Sep 10 GTOT INGGN EMPTY Empty pickup at Gurgaon

[Link] Page 35 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

Sep 11 GTIN INGGN LADEN Gate in laden (stuffed)

Sep 12 GTOT INGGN LADEN Gate out (rail to Mundra)
Sep 16 GTIN INMUN LADEN Gate in at Mundra port
Sep 24 LOAD INMUN LADEN Loaded on TORRENTE
Oct 29 DISC USORF LADEN Discharged at Norfolk
Nov 04 LOAD USORF LADEN Loaded on rail
Nov 05 GTOT USORF LADEN Gate out from Norfolk
Nov 09 GTIN USDET LADEN Gate in at Detroit
Nov 10 GTOT USDET LADEN Delivered to consignee
Nov 11 GTIN USDET EMPTY Empty returned

Example 3: Maersk D&D (Booking 262444238, discharged at Newark)

Demurrage:
Container: MRKU9294928
Location: Newark - Maher Terminal (USEWR)
Free days: 4
Free period start: 2026-02-06
LFD (original): 2026-02-11
LFD (actual): 2026-02-11
Total charges: $0 (within free time)

Detention:
Free days: 4
LFD: 2026-02-11
Total charges: $0

[Link] Page 36 of 37
Carrier API Integration Guide 18/02/26, 6:23 PM

17. Integration Gotchas

1. Maersk wraps events in {events: []} , Hapag returns a flat array [] . Normalize this in your parser.

2. Maersk Deadlines API requires exact city names, not UN/LOCODEs. You must maintain a mapping of
UN/LOCODE to Maersk-accepted city names. Test each port before deploying.

3. Hapag P2P and Vessel Schedule cut-off codes differ for the same concept. Map both: DGC / DGD → Danger-
ous Goods, OBC / OOG → OOG Cargo, RCO / REF → Reefer, DCO / DOC → Documentation.

4. Hapag container queries don’t return SHIPMENT events. If you need B/L status for a Hapag container, you
must query by booking number or B/L number instead.

5. Maersk D&D returns 404 for in-transit shipments. D&D data only becomes available after discharge at destina-
tion. Handle 404 gracefully — it doesn’t mean “no B/L found”, it means “not yet available”.

6. Maersk VGM events have timestamps but NOT the weight value. The RECE + VGM event tells you WHEN
VGM was submitted, not HOW MUCH the container weighs.

7. Hapag Tryout plan is limited to 50 calls/hour. For production workloads with 200+ containers, you need to up-
grade or implement aggressive caching.

8. Maersk vessel IMO is returned as a string (e.g., "9245756" not 9245756 ). Always parse/store as string.

9. Hapag [Link] (Schedules) vs [Link] (Track & Trace) — field naming differs be-
tween Hapag APIs. Normalize in your types.

10. Multiple VGM submissions are normal. Maersk booking 265012517 had 4 VGM RECE events — shippers often
resubmit with corrections.

11. Maersk multi-vessel routing: A single booking can use 3+ vessels (feeder → mainline → feeder). Parse ALL
transport events to get the complete route, not just the first vessel.

12. Hapag B/L number format: HLCUDE1250918387 (carrier prefix + country + sequential). Maersk B/L number =
booking number (e.g., 262444238 ).

13. Carrier codes for Maersk D&D: MAEU (Maersk), SEAU (Sealand), SEJJ (Sealand Asia), MCPU (MCC
Transport), MAEI (Maersk Line India). Use the correct code for the specific carrier entity.

Document maintained by: API Integration Team Last verified against live APIs: February 18, 2026

[Link] Page 37 of 37