This is a technical implementation guide to the DCSA Booking (BKG) standard version 2.0. The audience of this document is technical teams of DCSA adopting organizations.

Table of Contents

Use Case 1: Submit Booking request

Use Case 2: Use Case 2: Request to update Booking request

Use Case 3: Use Case 3: Submit updated Booking request

Use Case 4: Reject Booking request

Use Case 5: Confirm Booking request

Use Case 6: Request to amend confirmed Booking

Use Case 7: Request amendment to confirmed Booking

Use Case 8: Process amendment to confirmed Booking

Use Case 9: Cancel amendment to confirmed Booking

Use Case 10: Decline Booking by Carrier

Use Case 11: Cancel Booking request by Shipper

Use Case 12: Confirm Booking completed

Use Case 13: Cancel confirmed Booking by Shipper

Use Case 14: Process Booking cancellation

Use Case 1: Submit Booking request

Synchronous Carrier Processing

• The shipper sends a POST request to create a booking.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the booking it can subsequently return it as a valid GET response.
• The Carrier MAY also perform other validations or processing synchronously, optionally resulting in the collection of feedback.
• If validations succeed, the Carrier responds with a 202 (Accepted) containing only the carrierBookingRequestReference.
• The booking does not yet contain a state

GET Booking (before booking is in state RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 202 (Accepted) / 404 (Not Found) / 409 (Conflict) without content.

GET Booking Amendment (before booking is in state RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Asynchronous Carrier Processing

• The Carrier continues validating and processing the booking, optionally collecting additional feedback.
• The Carrier sets the booking state to RECEIVED.
• The Carrier sends a notification to the Shipper
  • If feedback was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification. A different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • If feedback was collected, it is included in the feedbacks property in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Back to Table of Content ⬆️

Footnotes

1. bookingReference can be either: carrierBookingRequestReference in case the booking is not yet Confirmed or carrierBookingReference in case the booking has been Confirmed. ↩ ↩² ↩³ ↩⁴

Use Case 2: Request to update Booking request

• The Carrier changes the booking state to PENDING_UPDATE.
• The Carrier sends a notification to the Shipper.
  • There MUST be feedback, it is included in the notification root.
  • If a full notification is sent, the booking (booking property) is included, MUST also contain feedback.
  • There MAY be differences between the feedback in the root and within the booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• If the Carrier performs Use Case 2 again or resends the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state PENDING_UPDATE)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The mandatory feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state PENDING_UPDATE)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Back to Table of Content ⬆️

Footnotes

1. bookingReference can be either: carrierBookingRequestReference in case the booking is not yet Confirmed or carrierBookingReference in case the booking has been Confirmed. ↩ ↩²

Use Case 3: Submit updated Booking request

Synchronous Carrier Processing

• The Shipper sends a PUT request to update a booking.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the booking it can subsequently return it as a valid GET response.
• The Carrier MAY also perform other validations or processing synchronously, optionally resulting in the collection of feedback.
• If validations succeed, the Carrier responds with an empty 202 (Accepted).
  • A 404 (Not Found) is returned if the carrierBookingRequestReference is not known.
  • A 409 (Conflict) is returned if the Carrier is processing a booking request.
• Booking state is unchanged (it is still in RECEIVED or PENDING_UPDATE).

