Returns integration

Let your customers send items back to you: by home pickup, or by dropping the parcel off at a service point, with or without a label.

This guide covers these steps:

  1. Authorize
  2. Check address for coverage
  3. Fetch available pickup dates (home pickup only)
  4. Book the return
  5. Give the customer a label or return code
  6. Track the return

Choose a transport solution

See Delivery methods to choose a transport solution. The return transport solution decides which return options the customer gets. It also sets the order in which Helthjem tries them when the first isn't available.

transportSolutionId Name Falls back through Use when
21 Helthjem retur 4 Home pickup only
33 Helthjem retur m/retur via butikk 4 → 56 → 20 Home pickup, labelled PUDO as backup
63 Helthjem retur butikk 56 → 20 Labelled PUDO only
116 Etikettløs retur via butikk 91 Labelless PUDO only
118 Helthjem Returpakke 56 Labelled Helthjem PUDO only
119 Pure Helthjem Retur 4 → 56 Home pickup, Helthjem PUDO as backup
121 100% Etikettløs Retur 4 → 91 Labelless throughout
122 Helthjem retur m/etikettløs PUDO 4 → 91 → 20 Home pickup, labelless PUDO as backup, labelled PostNord PUDO as last resort
135 Etikettløs retur via butikk eller PN 91 → 20 Labelless PUDO, PostNord as backup

These are the freight products the solutions resolve to:

freightProductId productName Return type Label
4 HELTHJEM_RETUR Home Label or code
56 Helthjem_SHOP_RETURN PUDO Label
91 HELTHJEM_C2B_SHOP PUDO Label or code
20 PN_MYPACK_RETUR PUDO Label

Tip: in rural or low-coverage areas, use a solution with fallbacks (33, 122 or 135), so you can accept more returns.

This guide uses TS 21 for home pickup and TS 116 for labelless drop-off at a service point. It checks coverage before booking.

1. Authorize

Get an access token and send it as Authorization: Bearer your_token with every request. See Authentication for how to request, cache and refresh the token.

2. Check address for coverage

2.1 Check return coverage

Use the Single Address Check endpoint to confirm that Helthjem covers an address with a return transport solution.

Run the check once for each return option you want to show, so the customer only sees options that are available at their address.

This example checks that Helthjem can collect a return from the doorstep of Ola Nordmann, who lives at Kongsberggata 18, 0468 Oslo, in apartment H0201.

Path: POST /parcels/v1/addresses/find/single

Request

{
    "shopId": 16,
    "transportSolutionId": 21,
    "customerName": "Ola Nordmann",
    "address": "Kongsberggata 18 H0201",
    "zipCode": "0468",
    "postalName": "Oslo",
    "countryCode": "NO",
    "weight": 1000,
    "volume": null
}

Success (200)

{
  "productName": "HELTHJEM_RETUR",
  "routeName": "21516",
  "routing": "1-31/114-43-x21516x385",
  "routeAddress": "TÅSENVEIEN 26",
  "handoverCity": "OSLO",
  "plannedDeparture": "1600"
}

The response "productName": "HELTHJEM_RETUR" confirms that Helthjem can collect a return from this address.

You can now offer home pickup as a return option.

A 400 with no.carrier.support means Helthjem can't collect from that address with the chosen transport solution. Hide that option in your checkout.

To check labelless drop-off at a service point, run the same check with "transportSolutionId": 116. If the address is covered, the response contains "productName": "HELTHJEM_C2B_SHOP" (freight product 91), and you can offer labelless service point returns.

2.2 Find nearby service points

To show service point drop-off options, use the Nearby Service Points endpoint to get the 3 closest locations to the address.

This example uses transportSolutionId: 62, which includes both Helthjem and PostNord service points.

Path: POST /parcels/v1/service-points/nearby

Request

{
    "shopId": 16,
    "transportSolutionId": 62,
    "streetAddress": "Kongsberggata 18",
    "zipCode": "0468",
    "postalName": "Oslo",
    "countryCode": "NO"
}

Response (trimmed)

{
  "freightProducts": [
    {
      "freightName": "Helthjem Hentepakke",
      "servicePoints": [
        {
          "servicePointExternalId": "30694",
          "servicePointName": "Joker Toftes Gate",
          "openingHours": [
            {"day":"MONDAY","from1":"07:00","to1":"00:00"}
          ],
          "visitingAddress": {
            "streetName": "TOFTES GATE",
            "streetNumber": "12",
            "postalCode": "0556",
            "postalName": "OSLO",
            "countryCode": "NO"
          }
        }
      ]
    }
  ]
}

Customers can hand in a return at any eligible location. Show the nearby points for information only, and don't add a servicePoint party to the booking.

3. Fetch available pickup dates

If the customer chooses home pickup (TS 21), show them the available pickup dates. The booking needs the selected date to order a Helthjem driver.

Skip this step for service point returns. They have no pickup date.

This endpoint takes a freight product, not a transport solution. Use "freightProductId": 4 (home pickup).

Path: POST /parcels/v1/addresses/find/single/dates

Request

{
    "shopId": 16,
    "freightProductId": 4,
    "zipCode": "0468",
    "customerName": "Ola Nordmann",
    "countryCode": "NO",
    "postalName": "Oslo",
    "address": "Kongsberggata 18 H0201",
    "co": ""
}

