Parent and child references
A parent reference is generated whenever container tracking is initiated from a document number: either a bill of lading or a booking number. For every container found on that document, the API creates a child reference to track that container individually.
Each child reference has a parent_reference_id property set to the parent reference's reference_id. This allows you to easily group shipments together as you receive updates for each container.
When a parent reference is created
| How tracking is initiated | Parent reference created? | parent_reference_id on the container reference |
|---|---|---|
Bill of lading (bill_of_lading) | Yes | Set to the parent bill of lading reference's reference_id |
Booking number (booking_number) | Yes | Set to the parent booking reference's reference_id |
Bill of lading or booking number via ACI, with no carrier_code | Yes | Set to the parent bill of lading or booking reference's reference_id |
Bill of lading or booking number with a container_id | No. A single reference is created for that container only | null |
Container ID (container_id) with a carrier_code | No | null |
| Container ID alone via ACI | No | null |
How is the parent reference determined?What determines whether a parent reference is created is the identifier you track by, not the carrier identification method you use. A request that relies on Auto Carrier Identification still creates a parent reference and one child per container when it includes a bill of lading or booking number without a
container_id.
Unsubscribing a parent reference
Unsubscribing a parent reference also unsubscribes all of its child references.
When you call Unsubscribe a reference with a parent reference's reference_id, the parent and every child reference created under it are deactivated. The API stops creating updates for all of them, and if a callback_url was provided, webhook updates stop being sent for all of them.
To stop tracking only some of the containers on a bill of lading or booking number, unsubscribe those child references individually using each child's own reference_id. This leaves the parent reference and the remaining child references active.
Tips for using parent references
- By default, once a parent reference has been generated and discovers its existing child references, it will no longer search for new child references even while still active. We will also not remove any created child references for the same reason. This behavior can be changed with Continuous MBL and Booking Processing.
- If active, the parent reference ID can be used to query the API's List reference updates endpoint to easily retrieve the latest update payload for each active child reference.
- The parent reference itself is not billable. Only the child container references count toward your active references. See Billable references.
Updated 15 days ago