C2C Integration

This guide takes you through the basic setup and steps to integrate a Business to Customer delivery flow with Helthjem.

Steps:

Authorize
Check address for coverage
Fetch pickup date (If home pickup)
Book parcel
Shipment code (returnCode)

Choose a transport solution

See our page with descriptions on Delivery Methods to find an appropriate Transport Solution. In this guide we will be using the labelless C2C transport solutions 23 (Doorstep pickup), 113 (Service point -small) and 115 (Service point - medium/large).

Lets begin

1. Authorize

Use the Authorization endpoint with your client_id and client_secret to obtain a JWT. This token expires in 24hrs, if you store if you store it and refresh it every 12 hours, you will not need need to authorize for every request.

Path: /auth/oauth2/v1/token

Request

{
    "client_id": "your-client-id",
    "client_secret": "your-secret",
    "grant_type": "client_credentials"
  }

Response

{
  "token": "xxx",
  "expires_in": 86400,
  "token_type": "Bearer"
}

Use the body headers for all subsequent requests:

Authorization: Bearer <token>
Content-Type: application/json

2. Check address for coverage

2.1 Single Address Check

For Pickup from home (TS 23), first check the senders address to see if we offer pickup from home.

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

Request

{
    "shopId": "16",
    "transportSolutionId": 23,
    "customer name": "Sender Name",
    "address": "Eksempelveien 12",
    "zipCode": "0468",
    "postalName": "Oslo",
    "countryCode": "NO",
    "weight": 900,
    "volume": null
  }

Response (200) OK

{
  "productName": "HELTHJEM_MEGTILDEG",
  "handoverCity": "OSLO"
}

Response (400) unavailable

{
    "errorKey": "no.carrier.support",
}

2.2 Nearby service points

If home pickup is not available, show the closest drop-off locations for the sender. (TS 113)

All C2C parcels sent with Helthjem can be returned at any Helthjem Service point.

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

Request

{
    "shopId": "16",
    "transportSolutionId": 113,
    "customer name": "Sender Name",
    "address": "Eksempelveien 12",
    "zipCode": "0468",
    "postalName": "Oslo",
    "countryCode": "NO",
    "weight": 900,
    "volume": null
  }

Response -trimmed

