A freight forwarder connects its ERP to an ocean carrier’s electronic bill of lading (eBL) API. A clerk submits shipping instructions, the worker logs HTTP 202, and the job flips to ready for draft approval. Later, the clerk tries to clear a party field by omitting it from an update—only for the republished draft to keep the booking value.
An electronic bill of lading integration checklist prevents those failures by mapping each document transition to its handoff, validation gate, and exception owner. Physical milestone alerts belong in a separate freight shipment exception event model; eBL integration governs legal document state across the cargo owner, the forwarder acting for them, the carrier, and any eBL solution provider.
This checklist uses the Digital Container Shipping Association’s (DCSA) third-party Electronic Bill of Lading standard (DCSA is a third-party standards body, not an Insonl client). DCSA’s public index for Bill of Lading lists 3.0.4 as current, while the v3 page notes that 3.0.4 release artifacts require DCSA Standards Member and Partner Access; this guide cites only DCSA’s public v3 guidance.
Map the four-party boundary before writing code
Forwarders act for a shipper or consignee across booking and documentation (Booking and Bill of Lading Adoption Guide). Separate two tracks before writing connectors:
- Seaway Bills (
transportDocumentTypeCode='SWB') are issued directly by the ocean carrier. - Original electronic Bills of Lading (
transportDocumentTypeCode='BOL'withisElectronic=true) are not issued directly by carriers. In DCSA’s Shipping Instructions logical data model,BOLcovers both paper (isElectronic=false) and electronic (isElectronic=true) Bills of Lading; for electronic originals, carriers issue to an IGP&I-approved eBL solution provider via the Issuance API (PUT /v3/ebl-issuance-requests), and holders surrender through that provider via the Surrender API (eBL Technical Implementation Guidelines).
DCSA’s framework lets participating platforms exchange eBLs; it rests on DCSA eBL platform interoperability: the Platform Interoperability (PINT) API between providers, the Multilateral Service Provider Interoperability Agreement (MSPIA) governing relationships among eBL providers, the Standard Annex accepted by users alongside their platform’s existing terms, and the Control Tracking Registry (CTR) tracking which platform controls the eBL. Before transfer, PINT’s receiver validation checks the counterparty’s PartyCode; an unrecognized PartyCode triggers automatic rejection. Integrity and non-repudiation use certificates, canonical JSON, SHA-256 hashing, and JSON Web Signatures (JWS) (Implementing Digital Signatures for Transport Documents).
DCSA v3 lifecycle checklist: handoffs, checks, and exception owners
DCSA’s eBL Technical Implementation Guidelines cover 14 use cases across Shipping Instructions (SI) and Transport Documents (TD). Assign every stage a validation check and one owner:
| Lifecycle stage (DCSA use cases) | System handoff and state transition | Validation checks | Exception trigger and owner |
|---|---|---|---|
| 1. Submit SI (UC1) | POST /shipping-instructions → sync 202 returning only shippingInstructionsReference (no state yet) → async RECEIVED via POST /shipping-instructions-notifications. |
Verify every linked carrierBookingReference is CONFIRMED or PENDING_AMENDMENT; validate schema and carrier-required booking consistency (isShipperOwned, container type/size, units, isNonOperatingReefer). |
Schema or 7000–7999 error → Integration engineering. Unconfirmed booking or 8000–8999 error → Export documentation desk. |
| 2. Update request & SI amendments (UC2–UC5) | Carrier sets PENDING_UPDATE (mandatory feedback). Forwarder sends PUT /shipping-instructions/{documentReference} → sync 202 → async UPDATE_RECEIVED → UPDATE_CONFIRMED or UPDATE_DECLINED. To request cancellation of a pending update, forwarder sends PATCH with {"updatedShippingInstructionsStatus": "UPDATE_CANCELLED"}; carrier asynchronously accepts (UPDATE_CANCELLED) or declines (stays UPDATE_RECEIVED). |
Check field category (Booking-only, SI-only, or shared); inspect ?updatedContent=true and PENDING_UPDATE feedback; handle 409 (Conflict) during processing. |
PENDING_UPDATE, UPDATE_DECLINED, declined cancellation, or booking CANCELLED → Export documentation desk (plus Booking team if Booking amendment needed). Persistent 409/404 → Integration engineering. |
| 3. Draft TD & approval (UC6–UC7) | Carrier publishes DRAFT (GET /transport-documents/{transportDocumentReference}). Forwarder approves via PATCH /transport-documents/{transportDocumentReference} with {"transportDocumentStatus": "APPROVED"} → sync 202 (stays DRAFT) → async APPROVED. |
Reconcile carrier-supplied TD-only fields (shippedOnBoardDate, receivedForShipmentDate, charges, termsAndConditions) against the ERP file; check for parallel Booking or SI republishes. |
Charge, date, or clause mismatch, or stale draft → Export documentation lead (human gate). |
| 4. Issuance & transfer (UC8) | Carrier sets ISSUED and notifies via POST /shipping-instructions-notifications; for transportDocumentTypeCode='BOL' with isElectronic=true, issues to the eBL provider via PUT /v3/ebl-issuance-requests. Provider transfers via PINT and updates CTR. |
Confirm counterparty platform terms plus Standard Annex acceptance and PartyCode pre-transfer check; verify signature status on the eBL platform. |
Unrecognized PartyCode, PINT rejection, or missing Standard Annex → Trade documentation / compliance. Issuance API or certificate failure → eBL platform admin & integration engineering. |
| 5. Surrender for amendment, void & reissue (UC9–UC11) | Authorized party submits POST /v3/ebl-surrender-requests (surrenderRequestCode: "AREQ" + endorsementChain) via eBL provider → async PENDING_SURRENDER_FOR_AMENDMENT. Accepted branch: carrier sends POST /v3/ebl-surrender-responses with SURR (SURRENDERED_FOR_AMENDMENT), then in UC11 voids (VOIDED) and issues amended TD (ISSUED). Rejected branch: carrier sends SREJ, original TD returns to ISSUED, and that branch ends. |
On the accepted branch, archive VOIDED on receipt and order VOIDED vs ISSUED notifications by time when transportDocumentReference is reused; on switch to paper, record that the eBL prevails in discrepancies. |
SREJ or amendment dispute → Documentation lead & customer service. Lost VOIDED archive on reference reuse → Integration engineering. |
| 6. Surrender for delivery & SI closure (UC12–UC14) | Authorized party submits POST /v3/ebl-surrender-requests (surrenderRequestCode: "SREQ" + endorsementChain) → async PENDING_SURRENDER_FOR_DELIVERY. UC13 accepted: SURR (SURRENDERED_FOR_DELIVERY). UC13 rejected: SREJ returns TD to ISSUED. Separately, UC14 transitions SI to COMPLETED with its own notification (not an automatic step after either UC13 outcome). |
Verify endorsement chain and holder authority before cargo release; handle UC14 SI COMPLETED independently when closing ERP billing. |
SREJ delivery hold or endorsement gap → Import release ops. Unclosed ERP job after COMPLETED → Finance / ERP ops. |
Made-up example: surrender rejection and exception handoff
Both snippets are made-up example payloads (not from a real forwarder, carrier, eBL provider, or Insonl client). The first follows DCSA Use Case 13’s carrier-to-eBL-provider rejection response (POST /v3/ebl-surrender-responses):
{
"surrenderRequestReference": "SR-2026-00419",
"action": "SREJ"
}
When the eBL platform surfaces that SREJ alongside the carrier notification returning the TD to ISSUED, do not retry the surrender call. Write a made-up internal ERP exception record with the keys operators need:
{
"exceptionType": "EBL_SURRENDER_REJECTED",
"transportDocumentReference": "TD-9904128",
"surrenderRequestReference": "SR-2026-00419",
"surrenderRequestCode": "SREQ",
"carrierAction": "SREJ",
"transportDocumentStatus": "ISSUED",
"notificationTime": "2026-11-22T01:12:40Z",
"ownerTeam": "import_release_ops",
"carrierFeedbackPresent": true,
"autoRetry": false
}
Recording transportDocumentReference, surrenderRequestReference, and notificationTime lets import release ops inspect carrier feedback, clear the hold or endorsement gap, and submit a new surrender request only once resolved.
Five DCSA v3 integration traps to check before go-live
- Treating HTTP
202as committed state. In UC1, UC3, UC5, and UC7, the carrier validates synchronously and, if validation succeeds, replies202 (Accepted)before async completion: UC1 has no SI state yet; UC3 and UC5 keep the prior SI state (RECEIVEDorPENDING_UPDATE, and in UC5 the pendingUPDATE_RECEIVEDstate); UC7 staysDRAFT. Polling differs by stage:GET /shipping-instructions/{documentReference}returns202,404, or409without content in UC1 beforeRECEIVED, whereas UC3 and UC5 can return200with the existing SI (or202/409mid-processing, with?updatedContent=trueto retrieve the updated SI), and UC7 checks status viaGET /transport-documents/{transportDocumentReference}(200or202). Drive ERP transitions fromPOST /shipping-instructions-notificationsor bounded polling, never from202. - Trying to clear Booking fields through Shipping Instructions. Per DCSA’s Implementing Booking and Bill of Lading Technical Guide, TD property values originate from three sources—Booking, Shipping Instructions, and the implementer (typically the carrier)—grouped into four categories: Booking-only (
receiptTypeAtOrigin,deliveryTypeAtDestination,declaredValue, dangerous goods, reefer settings), SI-only (isElectronic,isToOrder, copy counts), shared Booking-and-SI fields where SI takes precedence (manydocumentPartiessuch as Shipper, Consignee, and Notify Parties, plustransportDocumentTypeCodeandfreightPaymentTermCode), and carrier-supplied TD-only fields (shippedOnBoardDate,charges,termsAndConditions). Setting a shared field tonullor omitting it in SI cannot clear a Booking value—amend the Booking instead. ACANCELLEDlinked booking moves the SI toPENDING_UPDATE. - Mishandling notification resends and
VOIDEDreference reuse. Carriers may resendPOST /shipping-instructions-notificationswith a new or reusedid, and content orfeedbackmay differ between deliveries—and between the root and nested document objects (e.g.INFOfeedback in one place only). Protect writes using idempotent ERP posting on retries keyed on state and payload digest rather than dropping duplicateids blindly. In UC11, when a carrier reusestransportDocumentReference, the notificationtimeproperty alone distinguishesVOIDEDfrom re-ISSUED, and once amended,GET /transport-documents/{transportDocumentReference}returns only the new TD—archiveVOIDEDimmediately on notification. - Routing
7000,8000, and9000errors into one retry loop. Under Using DCSA Standard Error Codes (used by DCSA standards released in 2024 and earlier, including Bill of Lading3.xper the DCSA API Design and Implementation Guidelines),7000–7999indicates technical syntax/integrity errors,8000–8999indicates functional business-rule errors, and9000–9999covers provider-documented codes. Send unrecoverable technical failures to a dead-letter queue for ERP integrations, and route8000-series errors plus mandatoryPENDING_UPDATEfeedback to the documentation desk. - Deferring conformance tests—or putting AI on legal write paths. Run the DCSA Conformance Framework against a synthetic counterpart early; certification applies to the exact full standard version, standard role, and module where applicable. Where teams use AI to draft SI payloads from shipper emails or summarize carrier
feedback, keep deterministic validation and human approval on every legal transition (APPROVED,AREQ,SREQ, and Booking amendments).
Before wiring eBL APIs into your forwarding ERP
Insonl is a Ho Chi Minh City engineering studio building custom ERP systems and operational AI workflows. Map your eBL handoffs, validation rules, and exception ownership before connecting carriers with our free AI workflow audit.
The audit is free; work after it is charged separately.
Sources
- Digital Container Shipping Association (DCSA, third-party): Electronic Bill of Lading standard, Bill of Lading Public Reference, Bill of Lading v3, Shipping Instructions Logical Data Model (2024.Q4), electronic Bill of Lading - Technical implementation guidelines, Implementing Booking and Bill of Lading - Technical guide, Booking and Bill of Lading Standards Adoption Guide, eBL Platform Interoperability, Implementing Digital Signatures for Transport Documents, Using DCSA Standard Error Codes, DCSA API Design and Implementation Guidelines, Conformance
- Insonl: ERP Systems, Free AI workflow audit, A Shipment Event Model for Freight Exception Alerts, How to Prevent ERP Double Posting When a Request Retries, Dead-Letter Queue for ERP Integrations: Recovery
