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

Create or update parcel record

Overview of parcel related endpoints: Parcels Endpoints
While creating parcels in our system, it is possible to create a single parcels or several at once. The payload is similar in both cases
Example payload for Create or update single parcel:
It is recommended to start with the basic request and update the other fields step by step.
The system uses the identifiers to check if there is an existing parcel record with these identifiers.
In case the parcel with the same identifiers already exists, each next request will be updating the parcel record.
In case the parcel record gets an error, resending the request with the same identifiers and modified receiver data, for example, can be used to resolve the issues.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890

PUT {{host}}/api/v1/parcels
content-type: application/json
X-API-KEY: {{apiKey}}

{
  "identifiers": {
    "senderParcelNr": "Test-SE-0036"
  },
  "parcel": {
    "transactionType": "B2C",
    "parcelGrossWeight": 0.15,
    "currency": "USD",
    "items": [
      {
        "description": "plastic toy",
        "hsCode": "950300",
        "quantity": 1,
        "valuePerItem": 0.1,
        "weightPerItem": 0.1
      }
    ]
  },
  "additionalInfo": {
    "serviceCode": "UZPO-PRIME"
  },
  "receiver": {
    "name": "A test consignee",
    "phone": "+123456",
    "address": "Skeppsbron 5-1",
    "zipCode": "41121",
    "city": "GÖTEBORG",
    "countryCode": "SE"
  }
}
For a better overview, the request content has been split here by payload sections.

First section “identifiers”:#

{
  "identifiers": {
    "senderParcelNr": "Test-SE-0036",
    "parcelNr": "LP00000005PP"
  },
  "parcel": {...},
  "additionalInfo": {...},
  "receiver": {...}
}
It can include the following parcel identifiers:
senderParcelNr is the client’s reference to this specific parcel. This must be unique throughout all the created parcels. (Client can use their order number or generate a unique code that they can use to recognize the parcel.) If the parcelNr is left empty, this must be filled.
parcelNr – there are some cases where an offline parcel number range is provided. In these cases, the UPU format parcel number should be added to this field. If this is not the case, the parcelNr will be generated and provided by PostPlus.

Next section "parcel" contains info about the parcel itself:#

{
  "identifiers": {...},
  "parcel": {
    "transactionType": "B2C",
    "parcelGrossWeight": 0.15,
    "currency": "USD",
    "items": [
      {
        "description": "plastic toy",
        "hsCode": "950300",
        "skuCode": "ABC123",
        "quantity": 1,
        "valuePerItem": 0.1,
        "weightPerItem": 0.1
      }
    ]
  },
  "additionalInfo": {...},
  "receiver": {...}
}
transactionType is B2C as default. Other option is C2C in which case the sender information section needs to be filled.
Parcel value and parcel weight are calculated based on the items inside the parcel by adding up all the quantity times value/weight for each item. (Please note that you can also specify parcelGrossWeight property value, which must be equal to or greater than the sum of all items' weight because of packaging but it can never be lower.) There is a currency field, which also applies to the item level: all the items inside the parcel need values in the same currency.

items subsection has the item information:#

description should be filled, skuCode is optional.
hsCode is not a mandatory field but should be filled if possible. There might be situations where this is needed and if it is not provided, our system would try to add it based on the description. This might not be optimal. (6-10 characters)
quantity is how many of the same item is inside the parcel, value and weight are indicated based on one singular item. There can be more than one different item inside the parcel. In these cases, this section needs to be duplicated per each different item.

Next section is "additionalInfo":#

This section contains important information about product type (serviceCode property) tax type and tax identification.
{
  "identifiers": {...},
  "parcel": {...},
  "additionalInfo": {
    "serviceCode": "UZPO-PRIME",
    "taxType": "DDU",
    "taxIdentification": ""
  },
  "receiver": {...}
}
serviceCode - service or product identifier, used for explicit service selection, instead of relying on automatic selection by the system.
taxType determines how PostPlus will receive these goods. Possible tax type options include:
Empty – blank value is intended for shipments to non-EU destinations under DDU.
DDU – these parcels will not be customs cleared in AMS, but by destination post. VAT and service fee to be paid by addressee.
DDP – the parcels of these manifest lines will arrive to AMS terminal already customs cleared by third party appointed by the client.
IOSS – the parcels with IOSS will be customs cleared by PostPlus, VAT to be paid by IOSS number holder.
VOEC – applies to destination Norway.
TAXID – applies to other Non-EU destinations such as CH.
taxIdentification property:
If tax type is empty, tax identification should be empty
In case of DDU, empty or other tax identification
DDP – empty
Tax identification IOSS should always be accompanied by a valid IOSS number
Tax type VOEC should be accompanied by a valid VOEC number
Tax type TAXID should be accompanied by a valid tax identification number agreed with PostPlus

Next up we have the consignee ("receiver") information, where will this parcel be shipped to:#

{
  "identifiers": {...},
  "parcel": {...},
  "additionalInfo": {...},
  "receiver": {
    "name": "A test consignee",
    "phone": "+123456",
    "address": "Skeppsbron 5-1",
    "zipCode": "41121",
    "city": "GÖTEBORG",
    "countryCode": "SE"
  }
}
The consignee information consists of columns like name, phone number, email, address, zip code, city, state, and country code (2 characters). In the case of non-postal channels, either phone number or email is always required.

Next up we have the optoinal consignor ("sender") information, where will this parcel be shipped to:#

When trsansactionType is C2C sender section must be included in the request. The ection consists of attributes like name, phone number, email, address, zip code, city, state, and country code (2 characters).
{
  "identifiers": {...},
  "parcel": {...},
  "additionalInfo": {...},
  "receiver": {...},
  "sender": {
    "name": "A test consignor",
    "phone": "+123456",
    "address": "Skeppsbron 5-1",
    "zipCode": "41121",
    "city": "GÖTEBORG",
    "countryCode": "SE"
  }
}

The next section indicates the status of the parcel:#

Setting isCancelled to true, will cancel this parcel record. Once parcel data has been added to the system, either via manifest file or API, a parcel record is created. This record will remain in the system and will be marked as cancelled when on subsequent requests isCancelled property is set to true.
{
  "identifiers": {...},
  "parcel": {...},
  "receiver": {...},
  "additionalInfo": {...},
  "status": {
    "isCancelled": true
  }
}
Cancelling the parcel is necessary when you want to switch the product type for example, and you cancel sending this via postal channels and intend to upload the same sender parcel number to a non-postal channel. Since this sender parcel number currently has a generated parcel number, there's no possibility of generating a new non-postal parcel number for this before cancelling this specific record.
Previous
Working with parcels
Next
Cancel or delete a parcel record
Built with