Implementing Booking and Bill of Lading - Technical guide

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

Reference Documentation

To get acquainted with the standards, refer to the introductory Booking standard page and Bill of Lading standard page.To understand the key concepts, user stories, use cases and data overview of the standard, refer to the respective documentation pages (Booking and Bill of Lading).For an implementation guide to the Booking (BKG) standard - please visit Implementing the DCSA Booking Standard. For an implementation guide to the Bill of Lading (EBL) standard - please visit Implementing the DCSA Bill of Lading Standard (SI+TD).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 and Bill of Lading model in version 2024.Q4 of the DCSA Information Model.

Transport Document data sources

Property values in the Transport Document (TD) comes from multiple places. They can come from Booking (BKG), from Shipping Instructions (SI), from both and lastly from the implementor (the carrier)
Booking only properties
In case a property is only provided in Booking (BKG), a booking amendment is needed in order to update the value. Examples of property values coming only from Booking (BKG) are:
  • receiptTypeAtOrigin and deliveryTypeAtDestination
  • cargoMovementTypeAtOrigin and cargoMovementTypeAtDestination
  • serviceContractReference and contractQuotationReference
  • declaredValue and declaredValueCurrency
  • Dangerous Goods
  • Reefer Settings
  • etc.
Shipping Instructions only properties
Other property values only come from the Shipping Instructions (SI). In order to update these values a Shipping Instructions update needs to be made. Examples of properties containing values which only from Shipping Instructions (SI) are:
  • numberOfCopiesWithCharges, numberOfCopiesWithoutCharges, numberOfOriginalsWithCharges and numberOfOriginalsWithoutCharges
  • isElectronic
  • isToOrder
  • numberOfRiderPages
  • displayedNameForPlaceOfReceipt, displayedNameForPortOfLoad, displayedNameForPortOfDischarge and displayedNameForPlaceOfDelivery
  • etc.
Properties that exist in both Booking and Shipping Instructions
Some properties values can be specified both in both Shipping Instructions (SI) and in Booking (BKG). If only provided in Booking (BKG) and not in Shipping Instructions (SI) the value is carried over from Booking into the Transport Document. If only provided in Shipping Instructions (SI) and not provided in Booking (BKG) then the value in the Transport Document is taken from the Shipping Instructions (SI). If the value has been provided both places, first provided in the Booking (BKG) and then in the Shipping Instructions (SI), then the value from the Shipping Instructions (SI) is used. Examples of properties containing values which can come from both Booking (BKG) and from Shipping Instructions (SI) are:
  • invoicePayableAt
  • Many of the parties involved: Shipper, Consignee, Notify Parties, etc
  • transportDocumentTypeCode
  • freightPaymentTermCode
  • placeOfBLIssue (from Booking) and placeOfIssue (from Shipping Instructions)
  • etc.
Properties that only exist on Transport Document
Lastly some values are only available in the Transport Document. These values are provided by the implementor (which often is the carrier). Examples of properties containing values which only exist in the Transport Document are:
  • shippedOnBoardDate, receivedForShipmentDate and displayedShippedOnBoardReceivedForShipment
  • termsAndConditions
  • charges
  • numberOfRiderPages
  • etc.
👉Important note: It is not possible to remove a value provided in Booking by setting the property to Null (or Omitting the value) in Shipping Instructions. If a property, that can be provided in both Booking and Shipping Instructions, is to be removed, then it is necessary to make a booking amendment, and remove it from the Booking.

Draft Transport Document amendments

As values in the Transport Document come from many different sources, there are different processes for updating the Shipper provided values. As described in a previous section (Transport Document data sources) please follow the process that corresponds with the properties that need to be modified.
Draft Transport Document amendments through Booking
If a Transport Document has been drafted (transportDocumentStaus=DRAFT) and a change needs to be done to a property that only exists in Booking (see Booking only properties section above), then the following process should be followed:
  • 👉 Note: This step is only required if it is a Carrier initiated amendment request - if it is a Shipper initiated amendment, this step can be skipped The Carrier should perform Booking UC6: Request to amend confirmed Booking. If the Shipper subscribes to Booking Notifications - this will notify the Shipper (if not - it is expected for the Shipper to periodically poll on the Booking GET-endPoint in order to retrieve any changes to a Booking).
  • As a Shipper perform Booking UC7: Request amendment to confirmed Booking and update the Booking with the changes needed. 👉 Important note: Any changes done to properties that are also included in the Shipping Instructions will not have any effect as the Shipping Instructions value will prevail.
  • The Carrier now performs Booking UC8: Process amendment to confirmed Booking and validates if the amendment can be fulfilled. If for some reason the Carrier does not allow the amendment - the process stops here for Shipper initiated amendments. (the Booking is still CONFIRMED and the Transport Document is still DRAFT) For Carrier initiated amendments, if the Carrier does not allow the amendment - the Carrier will still be waiting for a valid amendment (the Booking will continue to be in state PENDING_AMENDMENT). The Carrier will be waiting for the consumer to continue via previous step.
  • If the amendment is accepted during the previous step - the Booking is re-confirmed. This is done by carrier performing Booking UC5: Confirm Booking request. To all subscribers of Booking Notifications - a new Booking Notification with status CONFIRMED is sent. For consumers not subscribing to Booking Notifications, it is necessary to poll periodically on the Booking GET-endPoint and check if anything in the Booking payload has changed.
  • At the same time as the Booking is re-confirmed in the previous step, the Carrier re-publishes the Transport Document using Transport Document UC6: Publish Draft Transport Document. As part of the re-published draft Transport Document - the newly updated values from the confirmed Booking in the previous step are included. To all subscribers of Transport Document Notifications - a new Transport Document Notification with status DRAFTED is sent. For consumers not subscribing to Transport Document Notifications, it is necessary to poll periodically on the Transport Document GET-endPoint and check if anything in the Transport Document payload has changed.
