Track external shipment

API specification

The track-external-shipment endpoint allows you to import an externally registered shipment into the MyParcel.com system. This allows users to track their shipment status updates via the MyParcel.com API and benefit from features such as webhooks.

Request

Required Scope: shipments.manage

Minimum shipment requirements

In order to successfully track an externally registered shipment through our system, you need to provide the following information:

Attributes

The following attributes should always be included in a shipment request:

Attribute Description
recipient_address Address object containing information of the shipments recipient address.
sender_address Address object containing information about where the shipment is sent from.
return_address Address object containing information about where the shipment can be returned to.
physical_properties Physical properties object containing at least the weight of the shipment.
tracking_code A string containing the carrier’s tracking code of the externally registered shipment.

Relationships

The shop relationship is always required in any shipment creation request. The contract relationship is required in order to retrieve tracking information from the carrier.

Relationship Description
shop A shop relationship object containing the uuid of the shop that is the owner of this shipment.
contract A contract relationship object containing the uuid of the contract with the credentials to track this shipment.

Sandbox environment

Since our sandbox environment does not provide real shipments, they will never receive a status update from the carrier. To simulate a status update, you can provide a status_id in sandbox requests. This way you can simulate realistic shipment behavior and trigger webhooks to test your implementation. See the update-shipment-status endpoint for more implementation details and examples.

POST /track-external-shipment HTTP/1.1
Example: https://sandbox-api.myparcel.com/track-external-shipment
{
  "data": {
    "type": "shipments",
    "attributes": {
      "recipient_address": {
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "street_1": "221B Baker Street",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB"
      },
      "return_address": {
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "street_1": "221B Baker Street",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB"
      },
      "sender_address": {
        "first_name": "Sherlock",
        "last_name": "Holmes",
        "street_1": "221B Baker Street",
        "postal_code": "NW1 6XE",
        "city": "London",
        "country_code": "GB"
      },
      "physical_properties": {
        "weight": 5000
      },
      "tracking_code": "ABCD0123456789"
    },
    "relationships": {
      "contract": {
        "data": {
          "type": "contracts",
          "id": "2cb32706-5762-4b96-9212-327e6afaeeff"
        }
      },
      "shop": {
        "data": {
          "type": "shops",
          "id": "35eddf50-1d84-47a3-8479-6bfda729cd99"
        }
      }
    }
  }
}

Response

The API will respond with status 204 No Content indicating that no content is returned, but the shipment has been imported.

05-05-2022