Implementing the DCSA Booking Standard

This is a guide to implementing the DCSA Booking (BKG) standard version 2.0, written for the technical teams of DCSA adopting organizations.

Reference Documentation

To get acquainted with the standard, refer to the introductory Booking standard page.To understand the key concepts, user stories, use cases and data overview of the standard, refer to the Booking 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 Booking 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 Booking standard, created by DCSA to verify the standard and used for measuring the conformance of adopter implementations, consult the Booking 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 Booking Technical Implementation Guidelines.

Carrier Implementation

To implement the Booking standard API as a carrier, use your organization's technology stack to implement each of the "/v2/bookings" endpoints of the DCSA Booking OpenAPI specification page.

Carrier To-Do list

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

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 Booking (BKG) lifecycle the carrierBookingReference and carrierBookingRequestReference are valid. Some carriers do not allow the use of carrierBookingReference before a Booking has been confirmed (provided it is available).
Specify if Dangerous Goods (DG) and Reefer is supported

Shipper Implementation

To create and manage bookings through the DCSA Booking standard API implementation of any carrier, use your organization's technology stack to build a backend API client application using the DCSA Booking 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 Booking standard API.To optionally receive notifications through the DCSA Booking API Notifications endpoint about bookings made by your organization with a carrier who offers notifications support, use your organization's technology stack to implement the "/v2/booking-notifications" endpoints of the DCSA Booking OpenAPI specification page and use the carrier's proprietary process to register your endpoint.

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.

Version overview

List of changes and the version they are released in

Version	Date of Publication	Change	Purpose of change
2.0.2	31 July 2025	Added a new optional property Full container pickup dateTime in the Booking request.	This allows the customer to indicate date and time when the loaded container(s) need to be picked up from the Place of Receipt, if provided. It may apply to any receipt type at origin. Example scenario for SD (Store Door) receipt type at origin: The carrier can bring the empty containers to the Door location designated by the customer and return to pick them up once they have been loaded at the date and time specified by the customer in the booking request.
2.0.2	31 July 2025	Added two new optional properties Requested pre-carriage mode of transport and Requested on-carriage mode of transport in the Booking request.	This allows the customer to define their preferred mode of transport from Place of Receipt to Port of Loading and from Port of Discharge to Place of Delivery as part of their booking request.
2.0.2	31 July 2025	Added three new mode of transport values in the Booking request and confirmation: RAIL_TRUCK BARGE_TRUCK BARGE_RAIL	This allows the customer to specify which type of multimodal transport they wish to book. The carrier can return the same information in the booking confirmation.
2.0.2	31 July 2025	Added two new optional properties in the Booking request: Transport Document References (array) Requested number of Transport Documents Added two new optional properties in the Booking confirmation: Transport Document References (array) Requested number of Transport Documents	Transport Document References allows the customer to provide a list of Transport Document References to be associated with the booking. The carrier will mirror it back in the booking confirmation. Requested number of Transport Documents allows the customer to indicate how many Transport Documents should be associated with the booking. The carrier will mirror it back in the booking confirmation. This is relevant when the customer has previously received from the carrier a list of Transport Document References that they can choose from.
2.0.2	31 July 2025	Added a new optional object Origin empty container pickup (including location and dateTime) in the Booking confirmation.	This allows the carrier to indicate the date, time and location of the depot from which the empty container(s) will be released from, irrespective of the receipt type at origin (CY, SD, CFS). Note: The standard currently only allows to provide this information for CY (Container Yard) shipments.
2.0.2	31 July 2025	Added a new optional property in the booking request to define the ETD from Place of Receipt (Expected Departure from Place of Receipt Date). Updated the definition of Expected Departure Date in the booking request to explicitly define it as referring solely to the ETD from the Port of Loading. Updated the condition to mandate that the shipper must supply at least ETD from POL or from Place of Receipt or both when the range of Expected Arrival Date at Place of Delivery or vessel/voyage/service details are not provided.	This ensure a consistent and unambiguous interpretation of the Expected Departure Date across all parties (customers and carriers) and provides more flexibility for customers to provide their preferred sailing as part of the booking request.
2.0.2	31 July 2025	Removed the constraint that a Carrier Booking Request Reference (CBRR) can only be used to retrieve a booking before it is confirmed, and that a Carrier Booking Reference (CBR) can only be used after confirmation.	This allows flexibility for the shipper to retrieve a Booking using either the CBRR or CBR, irrespective of whether the Booking has already been confirmed. Previously, unless the shipper implemented Booking notifications, the CBR was unknown making impossible for a shipper to retrieve a confirmed Booking.
2.0.2	31 July 2025	Updated definition of Party contact details	This removes ambiguity on which party it refers to.
2.0.2	31 July 2025	Added 4 new eBL Solution Providers: COVA (Covantis) ETIT (e-title) KTNE (KTNET) CRED (Credore)	This allows to use the DCSA Booking standard with all the eBL Solution Providers approved by IGP&I up to July 28, 2025.
2.0.1	25 April 2025	Added a new optional property routingReference (Routing Reference) in the Booking request.	This allows customers who integrate with the DCSA Booking API and Commercial Schedules API (point-to-point) to place a booking request with a specific routing previously fetched from Commercial Schedules, so that the booking will be created with the exact routing they need, without spending extra time re-keying information (such as vessel and service name) or on booking amendments due to routing discrepancies. The same optional property has been added to the point-to-point API response endpoint of the Commercial Schedules API.
2.0.1	25 April 2025	Added a new party function NAC (Named Account Customer) in the Document Parties in the Booking request and confirmation.	This allows the carrier to process the booking correctly, matching space against the specific NAC allocation and applying the correct rate from the pricing system, avoiding rate disputes and amendments. Example: Assume a freight forwarder has a contract with special rates and weekly allocation for 3 different customers (NACs). When they submit the booking request to the carrier they should provide the service contract reference and specify which of the 3 NACs they are booking for so that the carrier can apply the correct rate and space allocation.