📦 List shipments

Retrieve a list of shipments that are booked through MyParcelParcel.

This endpoint allows you to fetch and filter all shipments linked to your account.

Method

In order to list your shipments, you need to use the following method:

GET

Endpoint

You need the following endpoint:

https://services.parcelparcel.com/partners-api/v1/shipments

Header

You need to add the following headers:

Name	Value
Content-Type	application/json
X-PP-API	`{YourAPIKey}@{YourAPISecret}`

Don't you have an API Key and API Secret yet? Check our Authentication page and how to get them in under a minute.

Body

There is no body needed. All filters are passed as query parameters.

For example:

https://services.parcelparcel.com/partners-api/v1/shipments?status=created_at_carrier&carrier=DHL

https://services.parcelparcel.com/partners-api/v1/shipments?status=created_at_carrier&carrier=DHL&bookedFrom=2026-01-01&bookedTo=2026-05-20&originCountry=NL&destinationCountry=DE&shipmentId=387769

Query Parameters

All query parameters are optional and can be combined freely.

Name	Type	Description
page	integer	Page number. Defaults to `1`.
perPage	integer	Number of results per page. Defaults to `25`, maximum `100`.
status	string	Filter by shipment status. See status values below. Omit to return all active statuses.
shipmentId	integer	Filter by a specific shipment ID.
search	string	Search by reference or tracking number.
carrier	string	Filter by carrier ID (e.g. `DHL`, `FEDEX`, `UPS`).
bookedFrom	string	Return shipments booked on or after this date. Format: `YYYY-MM-DD`.
bookedTo	string	Return shipments booked on or before this date. Format: `YYYY-MM-DD`.
originCountry	string	Filter by origin country. Use ISO 3166-1 alpha-2 codes (e.g. `NL`, `DE`, `US`).
destinationCountry	string	Filter by destination country. Use ISO 3166-1 alpha-2 codes (e.g. `NL`, `DE`, `US`).

Shipment status values

Status	Description
`waiting_for_booking`	Draft shipment, not yet submitted to the carrier
`progress`	Shipment is being processed
`created_at_carrier`	Shipment is booked and has a tracking number
`done`	Shipment has been delivered
`cancelled`	Shipment has been cancelled

Response

The following response elements are returned:

Name	Value	Comments
errors	boolean	Whether an error occurred.
message	string	A human-readable result message.
data	array	A collection of shipment objects.
data.id	integer	The unique identifier of the shipment.
data.status	string	The current status of the shipment. See status values above.
data.trackingNumber	string	The tracking number assigned by the carrier. `null` if not yet booked.
data.trackingUrl	string	A direct link to track the shipment on the carrier's website. `null` if not yet booked.
data.trackingStatus	string	The latest tracking event status. Possible values: `info_received`, `in_transit`, `exception`, `delivered`.
data.labelsUrl	string	URL to retrieve the shipping label PDF. `null` if not yet booked. Requires the same `X-PP-API` header.
data.reference	string	Your own reference for the shipment, as provided when creating it.
data.carrier	string	The display name of the carrier (e.g. `DHL`, `FedEx`).
data.product	string	The name of the shipping product (e.g. `FedEx Priority Overnight`).
data.price	float	The shipment price excluding VAT, rounded to 2 decimals.
data.pickupAddress	object	The sender address. See address fields below.
data.destinationAddress	object	The recipient address. See address fields below.
data.createdAt	string	ISO 8601 timestamp of when the shipment was created.
data.bookedAt	string	ISO 8601 timestamp of when the shipment was booked at the carrier. `null` if not yet booked.
meta.total	integer	Total number of shipments matching the applied filters.
meta.page	integer	The current page number.
meta.perPage	integer	The number of results per page.

Address fields

Both pickupAddress and destinationAddress contain the following fields:

Name	Type	Description
company	string	Company name
contactPerson	string	Full name of the contact person
phone	string	Phone number
email	string	Email address
addressLine1	string	First line of the street address
addressLine2	string	Second line of the street address
zipcode	string	Postal code
city	string	City
stateOrProvince	string	State or province
country	string	ISO 3166-1 alpha-2 country code
vatNumber	string	VAT number
eoriNumber	string	EORI number (used for customs clearance)

Example Response

{
    "errors": false,
    "message": "Query processed successfully",
    "data": [
        {
            "id": 387766,
            "status": "created_at_carrier",
            "trackingNumber": "1ZG2237K6804083920",
            "trackingUrl": "https://www.ups.com/track?loc=en_US&tracknum=1ZG2237K6804083920",
            "trackingStatus": "in_transit",
            "labelsUrl": "https://services.parcelparcel.com/partners-api/v1/shipments/387766/labels",
            "reference": "my-order-ref-123",
            "carrier": "UPS",
            "product": "UPS Standard",
            "price": 57.23,
            "pickupAddress": {
                "company": "My Company",
                "contactPerson": "John Doe",
                "phone": "0201234567",
                "email": "[email protected]",
                "addressLine1": "Teststreet 1",
                "addressLine2": null,
                "zipcode": "1057 BN",
                "city": "Amsterdam",
                "stateOrProvince": null,
                "country": "NL",
                "vatNumber": null,
                "eoriNumber": null
            },
            "destinationAddress": {
                "company": null,
                "contactPerson": "Jane Smith",
                "phone": "12312312311",
                "email": "[email protected]",
                "addressLine1": "123 Main St",
                "addressLine2": null,
                "zipcode": "75001",
                "city": "Dallas",
                "stateOrProvince": "TX",
                "country": "US",
                "vatNumber": null,
                "eoriNumber": null
            },
            "createdAt": "2026-04-13T09:12:00+00:00",
            "bookedAt": "2026-04-13T09:14:32+00:00"
        }
    ],
    "meta": {
        "total": 1,
        "page": 1,
        "perPage": 25
    }
}