Implementing the DCSA Bill of Lading Standard (SI+TD)

This is a guide to implementing the Shipping Instructions (SI) and Transport Document (TD) modules 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 Issuance module 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 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 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.For a more in-depth technical specification of the standard (including how to use the Feedback object) please read eBL Technical Implementation Guidelines.

Carrier Implementation

To implement the Shipping Instructions (SI) and Transport Document (TD) modules of the Bill of Lading standard API as a carrier, use your organization's technology stack to implement each of the "/v3/shipping-instructions" and "/v3/transport-documents" endpoints of the DCSA Bill of Lading OpenAPI specification page.

Carrier To-Do list

Here is are some examples of what could be documented as part of a Carrier implementation:

The DCSA Bill of Lading (EBL) and Booking (BKG) model allows a many-to-many relation between Booking (BKG) and Shipping Instructions (SI). If your system only allows a one-to-many a many-to-one or event a one-to-one relation between the two please remember to document this
Remember to document any properties or objects that are not supported by your system. This should be done on the API and in the Feedback object returned as part of any response. As part of the Feedback object: if properties are echoed back (in a GET request) but not supported further downstream - please document this as a PROPERTY_WILL_BE_IGNORED code. If properties are removed/deleted automatically (because your system cannot store them) - please document this as a PROPERTY_HAS_BEEN_DELETED code.
Document if Notifications are supported and how to subscribe to them
Document at which points during the Shipping Instructions (SI) and Transport Document (TD) lifecycle the shippingInstructionsReference and transportDocumentReference are valid. Some carriers do not allow the use of shippingInstructionsReference after a Transport Document has been drafted.
Specify if Dangerous Goods (DG) and Reefer is supported

Shipper Implementation

To create and manage Shipping Instructions or to amend Transport Documents through the DCSA Bill of Lading standard API implementation of any carrier, use your organization's technology stack to build a backend API client application using the DCSA Bill of Lading OpenAPI specification page.As an alternative, you can also use directly the corresponding API specification page of one of the carriers with which you need to create and manage bookings through the DCSA Bill of Lading standard API.To optionally receive notifications through the DCSA Bill of Lading API SI / TD Notifications endpoints about the Shipping Instructions or Transport Documents of your organization from a carrier who offers notifications support, use your organization's technology stack to implement the "/v3/shipping-instructions-notifications" and "/v3/transport-document-notifications" endpoints of the DCSA Bill of Lading OpenAPI specification page and use the carrier's proprietary process to register your endpoints.

Booking and Bill of Lading

For a technical guide to implementing Booking and Bill of Lading together please visit: Implementing Booking and Bill of Lading.👉Important note: While implementing the standard, run conformance periodically and use the Conformance Tool as a compass to guide the implementation. Don't wait until implementation has been finished and then run Conformance.

FAQ

How does the ZZZ code work in the codeListProvider property in the IdentifyingCode object?

ZZZ is a mutually agreed value between the consumer and the provider. It is a value that is only valid between two specific parties and not known to the eco-system.An example of this could be a carrier and a shipper who mutually agrees that the value Shipper123 is the internal identifier for the shipper in the carrier system. Whenever the shipper wants to identify itself as a party the following IdentifyingCode object could be sent:"identifyingCodes": [ { "codeListProvider": "ZZZ", "partyCode": "Shipper123"} ]Since both parties have agreed on the code Shipper123 - it can be used when the Shipper makes a request.The shipper cannot by default use the same code (Shipper123) with another carrier - as it might reference to another shipper or not be valid.

How should errors be treated when found in a request?

If a request is made that is not schema valid - a 404 Bad Request should be returned with an error object.In case the payload is schema valid and an error has been encountered two things can happen:

A 404 Bad request can be returned. As part of the error object it would be good practice to notify the consumer of what the problem is.
A successful response can be returned (200 or 202 depending on the endPoint). After the successful response the state of the Shipping Instructions can be changed to PENDING_UPDATE with the feedBacks object (which is part of the notification and the Shipping Instructions) containing information of what the problem is.

Version overview

List of changes and the version they are released in

Version	Date of Publication	Change	Purpose of change
3.0.3	13 April 2026	Added two new attributes to the Shipping Instructions to support customs filing requirements: descriptionOfGoodsForCustoms shippingMarksForCustoms	Ensure alignment with the new EDI feature implemented for the ICS2 requirements, allowing shippers to provide customs-specific cargo description and marks & numbers.
3.0.3	13 April 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	13 April 2026	Added new fields: extendedHSCodes to support 12-digit HS codes. extendedNationalCommodityCode 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	13 April 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	13 April 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	13 April 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.3	13 April 2026	Added 3 new endpoints to support direct Transport Document amendments: GET / PUT / DELETE. Added 2 new properties to Transport Document notifications: amendedTransportDocumentStatus amendedTransportDocument	Allow carriers to process Transport Document amendments without requiring changes to the Booking or Shipping Instructions. This provides an alternative to the original approach, where amendments are requested indirectly by submitting updated Shipping Instructions and/or a Booking amendment. Carriers may choose to support the original (indirect) amendment process, the new direct amendment process, or both, depending on their internal processes and system capabilities.
3.0.3	13 April 2026	Added 2 new use cases to cancel Shipping Instructions after submission: UC15: Cancel Shipping Instructions (by shipper) UC16: Decline Shipping Instructions by carrier The following Shipping Instructions statuses have been added: CANCELLED, DECLINED.	Allow carriers and customers to cancel Shipping Instructions after they have been submitted.
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 original Bill of Lading upon issuance.	Remove ambiguity on the role of the Issue to party.
3.0.2	14 November 2025	Added Transport Document Sub-reference as an optional attribute in the Shipping Instructions and Transport Document lightweight notifications.	Allow the receiver of a Shipping Instructions lightweight notification to know which “version” of the Transport Document it affects. Allow the receiver of a Transport Document lightweight notification to distinguish between the notification referring to the surrendered Transport Document (VOIDED) and the amended Transport Document (ISSUED).
3.0.2	14 November 2025	Added the Feedback object to the Transport Document object.	Ensure customers can access Transport Document feedback information upon request, regardless of whether they have implemented notifications.
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	Added a new optional property Shipping Instructions requestor in the Shipping Instructions.	This allows customers to provide the details of the agent/third party who submitted the Shipping Instructions on behalf of the shipper to the carrier, so that the carrier can contact them in case any clarifications or corrections are needed.
3.0.1	31 July 2025	Added a new optional property Transport Document Reference in the Shipping Instructions.	This allows customers to indicate which Transport Document Reference should be linked with this Shipping Instructions. This is relevant when the customer has previously received from the carrier a list of Transport Document References that they can choose from.
3.0.1	31 July 2025	Added 2 new optional properties in SI: Carrier Code and Carrier Code List Provider.	This allows a service provider receiving the Shipping Instructions from their customers to know to which carrier the Shipping Instructions should be routed to.
3.0.1	31 July 2025	Removed upper limit on number of lines for Displayed address	This allows the carrier to customize the address printed on paper BLs, based on the number of lines supported by their system.
3.0.1	31 July 2025	Updated definition of Party contact details.	This removes ambiguity on which party it refers to.
3.0.1	31 July 2025	Added 4 new eBL Solution Providers: COVA (Covantis) ETIT (e-title) KTNE (KTNET) CRED (Credore)	This allows to use the DCSA Bill of Lading standard with all the eBL Solution Providers approved by IGP&I up to July 28, 2025.