# Update a shipment

Partial update. Fields omitted (null) are left unchanged. The manifests list, when present, uses full-replacement semantics.

Endpoint: PUT /integration/rest/api/v1/shipment/{shipmentExternalId}
Version: v0
Security: X-AUTH-KEY

## Path parameters:

  - `shipmentExternalId` (string, required)
    Shipment external identifier or uuid.

## Request fields (application/json):

  - `identifier` (string)
    Caller-assigned shipment external identifier. Immutable — supplying a different value than the current value returns 400. May be omitted (null) on update.

  - `gateIdentifier` (string)
    Gate to assign (accepts external identifier or uuid). Set to empty string to clear the gate assignment.

  - `notes` (string)
    Free-text notes.

  - `manifests` (array)
    Full-replacement manifest list. When present, replaces the current set; omitted manifests are detached. When null, the manifest list is left unchanged. An empty list is rejected with 400 — a shipment must always contain at least one manifest.

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

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

  - `customFields` (array)
    Full-replacement custom field list. When present, replaces the current set; omitted keys are removed. When null, custom fields are left unchanged. Blank values are ignored.

  - `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 404 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