PostPlus API
  1. Parcels
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.
        PUT
      • Create or update up to 200 parcels in a single request.
        POST
      • Get parcel details by parcel Id.
        GET
      • Get up to 100 parcels details by parcel Ids.
        GET
      • Get parcel details by parcel number (tracking number).
        GET
      • Get up to 100 parcels details by parcel numbers (tracking numbers).
        GET
      • Get parcel details by sender reference number.
        GET
      • Get up to 100 parcel details by sender reference numbers.
        GET
      • Query up to 500 parcels.
        GET
      • Delete parcel by Id.
        DELETE
      • Delete up to 100 parcels by Ids.
        DELETE
      • Get print details and contents by print Id.
        GET
      • Get up to 100 parcel print details and contents by print Ids.
        GET
      • Get pickup point details by Id.
        GET
      • Query pickup points.
        GET
      • Group parcels into bags and link to a shipment (update parcel references).
        POST
      • Get parcel details by manifest reference numbers.
        GET
      • Get up to 100 parcel details by manifest reference numbers.
        GET
      • Get parcel details by carrier reference numbers.
        GET
      • Get up to 100 parcel details by carrier reference numbers.
        GET
    • 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. Parcels

Create or update single parcel.

PUT
https://api.test.post-plus.io/api/v1/parcels
Parcels

Request

Authorization
Add parameter in header
Example:
X-Token: ********************
Header Params
Content-Type
string 
optional
Default:
application/json
Accept
string 
optional
Default:
application/json
X-API-KEY
string 
optional
Default:
apitest1234567890
Body Params application/json
shipmentId
integer <int64> | null 
optional
Optional shipment id to assign parcel to
identifiers
object (CreateOrUpdateParcelIdentifiers) 
required
id
integer <int64>
optional
Post+ parcel id, auto-generated
Example:
1234
parcelNr
string  | null 
optional
Unique tracking number of the parcel (for example UPU S10 for postal parcels). Auto-generated if not specified when parcel is created.
<= 50 characters
Example:
RS12345678US
senderParcelNr
string  | null 
optional
Sender internal refernce number, must be unque if present. Must not be empty if ParcelNr is not specified.
<= 50 characters
Example:
client-id-123
originalParcelNr
string  | null 
optional
Unique number of originating parcel in case of return resolution or resending/relabelling
originalSenderParcelNr
string  | null 
optional
Sender internal refernce number of originating parcel in case of return resolution or resending/relabelling
references
object (CreateOrUpdateParcelReferences) 
optional
bagNr
string  | null 
optional
Bag reference number.
<= 50 characters
Example:
bag-001
parcel
object (CreateOrUpdateParcelInfo) 
optional
type
string  | null 
optional
Parcel type. Optional when ServiceCode is provided, otherwise mandatory. For non-postal channels: NonPostal. For postal channels: Registered, NotRegistered, SRM, Prime, EMS, Premium, ParelUPU
Example:
NonPostal
transactionType
enum<string> 
optional
Allowed values:
B2CC2CMixed
parcelValue
number <double>
optional
Total parcel value
Example:
1.25
currency
string  | null 
optional
Currency symbol, optinal, default USD
parcelGrossWeight
number <double>
optional
Total parcel gross weight in kilograms
Example:
0.125
height
integer <int32> | null 
optional
Parcel Height in cm
width
integer <int32> | null 
optional
Parcel Width in cm
length
integer <int32> | null 
optional
Parcel Length in cm
items
array[object (CreateOrUpdateParcelItemInfo) {6}]  | null 
required
status
object (CreateOrUpdateParcelStatusInfo) 
optional
isCancelled
boolean 
optional
Flag sets whether parcel should be cancelled
Default:
false
receiver
object (CreateOrUpdateParcelReceiverInfo) 
optional
Parcel receiver
name
string 
required
Full name.
>= 1 characters<= 100 characters
phone
string  | null 
optional
Phone number.
<= 50 characters
email
string  | null 
optional
Email.
<= 100 characters
address
string 
required
Address
>= 1 characters<= 200 characters
zipCode
string 
required
Zip code
>= 1 characters<= 30 characters
city
string 
required
City
>= 1 characters<= 100 characters
state
string  | null 
optional
State (region, county)
<= 100 characters
countryCode
string 
required
2-digit iso country code.
>= 2 characters<= 2 characters
pickupPointId
integer <int32> | null 
optional
Pickup Point Id for PUDO delivery
sender
object (CreateOrUpdateParcelSenderInfo) 
optional
Parcel receiver
name
string  | null 
optional
Full name.
<= 100 characters
phone
string  | null 
optional
Phone number.
<= 50 characters
email
string  | null 
optional
Email.
<= 100 characters
address
string  | null 
optional
Address
<= 200 characters
zipCode
string  | null 
optional
Zip code
<= 30 characters
city
string  | null 
optional
City
<= 100 characters
state
string  | null 
optional
State (region, county)
<= 100 characters
countryCode
string  | null 
optional
2-digit iso country code.
>= 2 characters<= 2 characters
additionalInfo
object (CreateOrUpdateParcelAdditionalInfo) 
optional
taxType
string  | null 
optional
Tax type
<= 30 characters
taxIdentification
string  | null 
optional
Tax identification
<= 50 characters
routeInfo
string  | null 
optional
Route info
<= 250 characters
shipDate
string <date-time> | null 
optional
Ship date
serviceCode
string  | null 
optional
Service code. Optional when parcel Type is porvided, otherwise mandatory
<= 100 characters
ordinal
integer <int32> | null 
optional
Ordinal postition of parcel withing the batch
Example

