Retrieve shipment statuses ========================== After you have created a shipment, you most likely want to receive status updates so you can trigger business logic in your system. .. list-table:: :header-rows: 1 :width: 100% :widths: 50 50 * - Do - Dont * - Configure ``send-resource`` type webhooks towards an endpoint in your system. See the page on `how to create a webhook `_ and feel free to `submit a ticket `_ or `send an email `_ if you need help setting this up! - Please do not use a script to make multiple calls to our shipment or shipment-statuses endpoint. This is not practical for both parties and you might encounter rate-limiting issues in the future. Shipment status and carrier statuses ------------------------------------ Shipments always have at least one shipment status. A :doc:`shipment status resource ` contains: 1. A relation with a :ref:`generic status ` resource containing a code and description. 2. Information about the :ref:`carrier specific status ` like a status code, description and timestamp. You receive the :ref:`current shipment status ` within every shipment resource. A complete :ref:`status history ` can be retrieved separately. .. _generic-status: Generic status ______________ Within the MyParcel.com API, a list of generic :doc:`status resources ` is used for several types of resources. The list of status codes for shipments is: ================================= =========== =========== code level description ================================= =========== =========== shipment-processing pending The shipment is being processed internally. shipment-concept pending The shipment was created, but has not been registered with the carrier (yet). shipment-created-without-tracking success The shipment was registered and has files available, but no further tracking is available. shipment-registration-failed failed The concept shipment was rejected by the carrier. Please solve the errors and register it again. shipment-registered in-progress The shipment was registered with the carrier. Files (such as a label) are available. shipment-received-by-carrier in-progress The shipment was collected by or handed over to the carrier. shipment-on-the-way-to-hub in-progress The consolidation shipment got a status so this shipment is on the way to the hub. shipment-at-sorting in-progress The shipment is in the sorting process of the carrier. shipment-with-courier in-progress The shipment is with the courier and on it's way to the destination. shipment-at-parcel-shop in-progress The shipment is delivered at the parcel shop and ready for pick-up. shipment-delivered success The shipment was delivered successfully. shipment-returned-to-sender success The shipment could not be delivered and has been returned to the sender. shipment-failed failed The carrier has failed to deliver this shipment. shipment-voided cancelled The shipment was successfully voided. The label is no longer downloadable or usable. ================================= =========== =========== An up-to-date list of the generic statuses can be retrieved using the `GET /statuses `_ endpoint. .. note:: After initial shipment creation and shipment updates through PATCH requests, the shipment will get the status ``shipment-processing``. This indicates that the shipment is undergoing internal processes, for example any :doc:`hooks ` the user might have set up. The status will automatically update to ``shipment-concept`` when the internal processes are finished. .. _carrier-specific-status: Carrier specific status _______________________ Every carrier has its own list of statuses for the different events happening in their network. All of those carrier statuses are mapped to one of the `generic statuses <#generic-status>`_ mentioned above. Information about the carrier specific status is present in the shipment status resource in the following attributes: =========== =========== Attribute Description =========== =========== category The category code of this status update. If the value is not ``default``, some action might be required by the sender or recipient. code Status code we received from the carrier. description Description of the status code we received from the carrier. assigned_at Unix timestamp of the status update according to the carrier. =========== =========== The carrier status category indicates if something out of the ordinary has happened to the shipment. If the value is not ``default``, an action might be required by the sender or recipient. The list of category codes for a carrier status is: ====================================== =========== code description ====================================== =========== change-in-flight For deliveries which could be outside of ETA due to in-flight changes (not transit / carrier / weather related) or delivery areas where appointments are required. default Default category indicating a normal flow. delay All potential carrier / weather / delivery delays. Shipments can still be delivered within the ETA. failed-cash-on-delivery Cash on delivery failed, possibly due to no ID. Shipment is held while waiting on the payment. failed-collection Carrier could not collect the shipment. No more collection attempts. failed-collection-attempt Driver has physically tried to collect the shipment but did not succeed. failed-collection-attempt-user Driver has physically tried to collect the shipment but the customer is not home. failed-collection-attempt-force-majeur Collection attempt failed due to a Force Majeure. failed-customs-clearance Confiscations, customs delays & missing paperwork. failed-delivery-attempt Driver has physically tried to deliver the shipment but did not succeed. failed-delivery-attempt-user Driver has physically tried to deliver the shipment but the customer was not home. failed-delivery-attempt-force-majeure Delivery attempt failed due to a Force Majeure. failed-miscellaneous Please contact the carrier. Some communication has failed or a collection has not been scheduled. failed-pre-advice Missing pre-advice at any point during the shipping process. failed-refused-delivery Customer or address that refuses to accept delivery. Swap-it failure. failed-shipment-damaged Shipments with damage or disposal scans. failed-shipment-missing Shipments that are missing or lost. partial-collection Multi-colli shipments where the quantity collected does not match the pre-advice / POC / POD. partial-delivery Multi-colli shipments where the quantity delivered does not match the pre-advice / POC / POD. relabelling Relabelling due to area or service changes, or parcel dimensions / weight which exceed those stated by the shipper. require-delivery-instructions Change of address request due to incorrect addresses / contact details, customer on holiday, empty house etc. security-alert Concerns raised by security or dangerous goods. ====================================== =========== An up-to-date list of the status categories can be retrieved using the `GET /get-carrier-status-categories `_ endpoint. .. note:: Shipments having a specific carrier status category can be retrieved using the ``filter[carrier_status][category]`` filter on the `GET /shipments `_ endpoint. .. _current-status: Current status -------------- The current status of a shipment can be found in the ``relationships`` of a :doc:`shipment resource `. .. code-block:: json { "data": { "type": "shipments", "id": "7b808eee-bf1c-40cd-98f2-3c335a06417e", "attributes": { "...": "..." }, "relationships": { "shipment_status": { "data": { "type": "shipment-statuses", "id": "9e6d8dba-7c45-4351-a9fc-b55a0cbafbad" }, "links": { "related": "https://api.sandbox.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad" } } } } } To get the complete :doc:`shipment status ` resource, you will need to either: - fetch it, using the ``related`` link from the ``shipment_status`` relationship, or even better: - include it in the ``GET /shipments`` or ``GET /shipments/{shipment_id}`` request using the ``include`` query parameter: ``?include=shipment_status,shipment_status.status`` .. _status-history: Status history -------------- A complete list of all shipment statuses belonging to a shipment can be retrieved using the shipment statuses endpoint. You will need the ``shipments.manage`` scope in your access token in order to access this endpoint. .. code-block:: http GET /shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses HTTP/1.1 Check the `MyParcel.com API Specification `_ for a complete description of this shipment status endpoint.