Update voyage details | PurpleTRAC API

You normally supply voyage details when you enable tracking, as Tracking a Vessel describes. Plans move once the voyage is under way. A vessel is rerouted, a discharge port is confirmed, a charterer sends a new reference, or a track needs to run longer than anyone first expected.

One call amends the voyage and tracking configuration of an existing transaction in place, so the transaction and its screening history stay intact.

Method	Purpose
`PUT /transaction/{id}/voyage_update`	Update the voyage and tracking details of an existing transaction

The {id} path parameter is the transaction id of the vessel, the same id used throughout the tracking workflow, and the transaction has to belong to the authenticated user.

No voyage needs to exist first

If the transaction has no voyage recorded against it, we create one from the fields in your request. There is no separate call to create a voyage.

Before you start

Two conditions apply.

Bill of Lading tracking. Vessels tracked from a Bill of Lading reject this call with a 400. We maintain the voyage on those transactions from carrier data. Bill of Lading Verification covers that workflow.

Billing plan. On a pay-as-you-go plan we ignore tracking_expiry and apply only auto_deregister and client_reference. Tracking duration on those accounts is set per registration.

Update the voyage

Send only the fields that need to change. We leave anything you omit as it is.

Full update

Extend tracking only

Four things about the request fields.

departure_port, destination_port and interim_ports take UNLOCODEs. interim_ports accepts a single port code or a list.

Dates and times go in separate fields, DD/MM/YYYY and HH:MM. Always pair a date with its time: departure_date with departure_time, arrival_date with arrival_time.

tracking_expiry breaks that pattern. It is one ISO 8601 value in UTC with a Z suffix, for example 2026-09-08T00:00:00Z, and comes back in the response without the Z.

client_reference is the freeform reference set when the vessel was registered. A new value replaces whatever the transaction already held.

Bad ports and dates are skipped, not rejected

We skip invalid port codes and invalid date or time values and apply everything else, so the call returns 200 and a mistyped UNLOCODE leaves that part of the voyage unchanged. Compare the response against what you sent to confirm an update landed. A malformed tracking_expiry behaves differently and returns 500.

The response

You get the updated transaction, in the same shape returned when you enable tracking.

{
  "added_via": "MANUAL",
  "ais_gap_status": "N",
  "ais_received": null,
  "ais_reporting": true,
  "auto_deregister": false,
  "auto_deregistered": false,
  "auto_register": true,
  "blv": null,
  "carbon_rating_screen": false,
  "client_reference": "REF-2024-001",
  "closed_date": null,
  "container_screen_id": null,
  "creation_date": "2026-06-09T13:45:31.126526",
  "dbi_status": null,
  "deregistration_reason": null,
  "has_gaps": null,
  "id": 985724,
  "inmarsatc_expected": null,
  "inmarsatc_interval": 2,
  "inmarsatc_received": null,
  "inmarsatc_reporting": false,
  "only_tracking_by_ais": true,
  "overall_severity": "CRITICAL",
  "pandi_club_screen": false,
  "positional_discrepancy_status": null,
  "registered_date": "2026-06-10T06:06:36.215804",
  "registered_name": "8121977",
  "report_generation_complete": true,
  "resource_uri": "/api/v1/transaction/985724",
  "screened_date": "2026-06-09T13:45:32.506610",
  "screening_status": "CRITICAL",
  "ship": "/api/v1/shipdetails/202198",
  "status": "A",
  "sts_overall_severity": null,
  "tracking_date": "2026-06-10T06:39:56.525488",
  "tracking_expiry": "2026-09-08T00:00:00",
  "transceiver_domain": "",
  "transceiver_domain_id": "",
  "user": "/api/v1/user/7718",
  "voyage": "/api/v1/voyage/22661"
}

The voyage field carries the resource URI of the voyage held against the transaction. On a transaction that had no voyage before the call, that is the voyage we just created.

Error responses

Status	Cause
`400`	The vessel is tracked from a Bill of Lading, or the body could not be read as JSON
`401`	Missing or wrong `username` and `api_key` pair
`403`	The transaction sits on a different account from the credentials you sent
`404`	The transaction does not exist
`500`	System failure, or `tracking_expiry` supplied in a format other than `YYYY-MM-DDTHH:MM:SSZ`

Errors and Status Codes has the body shapes behind these.

Tracking a Vessel

Set the voyage details in the first place, and read positions.

Tracking Notifications

The arrival and departure events these ports and dates drive.

Managing Additional Entities

The other thing you can change while a track is running.

Updating Voyage Details

Before you start#

Update the voyage#

The response#

Error responses#

Related#

Before you start

Update the voyage

The response

Error responses

Related