# Create shipment

Creates a new shipment in status TO_DO. Optional external identifier, optional gate (by external id or uuid), optional notes, optional manifest list. Returns the full shipment payload.

Endpoint: POST /integration/rest/api/v1/shipment
Version: v0
Security: X-AUTH-KEY

## Request fields (application/json):

  - `identifier` (string, required)
    Required. Caller-assigned shipment external identifier, unique per organization within the Shipment namespace. May collide with Manifest external identifiers (independent namespaces).

  - `gateIdentifier` (string)
    Gate to attach at create time. Accepts the gate external identifier OR internal UUID.

  - `notes` (string)
    Free-text notes attached to the shipment.

  - `manifests` (array, required)
    Required. List of manifest references to attach at create. Must be non-empty. Each manifest must be in PLANNED status and not already attached to another shipment.

  - `manifests.manifestExternalId` (string)
    Caller-assigned manifest external identifier.

  - `manifests.manifestUuid` (string)
    Internal manifest identifier (uuid).

  - `customFields` (array)
    Optional custom field values to set on the shipment. Each entry must reference a configured field key.

  - `customFields.deepLink` (string)
    Deep link URL to open this entity in Ops.App.

  - `customFields.fieldKey` (string, required)
    Unique key (name) of the custom field. This must match the configured field name.

  - `customFields.fieldValue` (string)
    Value of the custom field as a string. For numeric fields, send the number as a string.

## Response 200 fields (*/*):

  - `createDate` (string)

  - `updateDate` (string)

  - `deepLink` (string)
    Deep link URL to open this entity in Ops.App.

  - `externalIdentifier` (string)
    Caller-assigned external identifier, unique per organization within the Shipment namespace.

  - `status` (string)
    Lifecycle status of the shipment.
    Enum: "PLANNED", "TO_DO", "IN_PROGRESS", "COMPLETED", "CANCELLED"

  - `gate` (object)
    Gate currently assigned to the shipment, if any.

  - `gate.name` (string)
    Human-readable gate name.

  - `gate.externalIdentifier` (string)
    External unique identifier of the gate.

  - `gate.status` (string)
    Current operational status of the gate.
    Enum: "AVAILABLE", "LOADING", "OUT_OF_SERVICE"

  - `gate.gateType` (string)
    Gate type. SINGLE_MANIFEST allows one active manifest at a time; MULTI_MANIFEST allows several manifests active simultaneously.
    Enum: "SINGLE_MANIFEST", "MULTI_MANIFEST"

  - `manifests` (array)
    Manifests currently attached to the shipment.

  - `manifests.uuid` (string)
    Internal manifest identifier (uuid).

  - `manifests.externalIdentifier` (string)
    Caller-assigned manifest external identifier, if any.

  - `manifests.manifestStatus` (string)
    Current manifest status.
    Enum: "PLANNED", "TO_DO", "IN_PROGRESS", "COMPLETED", "CANCELLED"

  - `tracksCount` (integer)
    Planning view: total tracks (assets) currently included across this shipment's manifests, regardless of loading state. For Total/Loaded execution counts use totalAssetsCount and loadedAssetsCount.

  - `totalAssetsCount` (integer)
    Total assets attached to the shipment, excluding invalid loadings (WRONGLY_LOADED, UNKNOWN_LOADING) and records belonging to cancelled manifests.

  - `loadedAssetsCount` (integer)
    Successfully loaded assets, excluding invalid loadings and records belonging to cancelled manifests.

  - `notes` (string)
    Optional free-text notes.

  - `activateDate` (string)
    Timestamp when the shipment transitioned to IN_PROGRESS, null if not yet activated.

  - `closeDate` (string)
    Timestamp when the shipment transitioned to a terminal status (COMPLETED or CANCELLED), null if still active.

  - `deleted` (boolean)
    Soft-delete flag. Deleted shipments are excluded from list and get endpoints.

  - `customFields` (array)
    Custom field values set on this shipment. Omitted when the organization's dispatch strategy is not SHIPMENT.

  - `customFields.fieldKey` (string, required)
    Unique key (name) of the custom field. This must match the configured field name.

  - `customFields.fieldValue` (string)
    Value of the custom field as a string. For numeric fields, send the number as a string.

## Response 400 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 403 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id

## Response 500 fields (*/*):

  - `code` (string)
    Error code

  - `message` (string)
    Error message

  - `timeStamp` (integer)
    Timestamp

  - `correlationId` (string)
    Correlation id