Parcels via API

Test files with examples: Postal & Non-postal

There are several endpoints in the Parcels part in swagger. Short descriptions are provided there.

While creating parcels in our system, it would make sense to create several at once. Endpoint create-or-update-many allows us to create up to 200 parcels in one request.

Full request can be viewed in Swagger. 

However, the example request below has all the necessary information for most of the cases and the integrator shall start with the similar request and extend if needed:

For a better overview, the request content has been split here by topic/fields:

The example request starts with shipmentId - at this point, the shipment has not been created yet, so this field can be left out from the initial request.

Next up we have parcel information, first section “identifiers” has three fields:

1. ID is generated by the system once the request has been sent
2. 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.
3. 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. 

Second section “references” has only one field: bagNr, which is there to indicate which bag this parcel can be found in. This can be left empty and updated after the packing and sorting has been done.

Next section contains info about the parcel itself. The first field is type, which indicates the mail type.

Possible values are:

• EMS
• NonPostal
• NotRegistered (default if left empty)
• ParcelUPU
• Premium
• Prime
• Registered
• SRM

The mail type is connected to the product that will be used – this information will be provided by your account manager once on-boarding.

Transaction type 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 the parcel gross weight can be higher 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.

The next section 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.

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. 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.

Next up we have the consignee (receiver) information. Where will this parcel be shipped to?

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.

After that, there's a section for consignor (sender) information:

Fields for the sender information are the same as for receiver information. This is optional in case of B2C, but can be filled. In some cases, it's possible to forward the sender information, to display to the consignee who the consignor is. In the case of B2C, the name field should contain the company name, other fields contain contact information (email or phone number) and the address information.

Next section is called “additional info”. This section contains important information about tax type and tax identification.

Tax type determines how PostPlus will receive these goods. Possible tax type options include:

1. Empty – blank value is intended for shipments to non-EU destinations under DDU.

2. DDU – these parcels will not be customs cleared in AMS, but by destination post. VAT and service fee to be paid by addressee.

3. DDP – the parcels of these manifest lines will arrive to AMS terminal already customs cleared by third party appointed by the client.

4. IOSS – the parcels with IOSS will be customs cleared by PostPlus, VAT to be paid by IOSS number holder.

5. VOEC – applies to destination Norway.

Tax identification number:

1. If tax type is empty, tax identification should be empty

2. In case of DDU, empty or other tax identification

3. DDP – empty

4. Tax identification IOSS should always be accompanied by a valid IOSS number

5. Tax type VOEC should be accompanied by a valid VOEC number

ServiceCode - additional service identifier, used for explicit service selection, instead of realying on automatic selection by the system.

Ordinal – for cases where you want to get the labels in the same order as these were manifested, you can specify the order.

Route info in this section will usually be left empty, unless specified otherwise by your account manager.

Taking all of this into consideration, it is sufficient to only use these fields in the initial parcel creation process:

It is recommended to start with the minimal request and update the other fields step by step. The rest of the fields can be updated later by using the same identifiers (Parcel number, ID, Client ID). The system uses the identifiers to check if there is a parcel record with these. In case yes, each next request will be updating the parcel record. In case the parcel record gets an error, the update option can be used to resolve the issues.

To get a parcel information, this endpoint can be used with the parcel ID:

api/v1/parcels/{{parcelId}}?IncludeReceiver=true&IncludeItems=true&IncludePrints=true

There might be cases where the parcel record needs to be cancelled or deleted. 

Deleting the parcel record means that in case it was to a postal channel, the parcel will be permanently deleted and in case of a non-postal channel, it will be cancelled.

Cancelling a parcel means that this parcel record is discarded, but remains in the system as information. When the parcel will be cancelled, a suffix will be added at the end of both Sender parcel number and Parcel number. The sender parcel number can be then used again.

When would it be necessary to cancel the parcel? For example, if the client wants to switch from non-postal to postal. Since both have different parcel number formats, a new record needs to be created and the old one can be discarded. It's not possible to update the parcel to switch between non-postal and postal service, if the first parcel creation didn't get an error. Thus the existing record should be cancelled to be switched to another product.

Once the parcel is generated successfully, we can get the parcel label out via these endpoints:

To get the label in base64, use

GET /api/v1/parcels/parcel-prints/{{labelId}}?IncludeContents=true

To get the label in direct content output, use

GET {{host}}/api/v1/documents/parcel-prints/{{labelId}}

where the labelId is the ID from the parcel creation response "prints" section.

After the parcel labels have been created and fetched, packing and sorting can start. Once the client has generated bag codes and knows which parcel went to which bag, the bag reference can be updated. It would make sense to create the shipment first, so the link to shipment and bag could be added with one request.

Next up, let’s see how to create a Shipment.