The Parcel Booking API registers a parcel shipment. Given the data in the request, the API performs the booking and returns the booked freight product and transport details.

Information

Environments / Endpoints

Environment Method URL
Production POST https://api.helthjem.no/parcels/v1/bookings
Pre-Production POST https://api.pre.helthjem.no/parcels/v1/bookings

Request schema

Party types

Request body

Field Type Example Required Max Description
shopId integer 95123 ✅ — Shop this booking is made for.
shopDisplayName string My Company Ltd 30 Alternative display name used in customer comms.
transportSolutionId integer 1 ✅ — Determines delivery behavior (see Transport Solutions).
shipmentId string (401)70712190172720651 35 Global order id. If omitted, created server-side (GS1 GINC).
desiredDeliveryDate string (yyyyMMdd) 20160120 ⚠️ 8 Delivery (B2C) / pickup (C2B/C2C) date. Mandatory for some products (e.g., labelless pickup).
parties array of party — ✅ — Must include consignor and consignee; may include servicePoint, pickupAddress, returnAddress.
items array of item — ✅ — One object per physical parcel (label).
messageToCarrier string Leave at door 350 Delivery instructions; may appear on label.
messageToConsignee string Thanks for ordering! 350 Message to receiver; may appear on label.
additionalServices array of additionalService — — Must be configured for the shop.

Parties

Field Type Example Required Max Notes
type string consignee ✅ — One of: consignee, consignor, returnAddress, servicePoint, pickupAddress.
id string 0123456789 ⚠️ 17 Use only if unique per consumer; otherwise avoid (links customers).
name string Ola Nordmann ⚠️ 105 Mandatory for consignee and consignor.
countryCode string NO ⚠️ 3 ISO 3166-1; required for consignee and consignor.
postalName string OSLO ⚠️ 35 City name.
zipCode string 0155 ⚠️ 9 Postal code; required for consignee and consignor.
address string Storgaten 11A H0202 105 Combined address line.
coaddress string Kari Nordmann 255 c/o line.
phone1 string +47 402 10 000 ⚠️ 100 Used for notifications.
phone2 string +47 402 20 000 100 Secondary phone.
email string [email protected] ⚠️ 100 Used for notifications.
reference string 012345 35 Order/reference; may print on label.
contact string Customer service 35 Contact name; may print on label.

Items

An item represents one physical parcel (one label / one trackingReference).

Field Type Example Required Max Description
itemNumber integer 1 ✅ — Sequence per shipment (1,2,3…).
trackingReference string (00)370724760010119754 ⚠️ 35 If omitted, generated and returned. For returns C2x, do not set; system generates.
returnCode string XX-12345 10 8–10 chars: letters+-+alphanum (e.g., AB-12345678).
weight integer (grams) 600 — Item weight.
volume decimal (dm³) 4 — Item volume.
length decimal (cm) 120 —
height decimal (cm) 5 —
width decimal (cm) 12 —
externalSupplierId string 5415 — Supplier id (access control/filtering).
contentValue decimal 580 — Currency per shop locale.
contents string Brown shirt 100 Item description (may print on label).
properties map — — Product-specific properties.
articles array of article —