DCSA Track & Trace and eBL APIs for Ocean Visibility

Three carriers on your tender all say they "support DCSA". The first exposes Track & Trace 2.2 with subscriptions, the second offers polling only and fills half the fields, and the third points you to an eBL platform whose API returns a code your ERP has never seen. Six weeks into the build, the visibility screen shows a container as discharged in Colombo while the dray desk is waiting for it in Nhava Sheva.

The DCSA specifications are precise enough to avoid that, provided you treat each one as a separate contract with its own keys, response codes and owner. This guide maps the event model and the electronic bill of lading APIs to the records your TMS and ERP keep, so that events are verified before use, duplicates are ignored and every title change in an eBL is stored as evidence.

• What this guide covers: which DCSA standards a project touches, the three event families and their classifier, polling versus signed subscriptions, journey keys, the shipping instructions and transport document API, issuance, surrender and platform transfer, and carrier adoption.
• What it adds: a sample event with its signature check, a failure trace at a transhipment port, ownership and rules tables, and a cost model in dollars and rupees.

Which DCSA specifications an ocean visibility build actually uses

A visibility and eBL programme normally touches five DCSA APIs, each versioned on its own. The Digital Container Shipping Association is an industry body formed by container carriers; its standards are voluntary interface contracts, not US or Indian regulation, so availability depends on each carrier's choice of version.

Most shippers consume only the first two directly. Issuance, surrender and interoperability run between carriers and eBL platforms, yet their outcomes decide when your consignee can take delivery, so you need their response codes even if you never call those endpoints. The legal side of electronic bills, including control under UCC 7-106 and India's position, is covered in our electronic bill of lading guide.

Shipment, transport and equipment events and the ACT, EST, PLN tag

Track & Trace 2.2 has three event families, and every event carries an eventClassifierCode of ACT (actual), EST (estimated) or PLN (planned). Only actual equipment events should move a container clock; estimates and plans feed forecasting and nothing else.

• Equipment events: LOAD, DISC, GTIN, GTOT, STUF, STRP, PICK, DROP, INSP, RSEA and RMVD, with emptyIndicatorCode EMPTY or LADEN and the container in equipmentReference.
• Transport events: ARRI and DEPA for a transport call, the vessel or other mode arriving at or leaving a location, with optional delay reason and schedule change remarks.
• Shipment events: the document lifecycle, such as RECE, DRFT, APPR, ISSU, SURR, HOLD and RELS, pointing at a document type such as BKG, SHI, TRD or VGM.

The specification adds one rule that trips up data teams: for shipment events, eventDateTime must equal eventCreatedDateTime. A shipment event therefore records when the document status changed in the carrier's system, never a forecast. Equipment and transport events, by contrast, can describe the future, so the same DISC code can arrive three times for one box: PLN at booking, EST when the vessel is a day out and ACT after the crane move.

DCSA Track & Trace 2.2 separates 11 equipment event codes, 2 transport event codes and 15 shipment event codes, and tags each event ACT, EST or PLN. A container milestone in the TMS should accept only ACT equipment events, keyed to the transport call, while EST and PLN values update forecasts without touching free-time clocks.

Teams that also receive X12 feeds will want a crosswalk. DISC with ACT corresponds to a 315 UV, GTOT with LADEN at the discharge terminal to an OA, and GTIN with EMPTY at a depot to an empty return. Our article on EDI 315 container status codes sets out which of those X12 events start and stop each free-time clock; the same clock logic applies once the DCSA events are mapped.

Polling GET /v2/events or subscribing with a signed callback

Subscriptions are the primary path and polling is the recovery path; a production integration needs both. Track & Trace 2.2 supports polling on GET /v2/events with filters and a cursor, and a push model in which you register a callbackUrl and a shared secret through POST /v2/event-subscriptions.

Paged responses carry Current-Page, Next-Page, Prev-Page, First-Page and Last-Page headers, and each response states its API-Version. Each callback carries the Subscription-ID and a Notification-Signature header of the form sha256=hex. The specification says the signature must cover the entire request body, whitespace and newlines included, decoded as UTF-8 bytes, and that neither headers nor the URL are covered.

POST /dcsa/callbacks/tnt HTTP/1.1
Content-Type: application/json
Subscription-ID: 6c1e0d4a-2b71-4c4e-9a43-0f5d6f2b9e11
Notification-Signature: sha256=<64 hex characters>
API-Version: 2.2.0

