Implementing Booking and Bill of Lading - Technical guide

This document provides technical guidance for implementing the DCSA Booking standard version 2.0 and the Bill of Lading standard version 3.0 in combination. It is intended for the technical teams of organizations adopting DCSA standards.

Reference Documentation

To get acquainted with the standards, start with the introductory Booking standard page and Bill of Lading standard page.To understand the key concepts, user stories, use cases and data overview, refer to the respective documentation pages for Booking and Bill of Lading.For implementation guidance, consult: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 organization's data types, see the Booking and Bill of Lading model in the DCSA Information Model, version 2024.Q4.

Transport Document data sources

Property values in the Transport Document (TD) can originate from multiple sources: Booking (BKG), Shipping Instructions (SI), and lastly the implementer (typically the carrier)
Booking-only properties
If a property is provided exclusively through the Booking, a booking amendment is required in order to update the value. Examples include:
  • receiptTypeAtOrigin and deliveryTypeAtDestination
  • cargoMovementTypeAtOrigin and cargoMovementTypeAtDestination
  • serviceContractReference and contractQuotationReference
  • declaredValue and declaredValueCurrency
  • Dangerous Goods
  • Reefer Settings
  • ShipmentLocations (which result in the Transports in the Transport Document)
  • etc.
Shipping Instructions-only properties
Certain properties are provided only through the Shipping Instructions. Updates must therefore be made via a Shipping Instructions update. Examples include:
  • numberOfCopiesWithCharges, numberOfCopiesWithoutCharges, numberOfOriginalsWithCharges and numberOfOriginalsWithoutCharges
  • isElectronic
  • isToOrder
  • numberOfRiderPages
  • displayedNameForPlaceOfReceipt, displayedNameForPortOfLoad, displayedNameForPortOfDischarge and displayedNameForPlaceOfDelivery
  • etc.
Properties available in both Booking and Shipping Instructions
Some properties may be specified in both Booking and Shipping Instructions. The following rules apply:
  • If only provided in Booking → The value is carried over from the Booking into the Transport Document.
  • If only provided in Shipping Instructions → The value is carried over from the Shipping Instructions into the Transport Document.
  • If the value has is provided in both places (first provided in the Booking, and then in the Shipping Instructions) → The value from the Shipping Instructions takes precedence.
Examples include:
  • invoicePayableAt
  • Many of the documentParties: Shipper, Consignee, Notify Parties, etc
  • transportDocumentTypeCode
  • freightPaymentTermCode
  • placeOfBLIssue (from Booking) and placeOfIssue (from Shipping Instructions)
  • etc.
Transport Document-only properties
Lastly some exist solely in the Transport Document and supplied by the implementer (typically the carrier). Examples include:
  • 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 it) in the Shipping Instructions. If a property that exists in both Booking and Shipping Instructions needs to be removed, it is necessary to make a booking amendment, and remove it from the Booking.

Draft Transport Document amendments

Because values in the Transport Document originate from multiple sources, different processes apply when updating the Shipper provided values. As described in the previous section (Transport Document data sources), please follow the process corresponding to the properties you need to modify.
Draft Transport Document amendments through Booking
If a Transport Document has been drafted (transportDocumentStaus=DRAFT) and a change is required to a property that exists only in Booking (see Booking only properties section above), the following process applies:● Carrier initiated amendment requests● Shipper initiated amendment requests👉 Important: If the same property also exists in the Shipping Instructions, any changes in Booking will not take effect, as values in the Shipping Instructions take precedence.● Carrier validation     • For Shipper initiated amendments the process stops here (the Booking remains in state CONFIRMED and the Transport Document remains in DRAFT).     • For Carrier initiated amendments the Booking remains in state PENDING_AMENDMENT until a valid amendment is received from the customer.
  • If the amendment IS accepted:
     • The Carrier re-confirms the Booking via Booking UC5: Confirm Booking request.     • Subscribers to Booking notifications receive a new Booking notification with state CONFIRMED. Consumers not subscribed to Booking notifications, need to periodically poll the Booking GET-endPoint to check for updates.
