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

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 Booking can be changed to PENDING_UPDATE with the feedBacks object (which is part of the notification and the Booking) 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
2.0.4	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).
2.0.4	TBD 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 properties.	Support new customs requirement for 12-digit HS codes, applicable in Saudi Arabia, UAE and other GCC countries as of 2025.
2.0.4	TBD 2026	Added a new optional object departingVesselVoyage inside shipmentLocations.	Allow customers to specify complete routing details in their Booking request.
2.0.4	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.
2.0.4	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.
2.0.4	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.
2.0.4	TBD 2026	Added a new document party CSR (Carrier Customer Service Representative) in the Booking request.	Allow customers to specify the designated customer service representative on the carrier side.
2.0.3	14 November 2025	Added a new optional party Issue to Party in the Booking request.	Allows the customer to designate the intended Transport Document receiver in the Booking request so that they can access and manage their respective shipments after the booking is confirmed.
2.0.3	14 November 2025	Added new locationTypeCode ROU (Routing Reference) inside ShipmentLocations.	Allows to pass the schema validation for the mandatory ShipmentLocations in case the shipper provides the routingReference in the Booking request.
2.0.3	14 November 2025	Updated the 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.
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.