Retrieve shipment statuses

Shipments always have at least one shipment status. A shipment status resource contains:

  1. A relation with a generic status resource containing a code and description.

  2. 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. Status resources can be of the following levels:

  • pending

  • in-progress

  • success

  • failed

  • cancelled

The list of status codes for the shipment resource 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.

failed-customs-clearance

Confiscations, customs delays & missing paperwork.

failed-delivery-attempt

Driver has physically tried to deliver the shipment but the customer was not home.

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://sandbox-api.myparcel.com/shipments/7b808eee-bf1c-40cd-98f2-3c335a06417e/statuses/9e6d8dba-7c45-4351-a9fc-b55a0cbafbad"
        }
      },
      "shop": {
        "...": "..."
      }
    }
  }
}

To get the complete shipment status resource, you will need to either:

  • fetch it, using the related link from the shipment_status relationship, or

  • include it in the GET /shipments/{shipment_id} request using the include query parameter: ?include=shipment_status.

Status history

A complete list of all shipment statuses belonging to a shipment can be retrieved using the shipment status 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.