insonl
← journal

An Electronic Bill of Lading Integration Checklist for Forwarders

date
22 November 2026
by
Insonl
read
7 min read

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' with isElectronic=true) are not issued directly by carriers. In DCSA’s Shipping Instructions logical data model, BOL covers 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

  1. Treating HTTP 202 as committed state. In UC1, UC3, UC5, and UC7, the carrier validates synchronously and, if validation succeeds, replies 202 (Accepted) before async completion: UC1 has no SI state yet; UC3 and UC5 keep the prior SI state (RECEIVED or PENDING_UPDATE, and in UC5 the pending UPDATE_RECEIVED state); UC7 stays DRAFT. Polling differs by stage: GET /shipping-instructions/{documentReference} returns 202, 404, or 409 without content in UC1 before RECEIVED, whereas UC3 and UC5 can return 200 with the existing SI (or 202/409 mid-processing, with ?updatedContent=true to retrieve the updated SI), and UC7 checks status via GET /transport-documents/{transportDocumentReference} (200 or 202). Drive ERP transitions from POST /shipping-instructions-notifications or bounded polling, never from 202.
  2. 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 (many documentParties such as Shipper, Consignee, and Notify Parties, plus transportDocumentTypeCode and freightPaymentTermCode), and carrier-supplied TD-only fields (shippedOnBoardDate, charges, termsAndConditions). Setting a shared field to null or omitting it in SI cannot clear a Booking value—amend the Booking instead. A CANCELLED linked booking moves the SI to PENDING_UPDATE.
  3. Mishandling notification resends and VOIDED reference reuse. Carriers may resend POST /shipping-instructions-notifications with a new or reused id, and content or feedback may differ between deliveries—and between the root and nested document objects (e.g. INFO feedback in one place only). Protect writes using idempotent ERP posting on retries keyed on state and payload digest rather than dropping duplicate ids blindly. In UC11, when a carrier reuses transportDocumentReference, the notification time property alone distinguishes VOIDED from re-ISSUED, and once amended, GET /transport-documents/{transportDocumentReference} returns only the new TD—archive VOIDED immediately on notification.
  4. Routing 7000, 8000, and 9000 errors into one retry loop. Under Using DCSA Standard Error Codes (used by DCSA standards released in 2024 and earlier, including Bill of Lading 3.x per the DCSA API Design and Implementation Guidelines), 7000–7999 indicates technical syntax/integrity errors, 8000–8999 indicates functional business-rule errors, and 9000–9999 covers provider-documented codes. Send unrecoverable technical failures to a dead-letter queue for ERP integrations, and route 8000-series errors plus mandatory PENDING_UPDATE feedback to the documentation desk.
  5. 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