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:

  1. Book to a specific parcel locker. The consumer picks a parcel locker at checkout, and you book the parcel to that locker.
  2. Book to an assigned parcel locker. You book the parcel with the consumer's address, and Helthjem assigns the closest parcel locker.
  3. 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

  1. Authorize
  2. Check address for coverage
  3. Get nearby parcel lockers
  4. Book parcel
  5. Print label
  6. 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.

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

  1. Authorize
  2. Check address for coverage
  3. Book parcel
  4. Print label
  5. 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

  1. Authorize
  2. Book parcel
  3. Print label
  4. 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

Last updated