{
    "freightProducts": [
        {
            "transporterId": 113,
            "transporterName": "Helthjem AS",
            "freightProductId": 92,
            "freightName": "Helthjem C2C via butikk - small",
            "freightTitle": "Retur fra hentested",
            "freightDescription": "C2C pakker leveres inn med returkode ved et Helthjem utleveringssted, og leveres hjem eller til butikk",
            "servicePoints": [
                {
                    "servicePointExternalId": "49003",
                    "servicePointName": "Joker Trondheimsveien",
                    "visitingAddress": {
                        "postalCode": "0560",
                        "countryCode": "NO",
                        "streetNumber": "26",
                        "streetName": "TRONDHEIMSVEIEN",
                        "postalName": "OSLO"
                    },

This response can be displayed to the sender, where they can select their preferred location, or you chose one for them by default.

3. Fetch available pickup dates

If the sender chooses Home pickup (TS 23), show available pickup dates. This date is needed in the booking to order a Helthjem driver to pickup the parcel and receive a returnCode.

Note: You need to use "freightProductId": 26,

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

Request

{
  "shopId": 16,
  "freightProductId": 26,
  "zipCode": "0561",
  "customerName": "Test customer",
  "countryCode": "NO",
  "postalName": "Oslo",
  "address": "Herslebs gate 2F",
  "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"
    ]
}

4. Book parcel

C2C parcels are labelless. After booking, the returnCode must be displayed to the sender for them to write it clearly on the parcel.

Path: /parcels/v1/bookings

4.1 Book home pickup (TS 23)

Ensure to include the pickup date collected earlier as the "desiredDeliveryDate":, otherwise the returnCode will not be shown.

Date needs to be canonized and converted to integer. Sorry… legacy things…

Request

{
    "shopId": 16,
    "transportSolutionId": 23,
    "shipmentId": null,
    "desiredDeliveryDate": 20260617,
    "parties": [
        {
            "type": "consignee",
            "name": "Test receiver",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0751",
            "address": "Vækerøveien 164d",
            "coaddress": "",
            "phone1": "12345678",
            "email": "test@gmail.com",
            "reference": "consignee_reference",
            "contact": "contact2"
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test sender",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0561",
            "address": "Herslebsgate 2F",
            "phone1": "12345678",
            "email": "test@gmail.com",
            "reference": "consignor_reference",
            "contact": "consignor_contact",
            "coaddress": null
        }
    ],
      "items": [
        {
            "itemNumber": 1,
            "trackingReference": "",
            "weight": 1000,
            "width": 12,
            "height": 12,
            "length": 12,
            "contents": "test item"
        }
    ]
}

Response - trimmed

{
    "shipmentId": "(401)70724763469418064",
    "freightProductId": 26,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Kristian Voie Danielsen",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0751",
            "address": "Vækerøveien 164d",
            "detailedAddress": null,
            "phone1": " 47 980 50 370",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "consignee_reference",
            "contact": "contact2",
            "coaddress": ""
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Herslebsgate 2F",
            "zipCode": "0561",
            "address": "Herslebsgate 2F",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "",
            "reference": "consignor_reference",
            "contact": "consignor_contact",
            "coaddress": null
        }
    ],
    "items": [
        {
            "returnCode": "T-NXXW9",
        }
    ],
    "properties": {
    },
    "additionalServices": [],
    "orderId": 227218777
}

4.1 Book Service point drop off (TS 113)

Request

{
    "shopId": 16,
    "transportSolutionId": 113,
    "shipmentId": null,
    "desiredDeliveryDate": 20260617,
    "messageToCarrier": "hello car",
    "messageToConsignee": "hello con",
    "parties": [
        {
            "type": "consignee",
            "name": "Kristian Voie Danielsen",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0751",
            "address": "Vækerøveien 164d",
            "coaddress": "",
            "phone1": " 47 980 50 370",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "consignee_reference",
            "contact": "contact2"
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Herslebsgate 2F",
            "zipCode": "0561",
            "address": "Herslebsgate 2F",
            "phone1": "12345678",
            "phone2": null,
            "email": "",
            "reference": "consignor_reference",
            "contact": "consignor_contact",
            "coaddress": null
        }
    ],
      "items": [
        {
            "itemNumber": 1,
            "trackingReference": "",
            "weight": 1000,
            "width": 12,
            "height": 12,
            "length": 12,
            "contents": "test item"
        }
    ]
}

Response

{
    "shipmentId": "(401)70724763469418088",
    "freightProductId": 92,
    "parties": [
        {
            "type": "consignee",
            "id": null,
            "name": "Kristian Voie Danielsen",
            "countryCode": "NO",
            "postalName": "Oslo",
            "zipCode": "0751",
            "address": "Vækerøveien 164d",
            "detailedAddress": null,
            "phone1": " 47 980 50 370",
            "phone2": null,
            "email": "test@gmail.com",
            "reference": "consignee_reference",
            "contact": "contact2",
            "coaddress": ""
        },
        {
            "type": "consignor",
            "id": null,
            "name": "Test shop",
            "countryCode": "NO",
            "postalName": "Herslebsgate 2F",
            "zipCode": "0561",
            "address": "Herslebsgate 2F",
            "detailedAddress": null,
            "phone1": "12345678",
            "phone2": null,
            "email": "",
            "reference": "consignor_reference",
            "contact": "consignor_contact",
            "coaddress": null
        },
        {
            "type": "servicePoint",
            "id": "49003",
            "name": "Joker Trondheimsveien",
            "countryCode": "NO",
            "postalName": "OSLO",
            "zipCode": "0560",
            "address": "TRONDHEIMSVEIEN 26",
            "detailedAddress": null,
            "phone1": null,
            "phone2": null,
            "email": null,
            "reference": null,
            "contact": null,
            "coaddress": null
        }
    ],
    "items": [
        {
            "itemId": null,
            "itemNumber": 1,
            "trackingReference": "(00)370724763469418096",
            "returnCode": "T-H1MN3",
            "linkedParcelType": null,
            "linkedTrackingReference": null,
            "weight": 1000,
            "volume": null,
            "length": 12,
            "height": 12,
            "width": 12,
            "contentValue": null,
            "externalSupplierId": null,
            "contents": "test item",
            "properties": {
                "shortItemIdentifier": "...8096"
            },
            "articles": [],
            "externalOrderId": null
        }
    ],
    "properties": {
        "areaId": null,
        "deliveryPointCarId": "9394",
        "distributionDate": "20260617",
        "freightProductName": "Helthjem C2C via butikk - small",
        "mainCarNumber": "107",
        "pickupZipString": "",
        "productName": "Retur fra hentested",
        "regionId": null,
        "retailerId": "49003",
        "routeAddress": "TRONDHEIMSVEIEN 26 A",
        "routeDescription": null,
        "routeName": null,
        "routeSeq": "",
        "routeZipAndCity": null,
        "routing": "107-12",
        "routingDescription": " ",
        "routingDetailed": "107",
        "servicePointType": "RETAILER",
        "shopName": "Testbutikken Helthjem",
        "transportNetId": "204"
    },
    "additionalServices": [],
    "orderId": 227218839
}

Display the returncode (from the response) and clear instructions:

“Write this code on the parcel and leave it by the mailbox/front door on the pickup day,” or “Write this code and drop off at the selected Service point.”

5. Conversion Note

In some cases, a customer may order a C2C shipment with home pick-up but instead decide to deliver the parcel at a PUDO (service point).

When this happens, the system automatically:

Cancels the original home pick-up order.
Creates a new order as a return from PUDO.
Books the shipment as freight product 92 – Helthjem C2C via butikk (small).

This ensures the tracking flow continues without breaking, while reflecting the correct product and journey.

B2C Integration

Logos and icons