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.

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 shipment status resource contains:

A relation with a generic status resource containing a code and description.
Information about the carrier specific status like a status code, description and timestamp.

You receive the current shipment status within every shipment resource. A complete status history can be retrieved separately.

Generic status

Within the MyParcel.com API, a list of generic 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 hooks the user might have set up. The status will automatically update to shipment-concept when the internal processes are finished.

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 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

The current status of a shipment can be found in the relationships of a shipment resource.

{
  "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 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

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.

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.