GET Booking (booking is in state RECEIVED and before it is in UPDATE_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
  • Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking (booking is in state PENDING_UPDATE and before it is in UPDATE_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The mandatory feedback is included in the booking.
  • Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (booking is in state RECEIVED or Calling GET /bookings/{bookingReference}?amendedContent=true ¹

PENDING_UPDATE and before it is in UPDATE_RECEIVED)

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Asynchronous Carrier Processing

• The Carrier changes the booking state to UPDATE_RECEIVED.
• The Carrier sends a notification to the Shipper.
  • If feedback was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state UPDATE_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state UPDATE_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Back to Table of Content ⬆️

Footnotes

1. bookingReference can be either: carrierBookingRequestReference in case the booking is not yet Confirmed or carrierBookingReference in case the booking has been Confirmed. ↩ ↩² ↩³ ↩⁴ ↩⁵

Use Case 4: Reject Booking request

• The Carrier changes the booking state to REJECTED.
• The Carrier sends a notification to the Shipper.
  • If feedback was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state REJECTED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state REJECTED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Back to Table of Content ⬆️

Footnotes

1. bookingReference can be either: carrierBookingRequestReference in case the booking is not yet Confirmed or carrierBookingReference in case the booking has been Confirmed. ↩ ↩²

Use Case 5: Confirm Booking request

• The Carrier changes the booking state to CONFIRMED.
• If it is a **re-**confirmation (the booking state is already CONFIRMED) the Carrier clears:
  • the amendedBooking state
  • the bookingCancellation state.
• The Carrier sends a notification to the Shipper.
  • If feedback was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing feedback
  • If the booking is **re-**confirmed and a full notification is sent, the amendment (amendedBooking property) is cleared
  • There MAY be differences between the feedback in the root and within the booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• If the Carrier performs Use Case 5 again or resends the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.
  • If the booking is **re-**confirmed and a full notification is sent, the amendment (amendedBooking property) is cleared

GET Booking (after booking is in state CONFIRMED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state CONFIRMED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
  • If the booking was re-confirmed the Carrier responds with a 404 (Not Found)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩²

Use Case 6: Request to amend confirmed Booking

• The Carrier changes the booking state to PENDING_AMENDMENT.
• The Carrier clears the amendedBooking state.
• The Carrier clears the bookingCancellation state.
• The Carrier sends a notification to the Shipper.
  • There MUST be feedback, it is included in the notification root.
  • If a full notification is sent, the booking (booking property) is included, it MUST contain feedback.
  • If a full notification is sent, the amendment (amendedBooking property) is cleared.
  • There MAY be differences between the feedback in the root and within the booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• If the Carrier performs Use Case 6 again or resends the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state PENDING_AMENDMENT)

Calling `GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The mandatory feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state PENDING_AMENDMENT)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as a possible amendment has been cleared.

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩²

Use Case 7: Request amendment to confirmed Booking

Asynchronous Carrier Processing

• The booking state stays unchanged (CONFIRMED or PENDING_AMENDMENT).
• The Carrier changes the amended booking state to AMENDMENT_RECEIVED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the amendment was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the amended booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after amended booking is in state AMENDMENT_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the confirmed booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after amended booking is in state AMENDMENT_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the amended booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩²

Use Case 8: Process amendment to confirmed Booking

Confirm Amendment

• The Carrier changes the booking state to CONFIRMED.
• The Carrier changes the amended booking state to AMENDMENT_CONFIRMED.
• The amendment now becomes the confirmed booking (the booking property and the amendedBooking property now contain the same value).
• The Carrier sends a notification to the Shipper.
  • If feedback for the confirmed booking was collected, it is included in the notification root
  • If a full notification is sent, the newly confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after amended booking is in state AMENDMENT_CONFIRMED)

Calling `GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after amended booking is in state AMENDMENT_CONFIRMED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Decline Amendment

• The booking state stays unchanged (CONFIRMED or PENDING_AMENDMENT).
• The Carrier changes the amended booking state to AMENDMENT_DECLINED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the confirmed booking was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after amended booking is in state AMENDMENT_DECLINED)

Calling `GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after amended booking is in state AMENDMENT_DECLINED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩² ↩³ ↩⁴

Use Case 9: Cancel amendment to confirmed Booking

Synchronous Carrier Processing

• The Shipper sends a PATCH request to cancel a booking amendment.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the cancellation it can subsequently process it.
• The Carrier MAY also perform other validations or processing synchronously, optionally resulting in the collection of feedback.
• If validations succeed, the Carrier responds with an empty 202 (Accepted).
  • A 404 (Not Found) is returned if the carrierBookingReference is not known.
  • A 409 (Conflict) is returned if the Carrier is processing a booking request.
• Booking state is unchanged (it is still in CONFIRMED or PENDING_AMENDMENT).
• The amendment state is unchanged (it is still in AMENDMENT_RECEIVED).

GET Booking (booking is in state CONFIRMED or PENDING_AMENDMENT and before it is in AMENDMENT_CANCELLED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (booking is in state CONFIRMED or PENDING_AMENDMENT and before it is in AMENDMENT_CANCELLED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Asynchronous Carrier Processing Accepting the Cancellation

• The booking state stays unchanged (CONFIRMED or PENDING_AMENDMENT).
• The Carrier changes the amended booking state to AMENDMENT_CANCELLED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the amendment was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the amended booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after amended booking is in state AMENDMENT_CANCELLED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after amended booking is in state AMENDMENT_CANCELLED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Asynchronous Carrier Processing Decline the Cancellation

• The booking state stays unchanged (CONFIRMED or PENDING_AMENDMENT).
• The amended booking stays unchanged AMENDMENT_RECEIVED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the amendment was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the amended booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after amended cancellation is declined and amended booking is in state AMENDMENT_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after amended cancellation is declined and amended booking is in state AMENDMENT_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶

Use Case 10: Decline Booking by Carrier

• The Carrier changes the booking state to DECLINED.
• The Carrier changes the amended booking state to AMENDMENT_DECLINED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the declined booking was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state DECLINED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state `DECLINED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).
• If the confirmed booking is a result of a re-confirmation or an amendment was never requested - then the Carrier responds with 404 (Not Found) as there is no amendment (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩²

Use Case 11: Cancel Booking request by Shipper

Asynchronous Carrier Processing Accepting Cancellation

• The Carrier changes the booking state to (CANCELLED).
• The Carrier sends a notification to the Shipper.
  • If feedback for the cancelled booking was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing optional feedback (if the confirmed booking is in state PENDING_UPDATE - the feedback is mandatory)
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (booking is in state CANCELLED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (booking is in state CANCELLED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Asynchronous Carrier Processing Declining Cancellation

• The booking state stays unchanged (RECEIVED, PENDING_UPDATE or UPDATE_RECEIVED).
• The Carrier sends a notification to the Shipper.
  • If feedback for the declined cancellation was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing optional feedback (if the confirmed booking is in state PENDING_UPDATE - the feedback is mandatory)
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (booking is in state RECEIVED, PENDING_UPDATE or UPDATE_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_UPDATE - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (booking is in state RECEIVED, PENDING_UPDATE or UPDATE_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 404 (Not Found) as no amendment exists before the booking is confirmed.

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩² ↩³ ↩⁴

Use Case 12: Confirm Booking completed

• The Carrier changes the booking state to COMPLETED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the completed booking was collected, it is included in the notification root
  • If a full notification is sent, the booking (booking property) is included, also containing optional feedback connected to the confirmed booking
  • If a full notification is sent, the amendment (amendedBooking property) is included, also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking is in state COMPLETED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the completed booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the completed booking
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking is in state COMPLETED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).
• If the completed booking is a result of a re-confirmation or an amendment was never requested - then the Carrier responds with 404 (Not Found) as there is no amendment (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩²

Use Case 13: Cancel confirmed Booking by Shipper

Synchronous Carrier Processing

• The Shipper sends a PATCH request to cancel a confirmed booking.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the cancellation it can subsequently process it.
• The Carrier MAY also perform other validations or processing synchronously, optionally resulting in the collection of feedback.
• If validations succeed, the Carrier responds with an empty 202 (Accepted).
  • A 404 (Not Found) is returned if the carrierBookingReference is not known.
  • A 409 (Conflict) is returned if the Carrier is processing a booking request.
• Booking state is unchanged (it is still in CONFIRMED or PENDING_AMENDMENT
• Amended booking state is unchanged (can be {any state}).

GET Booking (booking is in state CONFIRMED or PENDING_AMENDMENT and before booking cancellation is in CANCELLATION_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (booking is in state CONFIRMED or PENDING_AMENDMENT and before booking cancellation is in CANCELLATION_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).
• If the confirmed booking is a result of a re-confirmation or an amendment was never requested - then the Carrier responds with 404 (Not Found) as there is no amendment (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).

Asynchronous Carrier Processing

• The booking state stays unchanged (CONFIRMED or PENDING_AMENDMENT).
• The amended booking state stays unchanged (can be {any state}).
• The Carrier changes the booking cancellation state to CANCELLATION_RECEIVED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the cancellation was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
  • If a full notification is sent, the amendment (amendedBooking property) is included (if it exists), also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking cancellation is in state CANCELLATION_RECEIVED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking cancellation is in state CANCELLATION_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).
• If the confirmed booking is a result of a re-confirmation or an amendment was never requested - then the Carrier responds with 404 (Not Found) as there is no amendment (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩² ↩³ ↩⁴

Use Case 14: Process Booking cancellation

Confirm Cancellation

• The Carrier changes the booking state to CANCELLED.
• The Carrier changes the amended booking state to AMENDMENT_CANCELLED.
• The Carrier changes the booking cancellation state to CANCELLATION_CONFIRMED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the cancelled booking was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking
  • If a full notification is sent, the amendment (amendedBooking property) is included (if it exists), also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking cancellation is in state CANCELLATION_CONFIRMED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the cancelled booking
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking cancellation is in state CANCELLATION_RECEIVED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).
• If the confirmed booking is a result of a re-confirmation or an amendment was never requested - then the Carrier responds with 404 (Not Found) as there is no amendment (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).

Decline Cancellation

• The booking state stays unchanged (CONFIRMED or PENDING_AMENDMENT).
• The amended booking state stays unchanged (can be {any state}).
• The Carrier changes the booking cancellation state to CANCELLATION_DECLINED.
• The Carrier sends a notification to the Shipper.
  • If feedback for the confirmed booking was collected, it is included in the notification root
  • If a full notification is sent, the confirmed booking (booking property) is included, also containing optional feedback connected to the confirmed booking (if the confirmed booking is in state PENDING_AMENDMENT - the feedback is mandatory)
  • If a full notification is sent, the amendment (amendedBooking property) is included (if it exists), also containing optional feedback connected to the amendment
  • There MAY be differences between the feedback in the root and within the confirmed booking (e.g. the Carrier MAY always include INFO feedback in the root but not within the booking, or the other way around).
• The Carrier MAY resend the notification, a different notification id or previous notification id can be reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

GET Booking (after booking cancellation is in state CANCELLATION_DECLINED)

Calling GET /bookings/{bookingReference} ¹

• The Shipper sends a GET request to retrieve the booking.
• The Carrier responds with 200 (Ok) with the content of the confirmed booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).

GET Booking Amendment (after booking cancellation is in state CANCELLATION_DECLINED)

Calling GET /bookings/{bookingReference}?amendedContent=true ¹

• The Shipper sends a GET request with the amendedContent query parameter set to true to retrieve the amended booking.
• The Carrier responds with 200 (Ok) with the content of the amended booking (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).
  • The optional feedback is included in the booking.
• Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the booking asynchronously).
• If the confirmed booking is a result of a re-confirmation or an amendment was never requested - then the Carrier responds with 404 (Not Found) as there is no amendment (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the booking).

Back to Table of Content ⬆️

Footnotes

1. bookingReference in this case can only be carrierBookingReference since the Booking is Confirmed. ↩ ↩² ↩³ ↩⁴