Book a parcel
Learn about the Booking endpoint to register a parcel shipment.
Overview
The purpose of this API is to register a parcel shipment from a consignor (private person or a shop) to a consignee (private person or a shop). The object in the request body uses “parties” to define the sender and receiver.
-
Consignor - Entity sending a parcel
-
Consignee - Entity receiving a parcel
Use this endpoint for B2C, C2B, and C2C shipments. The basic methods and requests are outlined below with descriptions and examples.
You control the delivery behavior via the Transport Solution, make sure to read the guide on Delivery Methods to understand these first.
Booking request structure
A booking request contains 4 primary data points to control it:
-
Shop Id - The shop that is booking the order.
-
Transport Solution - The booked transport solution.
-
Parties - Consignor, Consignee.
-
Items - Description, dimensions and weight.
Business to consumer - B2C
Party types
-
consignor= Business -
consignee= Consumer -
servicePoint= Selected Service Point.
Example 1: Booking a B2C parcel
In this example, we will use transportSolutionId:"1". Helthjem has coverage over 100% of Norway. The response will include one of the following options, depending on address:
|
Transport Solution |
Freight products |
Description |
|---|---|---|
|
|
|
Primary: Home delivery Fallback 1: Service point (Helthjem) Fallback 2: Service point (Postnord) |
Request example
{
"shopId": 1,
"transportSolutionId": 1,
"shipmentId": "",
"parties": [
{
"type": "consignee",
"name": "Test Customer",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0566",
"address": "Fjellgata 48",
"phone1": "53582094",
"email": "testcustomer@test.com",
"reference": "cust_ref",
"contact": "contact2"
},
{
"type": "consignor",
"name": "Test shop",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0480",
"address": "Sandakerveien 121",
"phone1": "",
"contact": "contact1",
"reference": "shop_ref",
"email":""
}
],
"items": [
{
"itemNumber": 1,
"trackingReference": "",
"weight": 1000,
"width": 12,
"height": 12,
"length": 12,
"contents": "test item"
}
]
}Response
{
"shipmentId": "(401)70724762337121945",
"freightProductId": 1,
"parties": [
{
"type": "consignee",
"id": null,
"name": "Test Customer",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0566",
"address": "Fjellgata 48",
"phone1": "53582094",
"phone2": null,
"email": "testcustomer@test.com",
"reference": "cust_ref",
"contact": "contact2",
"coaddress": null
},
{
"type": "consignor",
"id": null,
"name": "Test shop",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0480",
"address": "Sandakerveien 121",
"phone1": "",
"phone2": null,
"email": "",
"reference": "shop_ref",
"contact": "contact1",
"coaddress": null
}
],
"items": [
{
"itemNumber": 1,
"trackingReference": "(00)370724762337121953",
"returnCode": null,
"linkedParcelType": null,
"linkedTrackingReference": null,
"weight": 1000,
"volume": null,
"length": 12.0,
"height": 12.0,
"width": 12.0,
"contentValue": null,
"externalSupplierId": null,
"contents": "test item",
"properties": {
"shortItemIdentifier": "...1953"
},
"articles": [],
"externalOrderId": null
}
],
"properties": {
"areaId": "59",
"freightProductName": "helthjem",
"mainCarNumber": "14",
"pickupZipString": "0556 OSLO",
"productName": "helthjem standard",
"regionId": "189",
"routeAddress": "TOFTES GATE 21 B",
"routeDescription": "BUDSENTRAL RINGNES PARK",
"routeName": "22140",
"routeSeq": "121",
"routeZipAndCity": null,
"routing": "14-0-x22140x121",
"routingCode": "1",
"routingDescription": "RINGNES PARK",
"routingDetailed": "14 - RINGNES PARK",
"shopName": "Testbutikken",
"transportCompanyId": "1",
"transportNetId": "223"
},
"additionalServices": [],
"orderId": 89828037
}
In this example, we get the response containing freightProduct:"1", which tells us that the parcel has been successfully booked with home delivery.
Example 2: Booking B2C to a service point
If you need to make a booking of a delivery to a service-point, you have an option to select a service-point in advance with the Nearby Service Points endpoint and add it to the booking request.
Booking request has to be done with "transportSolutionId": 62 and selected service-point at “parties” object of a request.
Step 1: Retrieve a service point
{
"type": "servicePoint",
"id": "30694",
"countryCode": "NO"
}Use this service point object as a party in the booking request.
Step 2: Booking request
{
"shopId": 1,
"transportSolutionId": 62,
"shipmentId": "",
"parties": [
{
"type": "consignee",
"name": "Test Customer",
"countryCode": "no",
"postalName": "Oslo",
"zipCode": "0195",
"address": "Fjellgata 48",
"phone1": "75476618",
"email": "testcustomer@test.com",
"reference": "cust_ref"
},
{
"type": "consignor",
"name": "Testbutikken",
"countryCode": "NO",
"postalName": "OSLO",
"zipCode": "0180",
"address": "Akersgata 55",
"phone1": "75476618",
"contact": "testcustomer@test.com",
"reference": "shop_ref"
},
{
"type": "servicePoint",
"id": "30694",
"countryCode": "NO"
}
],
"items": [
{
"itemNumber": 1,
"trackingReference": "",
"weight": 35,
"width": 0,
"height": 12.0,
"length": 35.0,
"contents": "en pakke"
}
]
}Response
{
"shipmentId": "(401)70724762337122546",
"freightProductId": 55,
"parties": [
{
"type": "consignee",
"id": null,
"name": "Test Customer",
"countryCode": "no",
"postalName": "Oslo",
"zipCode": "0195",
"address": "Fjellgata 48",
"phone1": "75476618",
"phone2": null,
"email": "testcustomer@test.com",
"reference": "cust_ref",
"contact": null,
"coaddress": null
},
{
"type": "consignor",
"id": null,
"name": "Testbutikken",
"countryCode": "NO",
"postalName": "OSLO",
"zipCode": "0180",
"address": "Akersgata 55",
"phone1": "75476618",
"phone2": null,
"email": null,
"reference": "shop_ref",
"contact": "testcustomer@test.com",
"coaddress": null
},
{
"type": "servicePoint",
"id": "30694",
"name": "Joker Toftes Gate",
"countryCode": "NO",
"postalName": "OSLO",
"zipCode": "0556",
"address": "TOFTES GATE 12",
"phone1": null,
"phone2": null,
"email": null,
"reference": null,
"contact": null,
"coaddress": null
}
],
"items": [
{
"itemNumber": 1,
"trackingReference": "(00)370724762337122554",
"returnCode": null,
"linkedParcelType": null,
"linkedTrackingReference": null,
"weight": 35,
"volume": null,
"length": 35.0,
"height": 12.0,
"width": 0.0,
"contentValue": null,
"externalSupplierId": null,
"contents": "en pakke",
"properties": {
"shortItemIdentifier": "...2554"
},
"articles": [],
"externalOrderId": null
}
],
"properties": {
"areaId": null,
"deliveryPointCarId": "8064",
"distributionDate": "20230202",
"freightProductName": "Helthjem Hentepakke",
"mainCarNumber": "103",
"pickupZipString": "",
"productName": "Hentepakke",
"regionId": null,
"retailerId": "30694",
"routeAddress": "TOFTES GATE 12",
"routeDescription": null,
"routeName": "",
"routeSeq": "",
"routeZipAndCity": null,
"routing": "103-5",
"routingDescription": " ",
"routingDetailed": null,
"shopName": "Testbutikken",
"transportNetId": "204"
},
"additionalServices": [
{
"key": "RNL",
"value": "Legitimasjonskontroll"
}
],
"orderId": 89828099
}This parcel has now been booked to the service point “id”: 30694”. The consignee will be notified.
Example 3: Booking a fulfilment order
When booking a fulfilment order to be picked by Helthjem, additional information is required in the booking request. After a successful booking is made, the order will be transferred to the WMS within 5 minutes. The booking request must include:
-
Additional service with key
ASBand valueHHWMS
-
Article name, article ID and quantity
Request example
{
"shopId": 1,
"transportSolutionId": 1,
"additionalServices": [
{
"key": "ASB",
"value": "HHWMS"
}
],
"shipmentId": "",
"parties": [
{
"type": "consignee",
"name": "Test Customer",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0566",
"address": "Fjellgata 48",
"phone1": "48398438",
"email": "testcustomer@test.com",
"reference": "cust_ref",
"contact": "contact2"
},
{
"type": "consignor",
"name": "Test shop",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0480",
"address": "Sandakerveien 121",
"phone1": "",
"contact": "contact1",
"reference": "shop_ref",
"email": ""
}
],
"items": [
{
"itemNumber": 1,
"trackingReference": "",
"weight": 1000,
"width": 12,
"height": 12,
"length": 12,
"contents": "test item",
"articles": [
{
"articleNumber": "100200300",
"articleName": "Testitem",
"quantity": 1
}
]
}
]
}Response
{
"shipmentId": "(401)70724762687981480",
"freightProductId": 1,
"parties": [
{
"type": "consignee",
"id": null,
"name": "Test Customer",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0566",
"address": "Fjellgata 48",
"phone1": "48398438",
"phone2": null,
"email": "testcustomer@test.com",
"reference": "cust_ref",
"contact": "contact2",
"coaddress": null
},
{
"type": "consignor",
"id": null,
"name": "Test shop",
"countryCode": "NO",
"postalName": "Oslo",
"zipCode": "0480",
"address": "Sandakerveien 121",
"phone1": "",
"phone2": null,
"email": "",
"reference": "shop_ref",
"contact": "contact1",
"coaddress": null
}
],
"items": [
{
"itemNumber": 1,
"trackingReference": "(00)370724762687981498",
"returnCode": null,
"linkedParcelType": null,
"linkedTrackingReference": null,
"weight": 1000,
"volume": null,
"length": 12.0,
"height": 12.0,
"width": 12.0,
"contentValue": null,
"externalSupplierId": null,
"contents": "test item",
"properties": {
"shortItemIdentifier": "...1498"
},
"articles": [
{
"articleNumber": "100200300",
"quantity": 1,
"articleName": "Testitem"
}
],
"externalOrderId": null
}
],
"properties": {
"areaId": "59",
"freightProductName": "helthjem",
"mainCarNumber": "14",
"pickupZipString": "0556 OSLO",
"productName": "helthjem standard",
"regionId": "189",
"routeAddress": "TOFTES GATE 21 B",
"routeDescription": "BUDSENTRAL RINGNES PARK",
"routeName": "22111",
"routeSeq": "536",
"routeZipAndCity": null,
"routing": "14-0-x22111x536",
"routingCode": "1",
"routingDescription": "RINGNES PARK",
"routingDetailed": "14 - RINGNES PARK",
"shopName": "Testbutikken",
"transportCompanyId": "1",
"transportNetId": "223"
},
"additionalServices": [
{
"key": "ASB",
"value": "External Packaging System"
}
],
"orderId": 133370472
}Consumer to Consumer - C2C
Party types
-
consignor= Consumer sending parcel -
consignee= Consumer receiving parcel -
servicePoint= Selected Service Point.
Example 1: Book C2C - label required
In this example, we will use transportSolutionId:"23". Which is a labelless solution, so that the consumer does not need to print a label.
The response contains “returnCode”: “X-XXXXX” which must be written on the package.
|
Transport Solution |
Freight products |
Description |
|---|---|---|
|
|
|
Primary: Send from home |
Returns - C2B
Example 1: Book C2B - label required
Party types
-
consignor= Consumer sending parcel -
consignee= Business
Booking request for return products is the same as for a regular outgoing booking. However, can be somewhat tricky implementing a solution with labels or labelless from the consumer. Read our page on Delivery methods to understand these nuances.
-
You should to use one of
transportSolutionId:17,21,33,63for return.