[{
  "eventID": "8f2d1c90-5e41-4b6f-a0a7-3c9b72e1d054",
  "eventCreatedDateTime": "2026-11-21T16:09:12+05:30",
  "eventType": "EQUIPMENT",
  "eventClassifierCode": "ACT",
  "eventDateTime": "2026-11-21T16:05:00+05:30",
  "equipmentEventTypeCode": "DISC",
  "equipmentReference": "NXEU5520314",
  "ISOEquipmentCode": "45G1",
  "emptyIndicatorCode": "LADEN",
  "transportCall": {
    "transportCallSequenceNumber": 2,
    "UNLocationCode": "INNSA",
    "exportVoyageNumber": "418W",
    "importVoyageNumber": "419E",
    "modeOfTransport": "VESSEL",
    "vessel": { "vesselIMONumber": "9321483" }
  },
  "documentReferences": [
    { "documentReferenceType": "BKG", "documentReferenceValue": "EXBK5530921" },
    { "documentReferenceType": "TRD", "documentReferenceValue": "EXCRNSA7712044" }
  ]
}]

Receiver check, in order:
1. raw = request body bytes exactly as received (UTF-8, no re-serialising)
2. expected = HMAC-SHA256(secret stored for Subscription-ID, raw), hex encoded
3. if "sha256=" + expected != Notification-Signature: reply 4xx, store nothing
4. for each event: skip if eventID already stored; else insert raw JSON + parsed fields

The sample is illustrative. Step 2 shows the common keyed-hash construction; confirm the exact algorithm in each carrier's implementation note, because the specification names the signature type as sha256 and leaves the shared-secret mechanics to the parties. Run a daily poll with eventCreatedDateTime filters to catch callbacks lost during your own outages.

Journey keys that keep one container's moves apart

A container number is not a key. The same box can be discharged at a transhipment port and again at destination within one bill of lading, and it will be reused on another booking next month. Key each milestone on the container, the event code, the classifier and the transport call, and deduplicate only on eventID.

• Transport call: UNLocationCode plus transportCallSequenceNumber, which the specification says distinguishes two separate calls at the same location within one voyage.
• Voyage numbers: exportVoyageNumber and importVoyageNumber, because carrierVoyageNumber is marked deprecated in the 2.2 transport call object.
• Vessel: vesselIMONumber, the seven-digit IMO number, rather than the vessel name, which carriers spell differently.
• Documents: documentReferences with BKG and TRD values, which tie an equipment event to your booking and transport document.

The trace below is illustrative and shows what happens when a feed is keyed on container and event code alone. Times are India Standard Time.

1. 14 Nov 03:10: DISC, ACT, NXEU5520314 at LKCMB (Colombo), transportCallSequenceNumber 3 on the mother vessel. The integration upserts milestone "Discharged" for the box.
2. 14 Nov 03:12: the TMS computes a destination last free day of 28 Nov from that event and clears the destination ETA, because the box "has arrived".
3. 16 Nov 09:30: trailer TRL-7781 reaches the Nhava Sheva terminal for collection under transport order TO-26-44871 and is turned away; the box is still in Colombo. The wasted trip costs ₹6,500.
4. 21 Nov 16:05: DISC, ACT at INNSA, transportCallSequenceNumber 2 on the feeder. The upsert treats it as a duplicate of the Colombo DISC and discards it. The real discharge never reaches the free-time engine.
5. 27 Nov 11:00: the line's detention desk emails a reminder. The fix keys milestones on box, code, classifier, UN/LOCODE and call sequence, and reprocesses the stored raw events.

The broader principle, that planned, estimated and actual records for one journey must remain distinct, is set out in our guide to container tracking API events. That article works from a generic internal model; this one applies the DCSA field names and the transhipment case that most often breaks a DCSA feed.

From shipping instructions to an issued transport document

The Shipping Instructions and Transport Document API is asynchronous: posting instructions returns 202 Accepted with a shippingInstructionsReference, and every later status arrives by notification or by polling. Your documentation system should never assume a submission was accepted until the RECEIVED status comes back.

The transport document then moves through eight statuses that version 3.0.3 defines: DRAFT, APPROVED, ISSUED, PENDING_SURRENDER_FOR_AMENDMENT, SURRENDERED_FOR_AMENDMENT, PENDING_SURRENDER_FOR_DELIVERY, SURRENDERED_FOR_DELIVERY and VOIDED. The consumer approves a draft with PATCH on /v3/transport-documents/{transportDocumentReference}, setting the status to APPROVED, which is the only value the consumer may set there.