● Re-publication of Draft Transport Document
  • At the same time as the Booking is re-confirmed in the previous step, the Carrier re-publishes the Transport Document via Transport Document UC6: Publish Draft Transport Document, including the updated values from the re-confirmed Booking.
  • Subscribers to Transport Document notifications receive a new Transport Document notification with state DRAFTED. Consumers not subscribed to Transport Document notifications, need to periodically poll the Transport Document GET-endPoint to check for updates.
Draft Transport Document amendments through Shipping Instructions
If a Transport Document has been drafted (transportDocumentStaus=DRAFT) and a change is required to a property that exists in Shipping Instructions (see Shipping Instructions only properties and Properties available in both Booking and Shipping Instructions sections above), the following process applies:
● Carrier initiated amendment requests
● Shipper/Consignee/Endorsee initiated amendment requests
👉 Important: It is not possible to remove a value provided in Booking by setting the property to Null (or omitting it) in the updated Shipping Instructions. If a property that exists in both Booking and Shipping Instructions needs to be removed, it is necessary to make a booking amendment, and remove it from the Booking.
● Carrier validation
     • For Shipper/Consignee/Endorsee initiated amendments the process stops here (the Shipping Instructions remains in state RECEIVED and the Transport Document remains in state DRAFT).     • For Carrier initiated amendments the Shipping Instructions remain in state PENDING_UPDATE until a valid amendment is received from the consumer.
  • If the amendment IS accepted:
     • The Carrier replaces the current version of the Shipping Instructions with the updated version.     • Subscribes to Shipping Instructions notifications receive a new Shipping Instructions notification with state RECEIVED. Consumers not subscribed to Shipping Instructions notifications, need to periodically poll the Shipping Instructions GET-endPoint to check for updates.
● Re-publication of Draft Transport Document
  • At the same time as the current Shipping Instructions is replaced with the updated version, the Carrier re-publishes the draft Transport Document via Transport Document UC6: Publish Draft Transport Document, including the updated values from the revised Shipping Instructions.
  • Subscribers to Transport Document notifications receive a new Transport Document notification with state DRAFT. Consumers not subscribed to Transport Document notifications, need to periodically poll on the Transport Document GET-endPoint to check for updates.
Draft Transport Document amendments through Booking and Shipping Instructions
If a change is required to a Transport Document that exists in both Booking and Shipping Instructions, both processes described above must be followed.The standard does not prescribe a specific order, updates may be made sequentially or in parallel. It is at the discretion of the implementer to specify if there are any restrictions. For example: 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 will be received for each process (one Transport Document notification for the Booking amendment and one Transport Document notification for the Shipping Instructions update).The standard does not define requirements for Booking amendments submitted while Shipping Instructions are in progress (before Transport Document is drafted). It is at the discretion of the implementrr to define what is allowed.

Frequently Asked Questions (FAQ)

Will the bookingStatus of the referred Booking be validated upon receipt of the Shipping Instructions request?
➤ Yes. When linking a Shipping Instructions to a Booking, the bookingStatus of the carrierBookingReference used to link the two is validated.
Can the Shipping Instructions be accepted if the bookingStatus of the linked Booking(s) is NOT confirmed?
➤ No. It is not possible to link to a non-existing Booking or to a Booking that has not been confirmed yet. If the Shipping Instructions refers to multiple bookings, all of them must be confirmed (corresponding to booking states: CONFIRMED or PENDING:AMENDMENT).
What happens if a linked Booking is cancelled (bookingStatus = CANCELLED)?
➤ Any Shipping Instructions linking to the Booking would require an update, as they cannot link to a cancelled Booking. This is also the case if a Shipping Instructions links to multiple bookings and one them is cancelled. The Shipping Instructions should change state to PENDING_UPDATE.
What if the bookingStatus is CONFIRMED and the amendedBookingStatus is AMENDMENT_RECEIVED?
➤ The Shipping Instructions can still be accepted. The standard does not prohibit requesting a Booking amendment after the Shipping Instructions has been submitted.
Should the Shipping Instructions maintain data consistency with the referred Booking ?
➤ Generally, yes. The carrier should specify the required level of consistency between the Shipping Instructions and the Booking. Sometimes it is important that values for: isShipperOwned, Container Type/Size, Container units, isNonOperatingReefer, etc match between the two standards. This should be specified by the implementer.👉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 is complete to beginconformance validation.