PostPlus API
  1. Scenarios And Workflows
PostPlus API
  • Authentication, Environments
  • Endpoints Overview
    • Parcels Endpoints
    • Shipments Endpoints
    • Tracking Endpoints
    • Accounts Endpoints
  • Scenarios And Workflows
    • Working with parcels
    • Create or update parcel record
    • Cancel or delete a parcel record
    • Manifesting parcels in bags and shipments
    • Query parcel tracking events
  • All API Endpoints
    • Parcels
      • Create or update single parcel.
      • Create or update up to 200 parcels in a single request.
      • Get parcel details by parcel Id.
      • Get up to 100 parcels details by parcel Ids.
      • Get parcel details by parcel number (tracking number).
      • Get up to 100 parcels details by parcel numbers (tracking numbers).
      • Get parcel details by sender reference number.
      • Get up to 100 parcel details by sender reference numbers.
      • Query up to 500 parcels.
      • Delete parcel by Id.
      • Delete up to 100 parcels by Ids.
      • Get print details and contents by print Id.
      • Get up to 100 parcel print details and contents by print Ids.
      • Get pickup point details by Id.
      • Query pickup points.
      • Group parcels into bags and link to a shipment (update parcel references).
      • Get parcel details by manifest reference numbers.
      • Get up to 100 parcel details by manifest reference numbers.
      • Get parcel details by carrier reference numbers.
      • Get up to 100 parcel details by carrier reference numbers.
    • Shipments
      • Create new shipment.
      • Update shipment.
      • Get shipment details.
      • Delete shipment.
      • Create new bag level shipment.
      • Update bag level shipment.
      • Link parcels with specified bag numbers to a shipment.
      • Validate and prepare shipment for submitting.
      • Submit and lock shipment and it's parcels.
      • Cancel erroneous parcels in a shipment.
      • Upload shipment manifest file.
      • Upload shipment document.
      • Delete shipment manifest file.
      • Query up to 500 shipments.
      • Group parcels into bags and link to a shipment, then prepare and submit shipment in one transaction.
    • Documents
      • Download manifest file.
      • Download resulting (processed) manifest file.
      • Download resulting (processed) shipment file.
      • Download shipment documents in archive file.
      • Download shipment document file by Id.
      • Download parcel label by Id.
      • Generate and download shipment parcel labels.
      • Generate and download generic bag labels.
      • Generate and download bag label.
      • Generate and download parcel commercial invoices.
    • Tracking
      • Get event codes and other metadata.
      • Fetch up to 500 tracking events in cursor fashion.
      • Get tracking events by the list of parcel numbers, up to 50, comma separated.
      • Get tracking events by the list of sender reference numbers, up to 50, comma separated.
      • Get tracking events by the list of parcel numbers or sender reference numbers, up to 50, comma separated.
      • Upload tracking events file.
      • Get bag tracking events by the list of bag numbers, up to 50, comma separated.
      • Get bag tracking events by the list of bag numbers or shipment numbers, up to 50, comma separated.
    • Accounts
      • Get current account details.
    • Integrations
      • Add up to 500 tracking events to the processing queue. The whole batch either succeeds or fails.
      • Add tracking event with generic payload.
  1. Scenarios And Workflows

Query parcel tracking events

Overview of tracking related endpoints: Tracking Endpoints

šŸ“Œ Request Rate Limits
PostPlus API applies rate limiting (normally 5 requests per second), so integrators must use batch operations whenever possible, not one-by-one.

Query parcel tracking events#

There are multiple ways of retrieving tracking information, described below:
Get tracking events by the list of parcel numbers, up to 50, comma separated.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890

### fetch by multiple parcel nrs
GET {{host}}/api/v1/tracking/parcel-nrs/get-many?ParcelNrs=PARCEL-NR-1,PARCEL-NR-2
X-API-KEY: {{apiKey}}
Get tracking events by the list of sender reference numbers, up to 50, comma separated.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890

