Implementing the DCSA Bill of Lading Issuance Standard Module

This is a guide to implementing the Issuance module of the DCSA Bill of Lading (eBL) standard version 3.0, written for the technical teams of DCSA adopting organizations.There are separate guides for implementing the SI and TD modules and for implementing the Surrender module of the standard.

Reference Documentation

To get acquainted with the standard, refer to the introductory Bill of Lading standard page.To understand the key concepts, user stories, use cases and data overview of the standard, refer to the Bill of Lading documentation page.For an overview of the business processes addressed by the standard, refer to the DCSA Industry Blueprint.To understand the data structures used by the standard and how they can be mapped to your own organization's data types, consult the Transport Document model in version 2024.Q4 of the DCSA Information Model.

Implementing the Standard

To get acquainted with the general principles applicable when implementing any DCSA standard, consult the DCSA API Design and Implementation Principles.To review the reference implementation of the Issuance module of the Bill of Lading standard, created by DCSA to verify the standard and used for measuring the conformance of adopter implementations, consult the Bill of Lading Issuance module of the DCSA conformance GitHub repository.To ensure that your organization becomes a successful adopter in the DCSA Bill of Lading standard API ecosystem, use the DCSA conformance framework periodically throughout your implementation project, to measure the conformance of your implementation and to improve it as needed.You can use a DCSA conformance sandbox as a counterpart in your development, since it allows you to easily test the most relevant scenarios that your application needs to support.👉Important note: While implementing the standard, run conformance periodically and use conformance scenarios and validations as a compass to guide the implementation. Don't wait until implementation has been finished to run the conformance scenarios.

Carrier Implementation

To request the issuance of eBL's through the Issuance module of the DCSA Bill of Lading standard API implementation of any eBL platform:

use your organization's technology stack to build a backend API client for the "/v3/ebl-issuance-requests" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization sends asynchronous issuance requests to the eBL platform.
use your organization's technology stack to implement the "/v3/ebl-issuance-responses" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization receives asynchronous responses from the eBL platform to previously sent issuance requests.

eBL Platform (Solution Provider) Implementation

To receive eBL issuance requests from any carriers through the Issuance module of the DCSA Bill of Lading standard API:

use your organization's technology stack to implement the "/v3/ebl-issuance-requests" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization receives asynchronous issuance requests from the carriers.
use your organization's technology stack to build a backend API client for the "/v3/ebl-issuance-responses" endpoint of the DCSA Bill of Lading Issuance OpenAPI specification page; this is the endpoint through which your organization sends asynchronous issuance responses to the carriers.

Implementing synchronous vs. asynchronous API responses

Synchronous and asynchronous eBL Issuance API responses are defined for different purposes and must be implemented accordingly:

Asynchronous regular responses (ISSU) and errors (BREQ / REFU), posted by the eBL Solution Provider using the "POST /v3/ebl-issuance-responses", are expected to be interpreted and routed programmatically by the Carrier system to their appropriate business process handlers, and to be manually processed if needed by the Carrier's business team.
Synchronous issuance responses must either acknowledge the receipt of the issuance request (204) or reject it as a duplicate (409). Any other synchronous error response (4xx / 5xx) is expected to be programmatically routed by the Carrier's system to their technical team for investigation.

👉Important note: When implementing eBL Issuance as an eBL Solution Provider, even if your system could send the BREQ or REFU issuance request rejections synchronously, it is essential not to do so, and to instead send them asynchronously using the dedicated "POST /v3/ebl-issuance-responses". Failure to do so will inadvertently trigger a technical support process on the Carrier side instead of the rejected issuance request business workflow.

Version overview

List of changes and the version they are released in

Version	Date of Publication	Change	Purpose of change
3.0.3	TBD 2026	Added an array of inner packagings inside the current inner packagings object.	Support additional levels of inner packagings to define Dangerous Goods cargo items more precisely. For example: 1 pallet (outer packaging), containing 1 box (1st level inner packaging), containing 50 cylinders (2nd level inner packaging).
3.0.3	TBD 2026	Added new fields: extendedHSCodes to support 12-digit HS codes. nationalCommodityCode.extendedValue to support 16-digit national commodity codes. Deprecated the existing HSCode and nationalCommodityCode.value properties.	Support new customs requirement for 12-digit HS codes, applicable in Saudi Arabia, UAE and other GCC countries as of 2025.
3.0.3	TBD 2026	Added a new optional field addressLines in the Address object.	Allow to capture unstructured address lines, used as a fallback when structured address fields are unavailable.
3.0.3	TBD 2026	Added a new extendedChargeName property with max length 100 and deprecated the existing chargeName which is limited to 50 characters.	Allow to provide full charge names, without the need to truncate it, improving clarity for carriers and end users.
3.0.3	TBD 2026	Added a new optional field facilityName in Location objects.	Allow parties to specify facilities which are not identified by an SMDG / BIC code.
3.0.2	14 November 2025	Added 2 optional Document parties in the Shipping Instructions and Transport Document (also included in the Issuance API): On Behalf of Shipper: The party allowed to act on behalf of the shipper for documentation purposes. On Behalf of Consignee: The party allowed to act on behalf of the consignee for documentation purposes.	Add support for scenarios where shippers/consignees contract third parties to handle the documentation process on their behalf (referred to as “On Behalf of” parties).
3.0.2	14 November 2025	Clarified the definition of “Issue to party”. Issue to party: The party that receives possession of the eBL upon issuance.	Remove ambiguity on the role of the Issue to party.
3.0.2	14 November 2025	Updated he definition of the latitude and longitude fields in the GeoCoordinate object: Latitude: Latitude expressed as decimal degrees using the ISO 6709 data interchange numeric format. Longitude: Longitude expressed as decimal degrees using the ISO 6709 data interchange numeric format.	The purpose of this change is to clarify how latitude and longitude values should be provided.
3.0.1	31 July 2025	No change	Align the API with eBL 3.0.1