• Document type: transportDocumentTypeCode is BOL for a bill of lading or SWB for a sea waybill; a waybill must have isToOrder set to false.
• Negotiability: isToOrder true makes the bill negotiable, with an endorsee party or blank endorsement; false makes it a straight bill.
• Platform choice: for an electronic BOL, sendToPlatform names the holder's eBL platform from a fixed code list, and the field must be absent for paper bills.
• Cancellation: shippingInstructionsStatus can be set to CANCELLED, and updatedShippingInstructionsStatus to UPDATE_CANCELLED; those are the only values the consumer can set on the two fields.

Issuance, surrender and platform transfer: responses to store

Possession and title changes happen between carriers and eBL platforms, but you need their outcomes in your own records because delivery, payment and letters of credit depend on them. Store each response code with its timestamp and the transport document reference.

• Issuance responses: ISSU means the platform issued the document and delivered it to the first holder; BREQ means the platform found a content problem; REFU means issuance was rejected for a reason the platform cannot resolve, such as a failed interoperable transfer.
• Surrender requests: SREQ asks to surrender for delivery and AREQ for amendment; the specification treats a switch to paper as an amendment.
• Surrender responses: SURR means the carrier accepted and now holds the bill; SREJ returns the eBL to the party that asked.
• Platform transfer responses: RECE, DUPE, BSIG, BENV, INCD, MDOC and DISE, covering received, duplicate, bad signature, bad envelope, inconclusive, missing document and disputed envelope.

Integrity is handled with signatures rather than trust. The issuance request carries an issuance manifest as a JWS in compact serialisation, signed by the carrier or its agent, and the interoperability API checks a SHA-256 checksum of the transport document so that a receiving platform can detect a replayed or altered envelope.

DCSA eBL Issuance API 3.0.3 records issuance as ISSU only when the eBL platform has delivered the document to its first holder, and the Surrender API answers SREQ or AREQ requests with SURR or SREJ. The release desk should treat SURR for delivery, stored with the transport document reference, as the release trigger.

Carrier adoption: what the conformance list proves and what it does not

Adoption is uneven, so plan for a mixed estate of DCSA APIs, EDI and portals for several years. DCSA's standard conformance page lists CMA CGM, ONE, Evergreen, ZIM, Yang Ming and PIL as confirmed for Track & Trace 2.x, and MSC, Maersk, Hapag-Lloyd and HMM as unverified legacy entries that are not DCSA-certified.

On electronic bills, nine DCSA member carriers committed on 15 February 2023 to convert 50% of original bills of lading to electronic form within five years and to reach 100% eBL adoption based on DCSA standards by 2030. A commitment is not coverage on your lane, and conformance for one version does not mean every field is populated for every port.

• Version check: ask each carrier which Track & Trace version and which optional fields it sends on your trade lanes, in writing.
• Coverage test: run a 30-day shadow feed and count ACT DISC and GTOT events received within six hours of the event time.
• Fallback: keep EDI 315 or portal data for carriers below your coverage threshold, mapped to the same milestone keys.
• India lanes: customs milestones at INNSA or INMUN, such as the carrier's arrival manifest on ICEGATE, are not DCSA events and still come through your customs broker.

Who owns each DCSA record and who signs off on it

The carrier owns the event; you own the milestone you derive from it and the decision you take on it. Write that split down, because a disputed demurrage bill or a delayed release will turn on which record each party relied on.

Worked cost model in dollars and rupees for a DCSA connection

A DCSA subscription pays for itself through fewer late discharge signals and, where counterparties accept it, through eBL surrender replacing couriered originals. The figures below are illustrative assumptions for one importer, before tax, showing that the same build can pay in one market and not in another.

Without the eBL line, the Indian case loses ₹21,600 a month, because rupee detention rates are lower than US demurrage and the run cost is similar. That is why Indian importers often start with eBL surrender and add event subscriptions later, while US importers on congested terminals usually start with events. The number that matters most is the late-signal rate, so measure it before building.

Rules in the integration layer and calls left to the visibility desk

Signature checks, deduplication and keying are fixed rules that must never be overridden by hand. Judgement belongs in interpreting gaps, conflicting carrier statements and the timing of a release, where software can rank cases but a person decides.

DCSA Track & Trace integrations should enforce three fixed rules in code: Notification-Signature verification on the raw UTF-8 body, deduplication on eventID and milestone keys built from UN/LOCODE plus transportCallSequenceNumber. A 30-day shadow run targeting at least 95% of actual discharge events within six hours shows whether a carrier is ready.

Before go-live, confirm each item below for every carrier and eBL platform you connect.

If you are choosing between building on DCSA APIs and buying a visibility or eBL service, put the checklist and the transhipment test into your tender; our RFP builder turns them into vendor questions. Related guides on ocean documents and container events are collected on the logistics and supply chain hub.