{
  "identifiers": {
    "senderParcelNr": "Test-SE-0037" 
  },
  "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",
    "taxType":"DDU",
    "taxIdentification":""
  },
  "receiver": {
    "name": "A test consignee",
    "phone": "+123456",
    "address": "Skeppsbron 5-1",
    "zipCode": "41121",
    "city": "GÖTEBORG",
    "countryCode": "SE"
  }
}

Request samples

Shell
JavaScript
Java
Swift
Go
PHP
Python
HTTP
C
C#
Objective-C
Ruby
OCaml
Dart
R
Request Request Example
Shell
JavaScript
Java
Swift
curl --location --request PUT 'https://api.test.post-plus.io/api/v1/parcels' \
--header 'Accept: application/json' \
--header 'X-API-KEY: apitest1234567890' \
--header 'Content-Type: application/json' \
--data-raw '{
  "identifiers": {
    "senderParcelNr": "Test-SE-0037" 
  },
  "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",
    "taxType":"DDU",
    "taxIdentification":""
  },
  "receiver": {
    "name": "A test consignee",
    "phone": "+123456",
    "address": "Skeppsbron 5-1",
    "zipCode": "41121",
    "city": "GÖTEBORG",
    "countryCode": "SE"
  }
}'

Responses

🟢200OK
text/plain
Success
Body
identifiers
object (ParcelIdentifiers) 
optional
id
integer <int64>
optional
Post+ parcel id, auto-generated
Example:
1234
parcelNr
string  | null 
optional
Parcel tracking number, typically UPU S10 generated by client or other
Example:
RS12345678US
senderParcelNr
string  | null 
optional
Sender internal refernce number in addition to UPU S10 ParcelNr, must be unque if present. Must not be empty if ParcelNr is not specified.
Example:
client-id-123
references
object (ParcelReferences) 
optional
shipmentId
integer <int64>
optional
Post+ parcel id, auto-generated.
shipmentNr
string  | null 
optional
Shipment reference number or document number.
Example:
123-000000123
bagNr
string  | null 
optional
Bag reference number.
Example:
bag-001
externalIds
array[string] | null 
optional
Parcel references in third-party systems, if any.
Example:
1234567890
carrier
string  | null 
optional
Carrier
carrierParcelNr
string  | null 
optional
Carrier/external parcel number
manifestParcelNr
string  | null 
optional
Parcel number as manifested by customer, usually a scanned barcode
printId
integer <int64> | null 
optional
Id of last parcel print, if any.
Example:
1234567890
status
object (ParcelStatusInfo) 
optional
hasErrors
boolean 
optional
Whether there are errors associated with the parcel.
errorDetails
array[string] | null 
optional
List of error messages
hasWarnings
boolean 
optional
Whether there are warnings associated with the parcel.
isCancelled
boolean 
optional
parcel is cancelled
Default:
false
warningDetails
array[string] | null 
optional
List of warning messages
status
enum<string> 
optional
Allowed values:
CreatedImportedManifestedDeleted
createdOn
string <date-time>
optional
Created timestamp
parcel
object (ParcelInfo) 
optional
type
enum<string> 
optional
Allowed values:
NotRegisteredRegisteredPrimeEMSPremiumSRMParcelUPUNonPostal
destinationCountryCode
string  | null 
optional
2-digit iso country code
Example:
NL
transactionType
enum<string> 
optional
Allowed values:
B2CC2CMixed
parcelItems
integer <int32>
optional
Number of SKU's in the parcel.
Example:
1
parcelValue
number <double>
optional
Total parcel value
Example:
1.25
currency
string  | null 
optional
Currency symbol
Example:
USD
parcelGrossWeight
number <double>
optional
Total parcel gross weight in kilograms
Example:
0.125
height
integer <int32> | null 
optional
Parcel Height in cm
width
integer <int32> | null 
optional
Parcel Width in cm
length
integer <int32> | null 
optional
Parcel Length in cm
items
array[object (ParcelItemInfo) {6}]  | null 
optional
receiver
object (ParcelReceiverInfo) 
optional
name
string  | null 
optional
Full name.
phone
string  | null 
optional
Phone number.
phoneNormalized
string  | null 
optional
Normalized phone number.
email
string  | null 
optional
Email.
address
string  | null 
optional
Address.
zipCode
string  | null 
optional
Zip cde.
city
string  | null 
optional
City.
state
string  | null 
optional
State (region, county)
countryCode
string  | null 
optional
2-digit iso country code.
pickupPointId
integer <int32> | null 
optional
Pickup Point Id for PUDO delivery
sender
object (ParcelSenderInfo) 
optional
name
string  | null 
optional
Full name.
phone
string  | null 
optional
Phone number.
phoneNormalized
string  | null 
optional
Normalized phone number.
email
string  | null 
optional
Email.
address
string  | null 
optional
Address.
zipCode
string  | null 
optional
Zip cde.
city
string  | null 
optional
City.
state
string  | null 
optional
State (region, county)
countryCode
string  | null 
optional
2-digit iso country code.
additionalInfo
object (ParcelAdditionalInfo) 
optional
taxType
string  | null 
optional
Tax type
taxIdentification
string  | null 
optional
Tax identification
routeInfo
string  | null 
optional
Route info
shipDate
string <date-time> | null 
optional
Ship date
serviceCode
string  | null 
optional
Additional service code
ordinal
integer <int32> | null 
optional
Ordinal postition of parcel withing the batch
prints
array[object (ParcelPrintInfo) {9}]  | null 
optional
id
integer <int64>
optional
Post+ parcel id, auto-generated
Example:
1234
format
enum<string> 
optional
Allowed values:
PdfZpl
type
enum<string> 
optional
Allowed values:
PostalLabelExtProviderLabel
subTypes
array[string] | null 
optional
Print subtypes.
provider
string  | null 
optional
Print provider.
Example:
ExtProvider,Postal
bytes
integer <int32>
optional
Print file - number of bytes.
content
string  | null 
optional
Print file content, base64 encoded.
hasErrors
boolean 
optional
Whether there are errors associated with the print file.
errorDetails
array[string] | null 
optional
List of error messages
Example
{
    "identifiers": {
        "id": 1234,
        "parcelNr": "RS12345678US",
        "senderParcelNr": "client-id-123"
    },
    "references": {
        "shipmentId": 0,
        "shipmentNr": "123-000000123",
        "bagNr": "bag-001",
        "externalIds": 1234567890,
        "carrier": "string",
        "carrierParcelNr": "string",
        "manifestParcelNr": "string",
        "printId": 1234567890
    },
    "status": {
        "hasErrors": true,
        "errorDetails": [
            "string"
        ],
        "hasWarnings": true,
        "isCancelled": false,
        "warningDetails": [
            "string"
        ],
        "status": "Created",
        "createdOn": "2019-08-24T14:15:22Z"
    },
    "parcel": {
        "type": "NotRegistered",
        "destinationCountryCode": "NL",
        "transactionType": "B2C",
        "parcelItems": 1,
        "parcelValue": 1.25,
        "currency": "USD",
        "parcelGrossWeight": 0.125,
        "height": 0,
        "width": 0,
        "length": 0,
        "items": [
            {
                "description": "Tennis ball",
                "skuCode": "sku-123",
                "hsCode": "711319",
                "quantity": 1,
                "valuePerItem": 1.25,
                "weightPerItem": 0.125
            }
        ]
    },
    "receiver": {
        "name": "string",
        "phone": "string",
        "phoneNormalized": "string",
        "email": "string",
        "address": "string",
        "zipCode": "string",
        "city": "string",
        "state": "string",
        "countryCode": "string",
        "pickupPointId": 0
    },
    "sender": {
        "name": "string",
        "phone": "string",
        "phoneNormalized": "string",
        "email": "string",
        "address": "string",
        "zipCode": "string",
        "city": "string",
        "state": "string",
        "countryCode": "string"
    },
    "additionalInfo": {
        "taxType": "string",
        "taxIdentification": "string",
        "routeInfo": "string",
        "shipDate": "2019-08-24T14:15:22Z",
        "serviceCode": "string",
        "ordinal": 0
    },
    "prints": [
        {
            "id": 1234,
            "format": "Pdf",
            "type": "PostalLabel",
            "subTypes": [
                "string"
            ],
            "provider": "ExtProvider,Postal",
            "bytes": 0,
            "content": "string",
            "hasErrors": true,
            "errorDetails": [
                "string"
            ]
        }
    ]
}
Previous
Query parcel tracking events
Next
Create or update up to 200 parcels in a single request.
Built with