Manifesting parcels in bags and shipments
Overview of shipment related endpoints: Shipments Endpoints
Workflow overview
Full step-by-step workflow
1.
2.
3.
4.
Simplified two-step workflow
1.
2.
3.
Full step-by-step workflow
Create shipment
Start by creating a shipment record at your terminal. A shipment represents a transport unit that will contain one or more bags of parcels.Save the returned updateIfExists flag Use
When updating:
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/shipments
content-type: application/json
X-API-KEY: {{apiKey}}
{
"type": "AWB",
"terminalCode": "AMS",
"shipmentNr": "999-68495221",
"updateIfExists": true
}id for subsequent calls.updateIfExists: true for retry-safe (idempotent) operations - prevents duplicate shipment errors in retry scenarios or batch processing systems.| Value | Behavior |
|---|---|
false (default) | Fails if shipmentNr already exists |
true | Updates existing shipment or creates new one |
type and terminalCode must match the existing shipment. Shipment must be in Created or Manifested status.Link parcels to shipment
Once parcels are created and packed into bags, link them to the shipment by updating their references. This assigns parcels to specific bags within the shipment. Call once per bag.Repeat for each bag with different destination or grouping. Use consistent bag naming (e.g., allowPartialSuccess flag Use
Always check
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/parcels/update-references-many
content-type: application/json
X-API-KEY: {{apiKey}}
{
"parcelNrs": "RF000000028LT,RF000000031LT,RF000000045LT",
"updateBagNr": "BAG-NL-001",
"linkShipmentId": {{shipmentId}},
"allowPartialSuccess": true
}BAG-{COUNTRY}-{SEQUENCE}).allowPartialSuccess: true when processing large batches where some failures are acceptable.| Value | Behavior |
|---|---|
false (default) | Entire operation fails if any parcel is invalid |
true | Valid parcels updated; failed ones returned in failedParcels |
failedParcels in the response and implement retry logic for failed items.Update shipment details
Before validation, add transport and arrival information to the shipment.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
PUT {{host}}/api/v1/shipments/{{shipmentId}}
content-type: application/json
X-API-KEY: {{apiKey}}
{
"masterNr": "MAWB-12345678",
"arrivalInfo": {
"transportNr": "CA1024",
"originCountryCode": "US",
"totalWeight": 125.5,
"totalBags": 3,
"arrivalOn": "2024-12-15T10:00:00Z",
"notes": "Handle with care"
}
}Validate shipment
Prepare the shipment to validate all data before submission.Returns Handling errors If validation fails ( Common errors and solutions: Arrival info missing ā Update shipment with arrival details Bag too heavy ā Split parcels across multiple bags Parcel errors ā Fix or cancel individual parcels After fixing issues, call prepare again until validation passes.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/shipments/{{shipmentId}}/prepare
content-type: application/json
X-API-KEY: {{apiKey}}
{
}shipmentSubmitToken needed for submission.hasErrors: true), check shipment details for specific error messages:GET {{host}}/api/v1/shipments/{{shipmentId}}?IncludeBags=true
X-API-KEY: {{apiKey}}Submit shipment
After successful validation, submit the shipment. Once submitted, the shipment is locked and cannot be modified.After submission, the shipment enters Pending status. CN documents can be generated, and AWB/MAWB/CMR numbers remain editable.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/shipments/{{shipmentId}}/submit
content-type: application/json
X-API-KEY: {{apiKey}}
{
"shipmentSubmitToken": "{{shipmentSubmitToken}}"
}Upload AWB/CMR documents
Some terminals require AWB or CMR documents to be attached before the shipment can be scheduled for handling. Without these documents, the shipment remains in Pending status and will not enter the handling schedule.
See Requirement to attach AWB/CMR documents and automatic email pre-alerts for full details on this requirement.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/shipments/{{shipmentId}}/shipment-documents?Type=AWB&FileName=awb-document.pdf
content-type: multipart/form-data
X-API-KEY: {{apiKey}}
// file: [binary content]Download documents
Documents (CN35, CN38) are generated asynchronously after submission. Poll shipment details until documents are available.Get shipment details Download all documents as archive Download manifest as CSV
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
GET {{host}}/api/v1/shipments/{{shipmentId}}?IncludeDocuments=true
X-API-KEY: {{apiKey}}GET {{host}}/api/v1/documents/shipments/{{shipmentId}}/all-documents
X-API-KEY: {{apiKey}}GET {{host}}/api/v1/documents/shipments/{{shipmentId}}/resulting-file?fileFormat=Csv
X-API-KEY: {{apiKey}}Delete shipment
Shipments can only be deleted before submission. This removes the shipment and all related data.
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
DELETE {{host}}/api/v1/shipments/{{shipmentId}}
X-API-KEY: {{apiKey}}Simplified two-step workflow
Simplified Step 1: Create shipment
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/shipments
content-type: application/json
X-API-KEY: {{apiKey}}
{
"type": "AWB",
"terminalCode": "AMS",
"shipmentNr": "999-68495221",
"masterNr": "MAWB-12345678",
"arrivalInfo": {
"transportNr": "CA1024",
"originCountryCode": "US",
"totalWeight": 125.5,
"totalBags": 3,
"arrivalOn": "2024-12-15T10:00:00Z"
},
"updateIfExists": true
}Simplified Step 2: Manifest and submit
@host = https://api.test.post-plus.io
@apiKey = apitest1234567890
POST {{host}}/api/v1/shipments/{{shipmentId}}/manifest-and-submit
content-type: application/json
X-API-KEY: {{apiKey}}
{
"bags": [
{
"bagNr": "BAG-NL-001",
"parcelNrs": "RF000000028LT,RF000000031LT,RF000000045LT"
},
{
"bagNr": "BAG-DE-001",
"parcelNrs": "RF000000059LT,RF000000062LT"
}
]
}