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:
- Authorize
- Check address for coverage
- Fetch available pickup dates (home pickup only)
- Book the return
- Give the customer a label or return code
- 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
- Tracking events: turn tracking events into statuses for your customers.
- Label guide: see the return label formats.
- Go-live checklist: check your integration before you switch to production.
