List your shipments

Markdown

Retrieve and filter all shipments linked to your ParcelParcel account.

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

Example request

Booked DHL shipments

curl --request GET 'https://services.parcelparcel.com/partners-api/v1/shipments?status=created_at_carrier&carrier=DHL' \
  --header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
  --header 'Content-Type: application/json'

const response = await fetch("https://services.parcelparcel.com/partners-api/v1/shipments?status=created_at_carrier&carrier=DHL", {
  method: "GET",
  headers: {
    "X-PP-API": "{YourAPIKey}@{YourAPISecret}",
    "Content-Type": "application/json",
  },
});
const data = await response.json();
console.log(data);

import requests

response = requests.get(
    "https://services.parcelparcel.com/partners-api/v1/shipments?status=created_at_carrier&carrier=DHL",
    headers={
        "X-PP-API": "{YourAPIKey}@{YourAPISecret}",
        "Content-Type": "application/json",
    },
)
print(response.json())

Tip: copy the cURL and paste it in Postman under Import, or straight into the URL bar of a new request. Postman fills in the method, headers and body for you. Replace {YourAPIKey}@{YourAPISecret} with your own API key and secret (use your sandbox key while testing), or import the whole Postman Collection.

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

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

JSON

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

Examples

Don't know how to test these requests? Check our guide.

Request example - Booked DHL shipments

curl --location --request GET 'https://services.parcelparcel.com/partners-api/v1/shipments?status=created_at_carrier&carrier=DHL' \
--header 'X-PP-API: {YourAPIKey}@{YourAPISecret}' \
--header 'Content-Type: application/json'

GET /partners-api/v1/shipments?status=created_at_carrier&carrier=DHL HTTP/1.1
Host: services.parcelparcel.com
X-PP-API: {YourAPIKey}@{YourAPISecret}
Content-Type: application/json

Don't forget to change the X-PP-API element in the header for this request to work. Leave out the query parameters to list all your shipments.

List your shipments

Example request

#Header

#Body

#Query Parameters

#Shipment status values

#Response

#Address fields

#Example Response

#Examples

#Request example - Booked DHL shipments

Header

Body

Query Parameters

Shipment status values

Response

Address fields

Example Response

Examples

Request example - Booked DHL shipments