Draft Transport Document amendments through Shipping Instructions
If a Transport Document has been drafted (transportDocumentStaus=DRAFT) and a change needs to be done to a property that exists in Shipping Instructions (see Shipping Instructions only properties and Properties that exist in both Booking and Shipping Instructions sections above), then the following process should be followed:
  • 👉 Note: This step is only required if it is a Carrier initiated update request - if it is a Shipper/Consignee/Endorsee initiated update, this step can be skipped The Carrier should perform Shipping Instructions UC2: Request to update Shipping Instructions. If the Shipper/Consignee/Endorsee subscribes to Shipping Instructions Notifications - this will notify the Shipper/Consignee/Endorsee (if not - it is expected for the Shipper/Consignee/Endorsee to periodically poll on the Shipping Instructions GET-endPoint in order to retrieve any changes to a Shipping Instructions).
  • As a Shipper/Consignee/Endorsee perform Shipping Instructions UC3: Submit updated Shipping Instructions and update the Shipping Instructions with the changes needed. 👉 Important note: It is not possible to remove values provided in Booking by omitting the value in the updated Shipping Instructions. A Booking amendment MUST be performed in order to remove the values from the Booking.
  • The Carrier now performs Shipping Instructions UC4: Process updated Shipping Instructions and validates if the update can be fulfilled. If for some reason the Carrier does not allow the update - the process stops here for Shipper/Consignee/Endorsee initiated updates. (the Shipping Instructions is still RECEIVED and the Transport Document is still DRAFT) For Carrier initiated updates, if the Carrier does not allow the update - the Carrier will still be waiting for a valid update (the Shipping Instructions will continue to be in state PENDING_UPDATE). The Carrier will be waiting for the consumer to continue via previous step.
  • If the update is accepted during the previous step - the updated Shipping Instructions becomes the received (or current) Shipping Instructions. If the Shipper/Consignee/Endorsee subscribes to Shipping Instructions Notifications - this will notify the Shipper/Consignee/Endorsee (if not - it is expected for the Shipper/Consignee/Endorsee to periodically poll on the Shipping Instructions GET-endPoint in order to retrieve any changes to a Shipping Instructions).
  • At the same time as the current Shipping Instructions is changed to to the updated Shipping Instructions in the previous step, the Carrier re-publishes the Transport Document using Transport Document UC6: Publish Draft Transport Document. As part of the re-published draft Transport Document - the newly updated values from Shipping Instructions in the previous step are included. To all subscribers of Transport Document Notifications - a new Transport Document Notification with status DRAFTED is sent. For consumers not subscribing to Transport Document Notifications, it is necessary to poll periodically on the Transport Document GET-endPoint and check if anything in the Transport Document payload has changed.
Draft Transport Document amendments through Booking and Shipping Instructions
If properties in the Transport Document that originates from both the Booking and the Shipping Instructions needs to be updated, the two updates described in the previous two sections should be followed. The standard does not specify which order this must happen in - it is up to each implementor to specify if there are any restrictions: Shipping Instructions updates can be done before Booking amendments, Booking amendments can be done before Shipping Instructions updates or the two can be done in parallel.If the Shipper is subscribed to Transport Document Notifications, a Transport Document Notification for each will be received (one Transport Document Notification for the Booking amendment and one Transport Document Notification for the Shipping Instructions update).
Booking amendments after a Shipping Instructions has been submitted and before a Transport Document is drafted
The standard does not specify any requirements for Booking amendments during Shipping Instructions submission. It is up to the implementor to specify what is allowed.

Frequently Asked Questions (FAQ)

  • Will the bookingStatus of the referred Booking (BKG) be validated upon receipt of the Shipping Instructions (SI) request? Yes. When linking a Shipping Instructions (SI) to a Booking (BKG), the bookingStatus of the carrierBookingReference used to link the two is validated. It is not possible to link to a non-existing Booking (BKG) or to a Booking (BKG) that is not confirmed (corresponding to booking states: CONFIRMED or PENDING_AMENDMENT).
  • Can the Shipping Instructions (SI) be accepted only if the bookingStatus of the corresponding Booking (BKG) is confirmed (corresponding to booking states: CONFIRMED or PENDING_AMENDMENT)? Yes, it is not possible to accept a Shipping Instructions (SI) that links to a Booking (BKG) that is not yet confirmed. If the Shipping Instructions (SI) refers to multiple bookings, all of them must be in state CONFIRMED.
  • What happens if a linked Booking (BKG) is cancelled (bookingStatus = CANCELLED)? Any Shipping Instructions (SI) linking to the Booking (BKG) would require an update, as no Shipping Instructions (SI) can link to an Cancelled Booking. This is also the case if a Shipping Instructions (SI) links to multiple bookings and one of the Bookings (BKG) are cancelled. The Shipping Instructions (SI) should change state to PENDING_UPDATE.
  • What about the case where bookingStatus is CONFIRMED and amendedBookingStatus is AMENDMENT_RECEIVED? The Shipping Instructions (SI) can still be accepted. The standard does not prevent requesting a Booking amendment after the Shipping Instructions (SI) has been submitted.
  • Should the Shipping Instructions (SI) maintain data consistency with the referred Booking (BKG)? In principle "yes", it is up to the carrier to specify how strict the consistency between the Shipping Instructions (SI) and Booking (BKG) should be.
👉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.