Parcel lockers
Deliver parcels to Helthjem parcel lockers: let the consumer choose a locker, let Helthjem assign the closest one or use lockers as a fallback for home delivery.
Choose a method
There are several ways to book parcels to parcel lockers. Start by choosing the flow that fits your checkout.
In practice, there are 4 pathways to connect to the network:
- Book to a specific parcel locker. The consumer picks a parcel locker at checkout, and you book the parcel to that locker.
- Book to an assigned parcel locker. You book the parcel with the consumer's address, and Helthjem assigns the closest parcel locker.
- Use parcel lockers as a fallback. You book with a transport solution that tries home delivery first, and falls back to a parcel locker if home delivery is not possible.
| Pathway | Transport solution | Consumer chooses locker? | Coverage check needed? |
|---|---|---|---|
| 1. Specific parcel locker | 137 |
Yes | Recommended |
| 2. Assigned parcel locker | 137 |
No | Yes |
| 3. Parcel locker as fallback | 1 or 114 |
No | No |
Test addresses
| Address | Expected Result |
|---|---|
| Toveien 16, 1540 Vestby | 2 nearby Parcel lockers |
| Sponstubben 62, 1414 Trollåsen | 2 nearby Parcel lockers |
Parcel locker limits
Parcel locker deliveries use freightProductId: 95 (Helthjem Parcel locker). The parcel must fit these limits:
| Limit | Value |
|---|---|
| Max weight | 5000 g |
| Max value | 200 000 kr |
| Max size | 590 x 450 x 500 mm |
The recipient is notified when the parcel is delivered, and receives a PIN code to open the locker.
These steps assume that you have already authenticated and are sending requests with your JWT token. See Authentication for how to get and use a token.
1. Book to a specific parcel locker
Use this pathway when you want the consumer to choose a parcel locker at checkout, for example from a list or a map.
| transportSolutionId | freightProductId | Description |
|---|---|---|
137 |
95 |
Primary: Parcel locker |
Steps for a specific locker
- Authorize
- Check address for coverage
- Get nearby parcel lockers
- Book parcel
- Print label
- Track shipment
Check address for coverage
Check that parcel locker delivery is available for the consumer's address before you show it as an option at checkout.
Path: /parcels/v1/addresses/find/single
Request
{
"shopId": 16,
"transportSolutionId": 137,
"customerName": "Ola Nordmann",
"address": "Toveien 16",
"zipCode": "1540",
"postalName": "Vestby",
"countryCode": "NO",
"weight": 1000
}
A 200 response confirms that parcel locker delivery is available. A 400 response with "errorKey": "no.carrier.support" means there is no parcel locker coverage for this address. Hide the option at checkout.
Get nearby parcel lockers
Use the Nearby Service Points endpoint with transportSolutionId: 137 to get the closest parcel lockers to the consumer's address.
Path: /parcels/v1/service-points/nearby
Request
{
"shopId": 16,
"transportSolutionId": 137,
"streetAddress": "Toveien 16",
"zipCode": "1540",
"postalName": "Vestby",
"countryCode": "NO"
}
Response (trimmed)
{
"freightProducts": [
{
"freightProductId": 95,
"servicePoints": [
{
"servicePointExternalId": "157128",
"servicePointName": "Pakkeskap KIWI Vestby",
"type": "PARCEL_LOCKER",
"eligibleParcelOutlet": true,
"visitingAddress": {
"streetName": "VESTBYVEIEN",
"streetNumber": "31",
"postalCode": "1543",
"postalName": "VESTBY",
"countryCode": "NO"
},
"servicePointCoordinates": [
{
"northing": 59.60860061645508,
"easting": 10.742959976196289
}
]
},
{
"servicePointExternalId": "157821",
"servicePointName": "Pakkeskap Vestby Stasjon",
"type": "PARCEL_LOCKER",
"eligibleParcelOutlet": true,
"visitingAddress": {
"streetName": "KROERVEIEN",
"streetNumber": "2",
"postalCode": "1540",
"postalName": "VESTBY",
"countryCode": "NO"
},
"servicePointCoordinates": [
{
"northing": 59.60340881347656,
"easting": 10.748283386230469
}
]
}
]
}
]
}
Show the parcel lockers to the consumer, for example on a map using servicePointCoordinates. Parcel lockers have "type": "PARCEL_LOCKER". In this example, the consumer can choose between Pakkeskap KIWI Vestby and Pakkeskap Vestby Stasjon.
Book parcel
Add the selected locker to the booking as a servicePoint party. Use its servicePointExternalId as the id. In this example, the consumer chose Pakkeskap KIWI Vestby (157128).
Path: /parcels/v1/bookings
Request headers
POST /parcels/v1/bookings
Authorization: Bearer your_token
Content-Type: application/json
idempotency-key: e6f1b3c8-2d9a-4e57-a0b4-9c7d3e5f1a28
Use a new, unique idempotency-key for each shipment, and reuse it if you retry this request. See Idempotency & retries.
Request
{
"shopId": 16,
"transportSolutionId": 137,
"parties": [
{
"type": "consignee",
"name": "Ola Nordmann",
"countryCode": "NO",
"postalName": "Vestby",
"zipCode": "1540",
"address": "Toveien 16",
"phone1": "12345678",
"email": "test@example.com"
},
{
"type": "consignor",
"name": "Test shop",
"countryCode": "NO",
"postalName": "Vestby",
"zipCode": "1540",
"address": "Toveien 19",
"phone1": "12345678"
},
{
"type": "servicePoint",
"id": "157128",
"countryCode": "NO"
}
],
"items": [
{
"itemNumber": 1,
"weight": 1000,
"width": 30,
"height": 20,
"length": 40,
"contents": "Shoes"
}
]
}
The response has "freightProductId": 95 and the locker in the parties list. Make sure phone1 and email are filled in for the consignee, so the recipient receives the delivery notification and the PIN code.
Print label and track shipment
Fetch the label and track the parcel in the same way as for any other booking. See Generate a label and Tracking events.
2. Book to an assigned parcel locker
Use this pathway when you want to offer parcel locker delivery, but don't want the consumer to choose a specific locker. Helthjem assigns the closest parcel locker to the consumer's address.
Steps for an assigned locker
- Authorize
- Check address for coverage
- Book parcel
- Print label
- Track shipment
Check coverage with transportSolutionId: 137 in the same way as in pathway 1. Then book with transportSolutionId: 137 without a servicePoint party. Helthjem uses the consignee's address to assign the closest parcel locker, and returns it as a servicePoint party in the booking response.
Request headers
POST /parcels/v1/bookings
Authorization: Bearer your_token
Content-Type: application/json
idempotency-key: f2a8c5e7-4b1d-4c93-8e6a-1d5b7f9c3e40
Use a new, unique idempotency-key for each shipment, and reuse it if you retry this request. See Idempotency & retries.
Request (parties)
{
"parties": [
{
"type": "consignee",
"name": "Ola Nordmann",
"countryCode": "NO",
"postalName": "Vestby",
"zipCode": "1540",
"address": "Toveien 16",
"phone1": "12345678",
"email": "test@example.com"
},
{
"type": "consignor",
"name": "Test shop",
"countryCode": "NO",
"postalName": "Vestby",
"zipCode": "1540",
"address": "Toveien 19",
"phone1": "12345678"
}
]
}
Show the assigned locker from the booking response to the consumer, for example in the order confirmation.
3. Use parcel lockers as a fallback
Use this pathway when you want home delivery wherever possible, with parcel lockers as a backup. You don't need a coverage check or a nearby lookup. Helthjem tries each freight product in order and uses the first one that is available for the address.
| transportSolutionId | Freight products (in order) | Description |
|---|---|---|
1 |
1 > 95 > 55 > 3 |
Primary: Home delivery Fallback 1: Parcel locker Fallback 2: Service point (Helthjem) Fallback 3: Service point (PostNord) |
114 |
1 > 95 > 55 |
Primary: Home delivery Fallback 1: Parcel locker Fallback 2: Service point (Helthjem) |
Steps for a fallback
- Authorize
- Book parcel
- Print label
- Track shipment
Book the parcel with one of the transport solutions above, without a servicePoint party. Check freightProductId in the booking response to see which delivery method was used. 95 means the parcel will be delivered to a parcel locker, and the assigned locker is returned as a servicePoint party. When a fallback is used, the parcel also gets tracking event 154 (fallback shipment solution was triggered).
A parcel can only fall back to a parcel locker if it fits the parcel locker limits. Larger or heavier parcels skip to the next fallback.
NOTE! Parcel locker fallbacks are not activated by default. If you are already using TS 1 or TS 114, please contact us at integrations@helthjem.no and we will activate it today.
Next steps
- Generate a label: print the label for the booking.
- Tracking events: follow the parcel until it's collected from the locker.
