---
title: "Creates a shipment plan"
method: POST
path: "/shipments/v4/plans"
tags: ["Shipments"]
---

# Creates a shipment plan

`POST /shipments/v4/plans`

Creates a new shipment plan. A shipment plan is a structure that holds information about a
recurring shipment. Like a shipment, a shipment plan also consists of segments each
representing a part of the logistics journey. A segment spans from a location to another and
each segment may be assigned a different tracking device. The segments of the shipment must form a
continuous chain of locations, that is the origin of a segment must match the destination of a
previous segment.

In addition to shipments, a predefined duration can be assigned to each segment in the plan.
This information will be used to calculate the Estimated Time of Departure (ETD) and
Estimated Time of Arrival (ETA) when instantiating a shipment from a shipment plan.

## Request body

- union
  - object
    - `autoStart` boolean — A boolean parameter defining whether the shipment starts upon exiting the first origin location.
    - `description` string — Description of the shipment
    - `name` string — Name of the shipment
    - `ruleIds` string[] — Array of `ruleId`s to associate with the shipment
    - `segments` object[], required — Array of objects each defining the origin and destination of the segment
      - `description` string — Description of the segment
      - `destination` string, required — Destination location of this segment
      - `durationS` integer — Segment duration in seconds.
      - `name` string — Name of the segment
      - `origin` string, required — Origin location of this segment
      - `trackingId` string — ID of the tracking device that produces data for this segment
      - `transportMode` 'car' | 'truck' | 'sea' | 'air' | 'undefined', required — Transport mode of the segment
    - `subShipment` boolean — Flag telling if shipment is a subShipment.
  - object
    - `options` object — Optional parameters for plan creation
      - `calculateDurationsFrom` 'actuals' | 'providedEstimate' | 'calculatedEstimate' — If defined, the durations of the segments in the plan will be based on the durations of the segments of the provided shipment
      - `copyTrackingIds` boolean — If set to `true`, trackingIds in the segments of the provided shipment are copied to the plan
    - `shipmentId` string, required — Shipment ID

## Response `201`

Created.

The shipment plan has been successfully created.

- object
  - `shipmentPlanId` string, required — Shipment plan ID

## Other responses

- `400` — Bad request The request object is in an incorrect format or has values that are invalid or out of range. If available, further error details are provided in the response body.
- `401` — Unauthorized The request did not provide correct authentication details
- `403` — Forbidden The account does not have the correct privileges
- `404` — Not Found The specified resource was not found

---

[API](https://skmtc.net/here/apis/tracking.md) · [All operations](https://skmtc.net/here/apis/tracking/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/here/tracking/versions/efa162f7023c/schema)