Response

{
    "dates": [
        "2026-06-17",
        "2026-06-18",
        "2026-06-19",
        "2026-06-20",
        "2026-06-22",
        "2026-06-23",
        "2026-06-24",
        "2026-06-25",
        "2026-06-26",
        "2026-06-27",
        "2026-06-29",
        "2026-06-30"
    ]
}

Dates when collection isn't possible are left out of the list, so you can show the array as it is.

4. Book the return

Once you've confirmed that the transport solution is available for the address, book the return with the Booking endpoint.

A return uses the same endpoint and request as an outgoing booking, with the parties swapped: the customer is the consignor (sender) and the shop is the consignee (receiver).

For home pickup, send the date the customer selected as desiredDeliveryDate.

Request headers

POST /parcels/v1/bookings
Authorization: Bearer your_token
Content-Type: application/json
idempotency-key: 0d4b7e2a-9c6f-4183-b5e9-6a2c8d1f4b57

Use a new, unique idempotency-key for each shipment, and reuse it if you retry this request. See Idempotency & retries.

Request (transportSolutionId: 21, home pickup)

{
    "shopId": 16,
    "transportSolutionId": 21,
    "desiredDeliveryDate": "20260617",
    "parties": [
        {
            "type": "consignee",
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0480",
            "address": "Sandakerveien 121",
            "phone1": "12345678",
            "email": "test@example.com"
        },
        {
            "type": "consignor",
            "name": "Ola Nordmann",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0468",
            "address": "Kongsberggata 18",
            "phone1": "12345678",
            "email": "test@example.com"
        }
    ],
    "items": [
        {
            "itemNumber": 1,
            "weight": 1000,
            "width": 12,
            "height": 12,
            "length": 12,
            "contents": "Shoes"
        }
    ]
}

Response (trimmed)

{
  "orderId": 133370472,
  "shipmentId": "(401)70724763243779244",
  "freightProductId": 4,
  "items": [
    {
      "itemNumber": 1,
      "trackingReference": "(00)370724763243779252",
      "returnCode": "H987654"
    }
  ]
}

The response contains the shipmentId and trackingReference. If the booking resolved to a labelless product, it also contains a returnCode.

For a service point return, use a service point solution (116, 63, 118 or 135) and leave out desiredDeliveryDate.

Tip: fill in phone1 and email for the consignor. Helthjem uses them to send the customer the return code and instructions.

5. Give the customer a label or return code

What you give the customer depends on the freight product the booking resolved to. Check freightProductId in the response.

Products with a label

For FP 56, FP 20 and FP 4 with a label, get a printable label after the booking succeeds. Use the shipmentId or trackingReference as the identifier. The standard label is a 102 mm × 192 mm PDF. See Generate a label for other formats.

Request

curl -X GET "https://api.pre.helthjem.no/parcels/v1/labels/70724763243779244/unified-large" \
  -H "Authorization: Bearer your_token" \
  -H "Accept: application/pdf, application/json" \
  -o label.pdf

Labelless products

For FP 91, and FP 4 without a label, there is no label. The booking response contains a return code instead:

{
  "returnCode": "H987654"
}

Helthjem sends the customer an SMS and an email with the code and instructions. You can also show them in your own return flow:

Option Instructions to show the customer
Home pickup Write the code on the parcel, and leave it outside by 07:00 on the selected date.
Service point Write the code on the parcel, and drop it off at the nearest Helthjem return point.

6. Track the return

Get the tracking events for the return, from booking to arrival.

curl -X GET "https://api.pre.helthjem.no/parcels/v1/tracking/fetch/70724763243779244/NO/false" \
  -H "Authorization: Bearer your_token" \
  -H "Accept: application/json"

Response

[
    {
        "shipmentNumber": "70724763243779244",
        "shopName": "Test shop",
        "shopId": 16,
        "consigneeReference": "shop_ref",
        "consignorReference": "cust_ref",
        "properties": {},
        "items": [
            {
                "trackingNumber": "370724763243779252",
                "returnCode": "H987654",
                "freightProductId": 4,
                "freightProductName": "HELTHJEM_RETUR",
                "parcelStatus": "WAITING_FOR_PACKAGE",
                "linkedParcelNumbers": [],
                "events": [
                    {
                        "eventTime": "2025-10-13 13:46:07",
                        "eventTimeUtc": "2025-10-13T11:46:07.028470Z",
                        "lat": null,
                        "lon": null,
                        "locationContext": "Test shop",
                        "locationContextId": null,
                        "eventType": {
                            "apiKey": "001",
                            "description": "Meldt ankomst av pakke",
                            "i18nKey": "event.type.distr.import.edi.information.received"
                        },
                        "additionalInfo": null,
                        "eventGroup": {
                            "id": 1,
                            "name": "event.type.group.import"
                        },
                        "comChannelType": null,
                        "changeUserId": null,
                        "changeUsername": null,
                        "regSystem": {
                            "id": 1,
                            "name": "Beh. Engangslev."
                        },
                        "message": null,
                        "eventData": null
                    }
                ]
            }
        ]
    }
]

For a service point return, nothing happens until the customer drops the parcel off. Expect a gap between the booking and the first scan.

Next steps

Last updated