Create a Shipment Plan

In this tutorial, we continue with the same topic as in create a shipment, and we create a shipment plan for the same route which goes from Tampere-Pirkkala airport to Berlin Brandenburg airport through Helsinki airport by airplane.

📘
Note
Shipment plan APIs (/shipments/v4/plans) have been deprecated.

Prerequisites

A valid HERE account user
A valid Tracking project
A claimed device
Geofences and locations as they are defined in the create a shipment tutorial

Log in user

Create shipment plan

To create a shipment plan, send a request to the shipment plans endpoint.

curl -X POST \
    'https://{tcHost}/shipments/v4/plans' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"From Tampere-Pirkkala to Berlin Brandenburg",
        "description":"A shipment from the Tampere-Pirkkala airport to the Berlin Brandenburg airport",
        "autoStart":"true",
        "segments": [
            {
                "name":"From Tampere-Pirkkala to Helsinki",
                "description":"Origin of the shipment",
                "transportMode":"air",
                "origin":"LOC-f79d965d-9124-446d-b0b4-f71ae793f602",
                "destination"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "durationS":"3600"
            },
            {
                "name":"Dwelling at Helsinki",
                "description":"Waypoint of the shipment where shipment dwells",
                "transportMode":"undefined",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "durationS":"22500"
            },
            {
                "name":"From Helsinki to Brandenburg",
                "description":"Destination of the shipment",
                "transportMode":"air",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination"LOC-878c8e9e-2821-11ec-8fc2-00155ddd7ddb",
                "durationS":"9000"
            }
        ]
    }'

{
  "shipmentPlanId": "SHPP-3de93876-2837-11ec-aecc-00155ddd7ddb"
}

Create a shipment from shipment plan

The shipment plan serves as a template which can be used for creating shipments with prefilled details. To create a shipment, send a request to the shipments endpoint.

curl -X POST \
    'https://{tcHost}/shipments/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "shipmentPlanId":"SHPP-3de93876-2837-11ec-aecc-00155ddd7ddb",
        "shipmentDeparture":"2021-10-01T06:30:00Z"
    }'

{
  "shipmentPlanId": "SHP-8bd8fbe6-2839-11ec-bc08-00155ddd7ddb"
}

Assign a device to the segments

This shipment will use a single device in each of the segments. Send a request to the shipments endpoint.

curl -X PATCH \
    'https://{tcHost}/shipments/v4/SHP-8bd8fbe6-2839-11ec-bc08-00155ddd7ddb' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"From Tampere-Pirkkala to Berlin Brandenburg",
        "description":"A shipment from the Tampere-Pirkkala airport to the Berlin Brandenburg airport",
        "autoStart":"true",
        "segments": [
            {
                "transportMode":"air",
                "trackingId":"{trackingId}",
                "origin":"LOC-f79d965d-9124-446d-b0b4-f71ae793f602",
                "destination":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb"
            },
            {
                "transportMode":"undefined",
                "trackingId":"{trackingId}",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb"
            },
            {
                "transportMode":"air",
                "trackingId":"{trackingId}",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination":"LOC-878c8e9e-2821-11ec-8fc2-00155ddd7ddb"
            }
        ]
    }'

This will assign the device to the segments and return an empty response with status code 204 if successful.