This is a technical implementation guide to the DCSA electronic Bill of Lading (EBL) standard version 3.0. The audience of this document is technical teams of DCSA adopting organizations.

Table of Contents

Use Case 1: Submit Shipping Instructions

Use Case 2: Request to update Shipping Instructions

Use Case 3: Submit updated Shipping Instructions

Use Case 4: Process updated Shipping Instructions

Use Case 5: Cancel update to Shipping Instructions

Use Case 6: Publish Draft Transport Document

Use Case 7: Approve Draft Transport Document

Use Case 8: Issue Transport Document

Use Case 9: Request surrender Transport Document (amendment)

Use Case 10: Process Transport Document surrender request (amendment)

Use Case 11: Void original Transport Document and issue amended Transport Document

Use Case 12: Request surrender Transport Document (delivery)

Use Case 13: Process Transport Document surrender request (delivery)

Use Case 14: Confirm Shipping Instructions completed

Use Case 1: Submit Shipping Instructions

Calling: POST /shipping-instructions

 

Synchronous carrier processing

• The shipper sends a POST request to create a Shipping Instructions.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the Shipping Instructions, 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 shippingInstructionsReference.
• The Shipping Instructions does not yet contain a state

 

GET Shipping Instructions (before Shipping Instructions is in state RECEIVED)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Updated Shipping Instructions (before Shipping Instructions is in state RECEIVED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

• The Shipper sends a GET request with the updatedContent query parameter set to true to retrieve the updated Shipping Instructions.
• The Carrier responds with 404 (Not Found) as no update exists.

 

GET Transport Document (before Shipping Instructions is in state RECEIVED)

Calling: GET /transport-document/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with 404 (Not Found) as no Transport Document exists.

 

Asynchronous carrier processing

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

 

GET Shipping Instructions (after Shipping Instructions is in state RECEIVED)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Updated Shipping Instructions (after Shipping Instructions is in state RECEIVED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

• The Shipper sends a GET request with the updatedContent query parameter set to true to retrieve the updated Shipping Instructions.
• The Carrier responds with 404 (Not Found) as no update exists.

 

GET Transport Document (after Shipping Instructions is in state RECEIVED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

Back to Table of Content ⬆️

Footnotes

1. documentReference can be either: shippingInstructionsReference or transportDocumentReference depending on what is available. If the Carrier has provided the transportDocumentReference this can be used throughout the process. ↩ ↩² ↩³ ↩⁴

Use Case 2: Request to update Shipping Instructions

• The Carrier changes the Shipping Instructions state to PENDING_UPDATE.
• If an Updated Shipping Instruction exists (because of a previous request to update) it is cleared.
• The Carrier sends a Shipping Instructions Notification to the Shipper.
  • There MUST be feedback. It is included in the notification root.
  • If a full notification is sent, the Shipping Instructions (Shipping Instructions property) is included, MUST also contain feedback.
  • There MAY be differences between the feedback in the root and within the Shipping Instructions (e.g. the Carrier MAY always include INFO feedback in the root but not within the Shipping Instructions, 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 Shipping Instructions (after Shipping Instructions is in state PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Updated Shipping Instructions (after Shipping Instructions is in state PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

• The Shipper sends a GET request with the updatedContent query parameter set to true to retrieve the updated Shipping Instructions.
• The Carrier responds with 404 (Not Found) as no update exists after the status has changed to PENDING_UPDATE.

 

GET Transport Document (after Shipping Instructions is in state PENDING_UPDATE)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

  Back to Table of Content ⬆️

Footnotes

1. documentReference can be either: shippingInstructionsReference or transportDocumentReference depending on what is available. If the Carrier has provided the transportDocumentReference this can be used throughout the process. ↩ ↩²

Use Case 3: Submit updated Shipping Instructions

Calling: PUT /shipping-instructions/{documentReference} ¹

 

Synchronous carrier processing

• The Shipper sends a PUT request to update Shipping Instructions.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the Shipping Instructions, 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 documentReference ¹ is not known.
  • A 409 (Conflict) is returned if the Carrier is processing a Shipping Instructions request.
• Shipping Instructions state is unchanged (it is still in RECEIVED or PENDING_UPDATE).

 

GET Shipping Instructions (Shipping Instructions is in state RECEIVED)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Shipping Instructions (Shipping Instructions is in state PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Updated Shipping Instructions (Shipping Instructions is in state RECEIVED or PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

• The Shipper sends a GET request with the updatedContent query parameter set to true to retrieve the updated Shipping Instructions.
• If Updated Shipping Instructions status IS NOT UPDATE_RECEIVED then the Carrier responds with 404 (Not Found) as no update exists after the status has changed to PENDING_UPDATE and before the update is in state UPDATE_RECEIVED.
• If Updated Shipping Instructions status IS UPDATE_RECEIVED then the Carrier responds with 200 (Ok) with the content of the (last) Updated Shipping Instructions (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the Shipping Instructions).
  • The optional feedback is included in the Updated Shipping Instructions.
  • Subsequent GET requests MAY return different feedback (e.g. the Carrier MAY still be processing the Updated Shipping Instructions asynchronously).

 

GET Transport Document (Shipping Instructions is in state RECEIVED or PENDING_UPDATE)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

 

Asynchronous carrier processing

• The Carrier sets the updated Shipping Instructions state to UPDATE_RECEIVED (the Shipping Instructions state is unchanged).
• The Carrier sends a Shipping Instructions Notification to the Shipper.
  • If feedback for the updated Shipping Instructions was collected, it is included in the notification root
  • If a full notification is sent
    • The Shipping Instructions (Shipping Instructions property) is included, also containing feedback (mandatory if Shipping Instructions state is PENDING_UPDATE and optional if the Shipping Instructions state is RECEIVED)
    • The updated Shipping Instructions (Updated Shipping Instructions property) is included, optionally containing feedback
  • There MAY be differences between the feedback in the root and within the updated Shipping Instructions (e.g. the Carrier MAY always include INFO feedback in the root but not within the updated Shipping Instructions, or the other way around).
• The Carrier MAY resend the Shipping Instructions 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 Shipping Instructions (after updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Updated Shipping Instructions (after updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

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

 

GET Transport Document (after updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

  Back to Table of Content ⬆️

Footnotes

1. documentReference can be either: shippingInstructionsReference or transportDocumentReference depending on what is available. If the Carrier has provided the transportDocumentReference this can be used throughout the process. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷

Use Case 4: Process updated Shipping Instructions

 

Confirm Updated Shipping Instructions

• The Carrier changes the Shipping Instructions state to RECEIVED.
• The Carrier changes the updated Shipping Instructions state to UPDATE_CONFIRMED.
• The update now becomes the confirmed Shipping Instructions.
• The Carrier sends a Shipping Instructions Notification to the Shipper.
  • If feedback for the Shipping Instructions is collected, it is included in the notification root
  • If a full notification is sent, the new Shipping Instructions (Shipping Instructions property) is included, also containing optional feedback connected to the Shipping Instructions
  • If a full notification is sent, the update Shipping Instructions (Updated Shipping Instructions property) is included, also containing optional feedback connected to the update
  • There MAY be differences between the feedback in the root and within the Shipping Instructions (e.g. the Carrier MAY always include INFO feedback in the root but not within the Shipping Instructions, or the other way around).
• The Carrier MAY resend the notification; either a new notification id or previous notification id maybe reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

 

GET Shipping Instructions (after Shipping Instructions is in state RECEIVED)

Calling: GET /shipping-instructions/{documentReference} ¹

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

👉Important note: The content of the Shipping Instructions and the Updated Shipping Instructions are the same.

 

GET Updated Shipping Instructions (after updated Shipping Instructions is in state UPDATE_CONFIRMED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

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

👉Important note: The content of the Shipping Instructions and the Updated Shipping Instructions are the same.

 

GET Transport Document (after Shipping Instructions is in RECEIVED and updated Shipping Instructions is in state UPDATE_CONFIRMED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

 

Decline Updated Shipping Instructions

• The Carrier leaves the Shipping Instructions state unchanged (it can be RECEIVED or PENDING_UPDATE)
• The Carrier changes the updated Shipping Instructions state to UPDATE_DECLINED.
• The Carrier sends a Shipping Instructions notification to the Shipper.
  • If feedback for the Shipping Instructions is collected, it is included in the notification root
  • If a full notification is sent, the new Shipping Instructions (Shipping Instructions property) is included, also containing optional feedback connected to the Shipping Instructions (the feedback is mandatory if the state of the Shipping Instructions is PENDING_UPDATE)
  • If a full notification is sent, the update Shipping Instructions (Updated Shipping Instructions property) is included, also containing optional feedback connected to the update
  • There MAY be differences between the feedback in the root and within the Shipping Instructions (e.g. the Carrier MAY always include INFO feedback in the root but not within the Shipping Instructions, or the other way around).
• The Carrier MAY resend the notification; either a new notification id or previous notification id maybe reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

 

GET Shipping Instructions (after updated Shipping Instructions is in state RECEIVED or PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference} ¹

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

 

GET Updated Shipping Instructions (after updated Shipping Instructions is in state UPDATE_DECLINED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

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

 

GET Transport Document (after Shipping Instructions is in RECEIVED or PENDING_UPDATE and updated Shipping Instructions is in state UPDATE_DECLINED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

  Back to Table of Content ⬆️

Footnotes

1. documentReference can be either: shippingInstructionsReference or transportDocumentReference depending on what is available. If the Carrier has provided the transportDocumentReference this can be used throughout the process. ↩ ↩² ↩³ ↩⁴

Use Case 5: Cancel update to Shipping Instructions

Calling: PATCH /shipping-instructions/{documentReference} ¹

with payload:

{
  "updatedShippingInstructionsStatus": "UPDATE_CANCELLED"
}

 

Synchronous carrier processing

• The Shipper sends a PATCH request to cancel a Shipping Instructions update.
• 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 documentReference ¹ is not known or no update exists.
  • A 409 (Conflict) is returned if the Carrier is processing a Shipping Instructions request.
• Shipping Instructions state is unchanged (it is still in RECEIVED or PENDING_UPDATE).
• The updated Shipping Instructions state is unchanged (it is still in UPDATE_RECEIVED).

 

GET Shipping Instructions (Shipping Instructions is in state RECEIVED or PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference} ¹

• The Shipper sends a GET request to retrieve the Shipping Instructions.
• The Carrier responds with 200 (Ok) with the content of the Shipping Instructions (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the Shipping Instructions).
  • The optional feedback is included in the Shipping Instructions (if the Shipping Instructions 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 Shipping Instructions asynchronously).

 

GET Updated Shipping Instructions (Updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

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

 

GET Transport Document (when Shipping Instructions is in RECEIVED or PENDING_UPDATE and updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

 

Asynchronous carrier processing: Accepting the Cancellation

• The Shipping Instructions state stays unchanged (RECEIVED or PENDING_UPDATE).
• The Carrier changes the Updated Shipping Instructions state to UPDATE_CANCELLED.
• The Carrier sends a Shipping Instructions 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 Shipping Instructions (shippingInstructions property) is included, also containing optional feedback connected to the Shipping Instructions (if the Shipping Instructions is in state PENDING_UPDATE - the feedback is mandatory)
  • If a full notification is sent, the update (updatedShippingInstructions property) is included, also containing optional feedback connected to the update
  • There MAY be differences between the feedback in the root and within the Updated Shipping Instructions (e.g. the Carrier MAY always include INFO feedback in the root but not within the Shipping Instructions, or the other way around).
• The Carrier MAY resend the notification; either a new notification id or previous notification id maybe reused.
  • The content of the notification MAY be the same or different.
  • The feedback MAY be the same or different.

 

GET Shipping Instructions (Shipping Instructions is in state RECEIVED or PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference} ¹

• The Shipper sends a GET request to retrieve the Shipping Instructions.
• The Carrier responds with 200 (Ok) with the content of the Shipping Instructions (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the Shipping Instructions).
  • The optional feedback is included in the Shipping Instructions (if the Shipping Instructions 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 Shipping Instructions asynchronously).

 

GET Updated Shipping Instructions (Updated Shipping Instructions is in state UPDATE_CANCELLED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

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

 

GET Transport Document (when Shipping Instructions is in RECEIVED or PENDING_UPDATE and updated Shipping Instructions is in state UPDATE_CANCELLED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

 

Asynchronous carrier processing: Decline the Cancellation

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

 

GET Shipping Instructions (Shipping Instructions is in state RECEIVED or PENDING_UPDATE)

Calling: GET /shipping-instructions/{documentReference} ¹

• The Shipper sends a GET request to retrieve the Shipping Instructions.
• The Carrier responds with 200 (Ok) with the content of the Shipping Instructions (or a 202 (Accepted) / 409 (Conflict) in case the Carrier is in the middle of processing the Shipping Instructions).
  • The optional feedback is included in the Shipping Instructions (if the Shipping Instructions 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 Shipping Instructions asynchronously).

 

GET Updated Shipping Instructions (Updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /shipping-instructions/{documentReference}?updatedContent=true ¹

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

 

GET Transport Document (when Shipping Instructions is in RECEIVED or PENDING_UPDATE and updated Shipping Instructions is in state UPDATE_RECEIVED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• If a Transport Document has previously been Drafted then the Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).
• If no Transport Document yet exists - then the Carrier responds with 404 (Not Found).

  Back to Table of Content ⬆️

Footnotes

1. documentReference can be either: shippingInstructionsReference or transportDocumentReference depending on what is available. If the Carrier has provided the transportDocumentReference this can be used throughout the process. ↩ ↩² ↩³ ↩⁴ ↩⁵ ↩⁶ ↩⁷ ↩⁸

Use Case 6: Publish Draft Transport Document

• The Carrier creates (or updates) a Transport Document and sets the state to DRAFT.
• The Carrier sends a Transport Document notification to the Shipper.
  • If feedback was collected, it is included in the notification root.
  • If a full notification is sent, the Transport Document (Transport Document property) is included, also containing feedback.
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• If the Carrier performs Use Case 6 again (republished the Draft) 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 Transport Document (after Transport Document is in state DRAFT)

Calling: GET /transport-documents/{transportDocumentReference}

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

  Back to Table of Content ⬆️

Use Case 7: Approve Draft Transport Document

Calling: PATCH /transport-documents/{transportDocumentReference}

with payload:

{
  "transportDocumentStatus": "APPROVED"
}

 

Synchronous carrier processing

• The Shipper sends a PATCH request to approve a Transport Document.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the approval 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 transportDocumentReference is not known.
  • A 409 (Conflict) is returned if the Carrier is processing a Transport Document request.
• Transport Document state is unchanged (it is still in DRAFT).

 

GET Transport Document (Transport Document is in state DRAFT)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

 

Asynchronous carrier processing

• The Carrier sets the Transport Document state to APPROVED.
• The Carrier sends a Transport Document Notification to the Shipper.
  • If feedback for the approved Transport Document was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the approved Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the approved Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state APPROVED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Shipper sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

  Back to Table of Content ⬆️

Use Case 8: Issue Transport Document

• The Carrier changes the Transport Document state to ISSUED.
• The Carrier sends a Transport Document notification to the Shipper.
  • If feedback was collected, it is included in the notification root.
  • If a full notification is sent, the Transport Document (Transport Document property) is included, also containing feedback.
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• If the Carrier performs Use Case 8 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.

👉 Important note: If the transportDocumentTypeCode='BOL' then the Transport Document will be issued to an eBL Solution Provider via the Issuance API (using PUT /v3/ebl-issuance-requests).

 

GET Transport Document (after Transport Document is in state ISSUED)

Calling: GET /transport-documents/{transportDocumentReference}

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

  Back to Table of Content ⬆️

Use Case 9: Request surrender Transport Document (amendment)

Calling: POST /v3/ebl-surrender-requests (via Surrender API)

with (example) payload:

{
  "surrenderRequestReference": "{Surrender Request Reference}",
  "transportDocumentReference": "{Transport Document Reference}",
  "surrenderRequestCode": "AREQ",
  "endorsementChain": [...{The endorsement chain}...]
}

 

Synchronous carrier processing

• The Party involved¹ (via the eBL Solution Provider) sends a POST request to Surrender a Transport Document for amendment.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the Surrender it can subsequently process it.
• Transport Document state is unchanged (it is still in ISSUED).

 

GET Transport Document (Transport Document is in state ISSUED)

Calling: GET /transport-documents/{transportDocumentReference} (via eBL API)

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

 

Asynchronous carrier processing

• The Carrier sets the Transport Document state to PENDING_SURRENDER_FOR_AMENDMENT.
• The Carrier sends a Transport Document Notification to the Party/Parties involved¹.
  • If feedback for the amendment request was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state PENDING_SURRENDER_FOR_AMENDMENT)

Calling: GET /transport-documents/{transportDocumentReference} (via eBL API)

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

  Back to Table of Content ⬆️

Footnotes

1. Party/Parties involved can be either: Shipper, Consignee, Endorsee or any other party authorized to the Transport Document. ↩ ↩² ↩³ ↩⁴

Use Case 10: Process Transport Document surrender request (amendment)

 

Confirm Surrender for Amendment

• The Carrier changes the Transport Document state to SURRENDERED_FOR_AMENDMENT.
• The Carrier sends a POST /v3/ebl-surrender-responses request back to the eBL Solution Provider with the following payload:

  {
    "surrenderRequestReference": "{Surrender Request Reference}",
    "action": "SURR"
  }
  

• The Carrier sends a Transport Document Notification to the Party/Parties involved¹.
  • If feedback for the amendment was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state SURRENDERED_FOR_AMENDMENT)

Calling: GET /transport-documents/{transportDocumentReference}

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

 

Reject Surrender for Amendment

• The Carrier changes the Transport Document state to ISSUED.
• The Carrier sends a POST /v3/ebl-surrender-responses request back to the eBL Solution Provider with the following payload:

  {
    "surrenderRequestReference": "{Surrender Request Reference}",
    "action": "SREJ"
  }
  

• The Carrier sends a Transport Document Notification to the Party/Parties involved¹.
  • If feedback for the rejection was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state ISSUED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

  Back to Table of Content ⬆️

Footnotes

1. Party/Parties involved can be either: Shipper, Consignee, Endorsee or any other party authorized to the Transport Document. ↩ ↩² ↩³ ↩⁴

Use Case 11: Void original Transport Document and issue amended Transport Document

 

Void Surrendered Transport Document

• The Carrier voids the Surrendered Transport Document and sets the state to VOIDED.
• The Carrier sends a Transport Document notification to the Party/Parties involved¹.
  • If feedback was collected, it is included in the notification root.
  • If a full notification is sent, the (Surrendered) Transport Document (Transport Document property) is included, also containing feedback.
  • There MAY be differences between the feedback in the root and within the (Surrendered) Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• If the Carrier 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.

 

Issue Amended Transport Document

• The Carrier issues the Amended Transport Document and sets the state to ISSUED.
• The Carrier sends a Transport Document notification to the Party/Parties involved¹.
  • If feedback was collected, it is included in the notification root.
  • If a full notification is sent, the (Amended) Transport Document (Transport Document property) is included, also containing feedback.
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• If the Carrier 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.

  👉 Important note: If the transportDocumentReference is being reused for the amended Transport Document - the two Transport Document notifications will contain the same transportDocumentReference - the only way to distinguish the two is via the time property of the Notification (the VOIDED notification should be sent before the ISSUED notification).

  👉 Important note: If the transportDocumentReference is being reused then it is not possible to GET the VOIDED (Surrendered) Transport Document once the amended Transport Document has been ISSUED. A GET /transport-documents/{transportDocumentReference} would fetch the new Amended Transport Document. It is only possible to fetch the two different Transport Documents if they have different transportDocumentReference.

 

GET Transport Document

Calling: GET /transport-documents/{transportDocumentReference}

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content (explained above) of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

  Back to Table of Content ⬆️

Footnotes

1. Party/Parties involved can be either: Shipper, Consignee, Endorsee or any other party authorized to the Transport Document. ↩ ↩² ↩³

Use Case 12: Request surrender Transport Document (delivery)

Calling: POST /v3/ebl-surrender-requests (via Surrender API)

with (example) payload:

{
  "surrenderRequestReference": "{Surrender Request Reference}",
  "transportDocumentReference": "{Transport Document Reference}",
  "surrenderRequestCode": "SREQ",
  "endorsementChain": [...{The endorsement chain}...]
}

 

Synchronous carrier processing

• The Party involved¹ (via the eBL Solution Provider) sends a POST request to Surrender a Transport Document for delivery.
• The Carrier MUST perform the schema validation, to ensure that if it accepts the Surrender it can subsequently process it.
• Transport Document state is unchanged (it is still in ISSUED).

 

GET Transport Document (Transport Document is in state ISSUED)

Calling: GET /transport-documents/{transportDocumentReference} (via eBL API)

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

 

Asynchronous carrier processing

• The Carrier sets the Transport Document state to PENDING_SURRENDER_FOR_DELIVERY.
• The Carrier sends a Transport Document Notification to the Party/Parties involved¹.
  • If feedback for the surrender request was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state PENDING_SURRENDER_FOR_DELIVERY)

Calling: GET /transport-documents/{transportDocumentReference} (via eBL API)

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

  Back to Table of Content ⬆️

Footnotes

1. Party/Parties involved can be either: Shipper, Consignee, Endorsee or any other party authorized to the Transport Document. ↩ ↩² ↩³ ↩⁴

Use Case 13: Process Transport Document surrender request (delivery)

 

Confirm Surrender for Delivery

• The Carrier changes the Transport Document state to SURRENDERED_FOR_DELIVERY.
• The Carrier sends a POST /v3/ebl-surrender-responses request back to the eBL Solution Provider with the following payload:

  {
    "surrenderRequestReference": "{Surrender Request Reference}",
    "action": "SURR"
  }
  

• The Carrier sends a Transport Document Notification to the Party/Parties involved¹.
  • If feedback for the surrender was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state SURRENDERED_FOR_DELIVERY)

Calling: GET /transport-documents/{transportDocumentReference}

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

 

Reject Surrender for Delivery

• The Carrier changes the Transport Document state to ISSUED.
• The Carrier sends a POST /v3/ebl-surrender-responses request back to the eBL Solution Provider with the following payload:

  {
    "surrenderRequestReference": "{Surrender Request Reference}",
    "action": "SREJ"
  }
  

• The Carrier sends a Transport Document Notification to the Party/Parties involved¹.
  • If feedback for the rejection was collected, it is included in the notification root
  • If a full notification is sent
    • The Transport Document (Transport Document property) is included, also containing feedback
  • There MAY be differences between the feedback in the root and within the Transport Document (e.g. the Carrier MAY always include INFO feedback in the root but not within the Transport Document, or the other way around).
• The Carrier MAY resend the Transport Document 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 Transport Document (Transport Document is in state ISSUED)

Calling: GET /transport-documents/{transportDocumentReference}

• The Party involved¹ sends a GET Transport Document request to retrieve the Transport Document.
• The Carrier responds with a 200 (Ok) with the content of the Transport Document (or a 202 (Accepted) in case the Carrier is in the middle of processing the Transport Document).

  Back to Table of Content ⬆️

Footnotes

1. Party/Parties involved can be either: Shipper, Consignee, Endorsee or any other party authorized to the Transport Document. ↩ ↩² ↩³ ↩⁴

Use Case 14: Confirm Shipping Instructions completed

• The Carrier changes the Shipping Instructions state to COMPLETED.
• The Carrier sends a Shipping Instructions notification to the Shipper.
  • If feedback was collected, it is included in the notification root.
  • If a full notification is sent, the Shipping Instructions (Shipping Instructions property) is included, also containing feedback.
  • There MAY be differences between the feedback in the root and within the Shipping Instructions (e.g. the Carrier MAY always include INFO feedback in the root but not within the Shipping Instructions, or the other way around).
• If the Carrier 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 Shipping Instructions (after Shipping Instructions is in state COMPLETED)

Calling: GET /shipping-instructions/{shippingInstructionsReference}

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

  Back to Table of Content ⬆️