# Shipment

API endpoints for managing shipments (multi-manifest dispatch grouping).
A shipment groups one or more manifests for dispatch at a single gate; only available to organizations configured with the shipment dispatch strategy.

## Get shipment by external id or uuid

 - [GET /integration/rest/api/v1/shipment/{shipmentExternalId}](https://docs.zimark.link/api/shipment/getshipmentbyid.md): Resolution order: external identifier first, UUID fallback. Soft-deleted shipments return 404.

## Update a shipment

 - [PUT /integration/rest/api/v1/shipment/{shipmentExternalId}](https://docs.zimark.link/api/shipment/updateshipment.md): Partial update. Fields omitted (null) are left unchanged. The manifests list, when present, uses full-replacement semantics.

## Soft-delete a shipment

 - [DELETE /integration/rest/api/v1/shipment/{shipmentExternalId}](https://docs.zimark.link/api/shipment/deleteshipment.md): Allowed from any non-terminal state including IN_PROGRESS. Detaches all manifests and releases the external identifier for reuse.

## List shipments (paginated, filterable)

 - [GET /integration/rest/api/v1/shipment](https://docs.zimark.link/api/shipment/getshipments.md): Returns a paginated list of shipments for the authenticated caller's organization. Supports filtering by status (multi-valued), gate (by UUID or external id), free-text, and three independent date ranges (created, activated, closed). Null-date semantics: when any bound is supplied on activateDate or closeDate, shipments whose corresponding date field is null are excluded.

## Create shipment

 - [POST /integration/rest/api/v1/shipment](https://docs.zimark.link/api/shipment/createshipment.md): 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.

## Update shipment status (activate / complete / cancel)

 - [POST /integration/rest/api/v1/shipment/{shipmentExternalId}/status/{shipmentStatus}](https://docs.zimark.link/api/shipment/updatestatus.md): Unified status-update endpoint mirroring ManifestIntegrationController#updateManifestStatus. Accepts IN_PROGRESS (activate; requires gate assigned first), COMPLETED (from IN_PROGRESS), or CANCELLED (from TO_DO or IN_PROGRESS). Unknown status values return 400. Invalid transitions return 400.

## Attach one or more manifests to the shipment (all-or-nothing batch)

 - [POST /integration/rest/api/v1/shipment/{shipmentExternalId}/manifest](https://docs.zimark.link/api/shipment/addmanifests.md): All supplied manifests must exist, must be in PLANNED status, and must not be attached to another shipment. If any fails validation, the entire batch is rolled back.

## Detach one or more manifests from the shipment (all-or-nothing batch)

 - [DELETE /integration/rest/api/v1/shipment/{shipmentExternalId}/manifest](https://docs.zimark.link/api/shipment/removemanifests.md): All supplied manifests must be currently attached to the shipment. If any is not attached, the entire batch is rejected.

## Assign (or change) the shipment's gate

 - [POST /integration/rest/api/v1/shipment/{shipmentExternalId}/gate/{gateExternalId}](https://docs.zimark.link/api/shipment/assigngate.md): Mirrors ManifestIntegrationController#createManifestGate. The gateExternalId path variable accepts the gate's external identifier (primary) or internal uuid (fallback). Must be called before transitioning the shipment to IN_PROGRESS.

## Upsert a single custom field value on an existing shipment

 - [POST /integration/rest/api/v1/shipment/{shipmentExternalId}/custom-field](https://docs.zimark.link/api/shipment/upsertshipmentcustomfield.md): Adds or updates a custom field value. The fieldKey must match a configured custom field. For numeric fields, the value must be parseable as a number. Blank values remove the field.

## Asynchronously bulk-upsert Shipment fields (custom fields)

 - [POST /integration/rest/api/v1/shipment/bulk-upsert](https://docs.zimark.link/api/shipment/bulkupsert_1.md)

## Update shipment asset loading status by record uuid

 - [PATCH /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading/{recordUuid}/status](https://docs.zimark.link/api/shipment/updateassetloadingstatusbyrecorduuid.md): Updates a specific asset-loading record status within a shipment. Target status must be LOADED, NOT_LOADED, or UNLOADED. gateExternalId is required when target is NOT_LOADED or UNLOADED.

## Update shipment asset loading status by track identifier

 - [PATCH /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading/track/{trackIdentifier}/status](https://docs.zimark.link/api/shipment/updateassetloadingstatusbytrackidentifier.md): Updates every asset-loading record in the shipment whose WMS identifier matches {trackIdentifier}. When the same pallet is attached to multiple manifests in the shipment, all rows are updated (one audit + timeline entry per manifest).

## Update shipment asset loading status by marker value

 - [PATCH /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading/marker/{markerValue}/status](https://docs.zimark.link/api/shipment/updateassetloadingstatusbymarkervalue.md): Updates every asset-loading record in the shipment matching the marker value, with a Zimark-code fallback (marker → track → WMS id → records). Multi-manifest fan-out applies when the resolved WMS id is shared across manifests.

## Validate shipment (returns domain validation errors without mutating state)

 - [GET /integration/rest/api/v1/shipment/{shipmentExternalId}/validate](https://docs.zimark.link/api/shipment/validateshipment.md): Returns cancelled member manifests and per-manifest validation results (duplicated tracks, non-existing tracks, deactivated tracks) without modifying the shipment.

## List assets (tracks) across all manifests in the shipment

 - [GET /integration/rest/api/v1/shipment/{shipmentExternalId}/asset](https://docs.zimark.link/api/shipment/getshipmentassets.md): Returns a flattened list of track records spanning every non-cancelled manifest attached to the shipment. Each entry includes the track, its loading status, and the owning manifest reference.

## Get shipment asset loading details

 - [GET /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading](https://docs.zimark.link/api/shipment/getshipmentassetloading.md): Retrieves asset-loading records for every track dispatched under the shipment, including manifest-linked rows (LOADED, NOT_LOADED, UNLOADED, OFFLOADED) and dispatched/unauthorized rows (WRONGLY_LOADED, UNKNOWN_LOADING). Each record carries the recordUuid required by the shipment DELETE asset-loading endpoints.

## Delete shipment custom field

 - [DELETE /integration/rest/api/v1/shipment/{shipmentExternalId}/custom-field/{fieldKey}](https://docs.zimark.link/api/shipment/deleteshipmentcustomfield.md): Removes a specific custom field from a shipment by its key. The field and its value will be permanently deleted from the shipment.

## Delete shipment asset invalid-loading record by record uuid

 - [DELETE /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading/{recordUuid}](https://docs.zimark.link/api/shipment/deleteassetloadingrecordbyrecorduuid.md): Deletes an unassigned (non-expected) asset invalid-loading record. Returns 404 if the record does not belong to any manifest attached to this shipment.

## Delete shipment asset invalid-loading record by track identifier

 - [DELETE /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading/track/{trackIdentifier}](https://docs.zimark.link/api/shipment/deleteassetloadingrecordbytrackidentifier.md): Deletes an unassigned (non-expected) asset invalid-loading record resolved by track identifier.

## Delete shipment asset invalid-loading record by marker value

 - [DELETE /integration/rest/api/v1/shipment/{shipmentExternalId}/asset-loading/marker/{markerValue}](https://docs.zimark.link/api/shipment/deleteassetloadingrecordbymarkervalue.md): Deletes an unassigned (non-expected) asset invalid-loading record resolved by marker value.