Implementing the DCSA Bill of Lading Surrender Standard Module

This is a guide to implementing the Surrender 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 Issuance module and for implementing the SI and TD modules 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 Surrender 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 Surrender 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.

Carrier Implementation

To receive eBL surrender requests from any eBL platforms through the Surrender module of the DCSA Bill of Lading standard API:

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

eBL Platform Implementation

To request the surrender of eBL's through the Surrender module of the DCSA Bill of Lading standard API implementation of any carrier:

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

👉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.

Version overview

List of changes and the version they are released in

Version	Date of Publication	Change	Purpose of change
3.0.2	14 November 2025	Added an optional “Represented party” inside “Actor” and “Recipient” in the Endorsement Chain (Surrender Request): representedParty (actor): The party on whose behalf the action was performed. representedParty (recipient): The party on whose behalf the action was directed.	Provide visibility in the endorsement chain on both the party performing / receiving an action and the represented party on whose behalf the action is taken / received.
3.0.2	14 November 2025	Added two new reason codes in the Surrender Request (for amendment): COD (Change of Destination) SWI (Switch BL)	Allow the eBL Solution Provider to indicate the reason for requesting a surrender for amendment. Allow the carrier to distinguish between specific types of surrender for amendment requests so that they can programmatically trigger the relevant process.
3.0.2	14 November 2025	Glossary update: Updated definitions of action codes ISSUE and SIGN in the Endorsement Chain (Surrender Request): ISSUE: The actor issued the document to the recipient, who is the first possessor of the eBL, as designated by the Issue to Party. SIGN: The actor signed the eBL while it was in the actor’s possession.	Remove ambiguity and ensure consistency with the other updates – Issue to Party and additional action codes.
3.0.2	14 November 2025	Glossary update: Updated definitions of action codes SURRENDER_FOR_DELIVERY and SURRENDER_FOR_AMENDMENT in the Endorsement Chain (Surrender Request): SURRENDER_FOR_DELIVERY: The actor requested to surrender the eBL to the recipient for delivery. SURRENDER_FOR_AMENDMENT: The actor requested to surrender the eBL to the recipient for amendment.	Ensure consistency with the other action codes definitions.
3.0.2	14 November 2025	Added a new value (NONE) in the “eBL Platform” and “Code List Provider” attributes to be used with the meaning of “No party” in the existing mandatory attributes of the Recipient in the Endorsement Chain (Surrender Request) when the following action codes are used: SIGN BLANK ENDORSE SURRENDERED	Enable schema validation by providing a value for the Recipient, even for action codes where it is not applicable (as the Recipient is currently a mandatory object and must contain a value).
3.0.2	14 November 2025	Added new Endorsement Chain action codes: BLANK ENDORSE: The actor endorsed the document in blank. ENDORSE TO ORDER: The actor endorsed the document to order of the recipient, allowing the recipient to further endorse the eBL to another party. TRANSFER: The actor transferred the possession of the eBL to the recipient. SURRENDERED: The actor acknowledged that the eBL has been accepted and the lifecycle of the eBL is accomplished.	Provide clarity and transparency on the actions performed by the parties on the eBL. Allow consumers (carrier/customer) to easily identify the action when checking the endorsement chain information.
3.0.2	14 November 2025	Added an optional attribute Audit reference (string with length = 100 characters) in the Endorsement Chain Link defined as: “An identifier issued by the eBL Solution Provider, used for auditing purposes to verify that the endorsement chain action has been securely recorded. The format of this identifier may vary depending on the technology employed by the eBL Solution Provider.”	Provide a verifiable reference for audit purposes within the eBL Solution Provider’s system.
3.0.1	31 July 2025	No change	Align the API with eBL 3.0.1