### fetch by multiple sender parcel nrs
GET {{host}}/api/v1/tracking/sender-parcel-nrs/get-many?SenderParcelNrs=SENDER-NR-1,SENDER-NR-2
X-API-KEY: {{apiKey}}
Fetch up to 500 tracking events in cursor/stream fashion.
fetch trackig data in a batch (page) stating from a given date and cursor (fetchId)
retrieval of the next page is done by suppling the correct fercthId parameter, see below
startDate=[absolute start date, works with conjunction with fetcIh id parameter]
fetchId=[leave empty for the very first call or take from previous response "nextFetchId" value]
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890

### first request with empty fetchId
GET  {{host}}/api/v1/tracking?startDate=2025-01-01&count=200&fetchId=
X-API-KEY: {{apiKey}}
snippet of response from the first request
HTTP/1.1 200 OK
Content-Length: 74988

{
  "nextFetchId": "Cj7tmDjWkdoUyVmb8R8B77",
  "fetchDone": false,
  "events": [
    {
      "parcel": {
        "parcelNr": "PARCEL-NR-1",
        "senderParcelNr": "13111315031",
        "destinationCountry": "EE",
        "carrier": "TestCarrier",
        "carrierParcelNr": "PARCEL-NR-1"
      },
      "event": {
        "eventId": "WoxFW73f47o2d55PPHwzit",
        "eventTime": "2025-01-13T01:56:27+00:00",
        "eventVersion": "332002",
        "eventCode": "CREATE_OR_UPDATE",
        "eventMessage": "Parcel data received or updated",
        "eventLocation": "PPLUS"
      }
    }]
}
### next request with fetchId from the previus response ("nextFetchId": "Cj7tmDjWkdoUyVmb8R8B77")
GET {{host}}/api/v1/tracking?startDate=2025-01-01&count=200&fetchId=Cj7tmDjWkdoUyVmb8R8B77
X-API-KEY: {{apiKey}}

### and so on

Query PostPlus event codes, messages and other metadata#

Get event codes and other metadata
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890

### Trackig event codes metadata
GET {{host}}/api/v1/tracking/event-codes
X-API-KEY: {{apiKey}}

Importing tracking events to PostPlus system#

Add up to 500 tracking events to the processing queue. The whole batch either succeeds or fails.
The example import payload contains 2 events, one with explicit eventId and one with auto-generated (autogenraed based on event time, event parcel number etc).
When integrators have their own unique tracking event ids, they can provide them in eventId parameter, and so the subsequent request with same eventId will update the exiting event instead of creating a new one.
@host = https://api.test.post-plus.io
@integrationApiKey = "integration-api-key-12345"
    
POST {{host}}/api/v1/integrations/tracking-import
content-type: application/json
X-API-KEY: {{integrationApiKey}}

{
  "events": [
    {
      "eventId": "SomeExternalSourceUNiqueEventId012356",
      "eventSourceAlt": "SomeExternalSource",
      "eventCode": "DELIVERED",
      "eventMessage": "Delivered to the recipient",
      "eventTime": "2024-04-04 04:04:00",
      "eventLocation": "Location",
      "trackingNr": "PARCEL-NR-1"
    },
    {
      "eventSourceAlt": "SomeExternalSource",
      "eventCode": "DELIVERED",
      "eventMessage": "Delivered to the recipient",
      "eventTime": "2024-04-04 04:04:00",
      "eventLocation": "Location",
      "trackingNr": "PARCEL-NR-2"
    }
  ]
}
Add tracking event with generic/custom payload.
This endpoint should be used by the agreement with PostPlus when events in custom format are inserted into the queue and then processed by the custom logic implmented by the PostPlus.
@host = https://api.test.post-plus.io
@integrationApiKey = integration-api-key-12345
        
POST {{host}}/api/v1/integrations/tracking-import-generic?DataSource=IntegratorName
content-type: application/json
X-API-KEY: {{integrationApiKey}}

{
  "integratorEventCode": "deliveredCode",
  "integratorEventMessage": "parcel was delivered",
  "date": "2025-01-01"
}
Previous
Manifesting parcels in bags and shipments
Next
Create or update single parcel.
Built with