Charter

Charter bookings.

GET/charter/{vesselId}/bookings

List a vessel's charter bookings

Supports `?cursor=` pagination. Bookings are annotated `isLocked: true` when the owning vessel's plan has downgraded below the `bookings_guests` feature tier.

Path parameters

Name	In	Type	Required	Description
vesselId	path	string (uuid)	required	—

Query parameters

Name	In	Type	Required	Description
cursor	query	string	optional	Opaque pagination cursor from a previous response's `pagination.cursor`. Omit this param entirely for the first page of cursor mode; pass `cursor=` (empty) is also accepted as "start from the beginning in cursor mode." Omitting `cursor` altogether (not even as an empty string) falls back to legacy `?page=` semantics on endpoints that still support it.
limit	query	integer	optional	—

Response

Field	Type	Required	Description
data	array<object>	required	—
data[].id	string (uuid)	optional	—
data[].vesselId	string (uuid) \| null	optional	—
data[].bookingReference	string	optional	—
data[].charterCompany	string \| null	optional	—
data[].startDate	string (date-time)	optional	—
data[].endDate	string (date-time)	optional	—
data[].embarkPort	string \| null	optional	—
data[].disembarkPort	string \| null	optional	—
data[].itinerary	object \| array \| null	optional	—
data[].totalPrice	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].currency	string	optional	—
data[].depositPaid	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].status	enum(inquiry \| confirmed \| in_progress \| completed \| cancelled)	optional	—
data[].specialRequests	string \| null	optional	—
data[].provisioningNotes	string \| null	optional	—
data[].notes	string \| null	optional	—
data[].apaAmount	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].apaPercentage	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].deliveryFee	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].redeliveryFee	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].taxRate	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].taxAmount	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].brokerName	string \| null	optional	—
data[].brokerCommission	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].agentCommission	string \| null	optional	Serialized as string to preserve Decimal precision.
data[].isArchived	boolean	optional	—
data[].isLocked	boolean	optional	Present only when the plan has downgraded below bookings_guests full-charter access.
data[].lockReason	string	optional	—
data[].guests	array<object>	optional	—
data[].guests[].id	string (uuid)	optional	—
data[].guests[].profile	object	optional	—
data[].createdAt	string (date-time)	optional	—
data[].updatedAt	string (date-time)	optional	—
pagination	object	optional	Canonical cursor-pagination block. On endpoints not yet retrofitted for true cursor support, `cursor` is a best-effort display-only value (not decodable, no `?cursor=` branch accepts it back) — see each endpoint's description for whether it has full cursor support.
pagination.cursor	string \| null	optional	Opaque token for the next page, or `null` when `hasMore` is `false`.
pagination.limit	integer	required	—
pagination.hasMore	boolean	required	—
pagination.total	integer	required	Total row count matching the filter (not just this page).
meta	object	optional	Endpoint-specific extra fields promoted out of the top level by envelope normalization (e.g. `totalAmount`, `planContext`, `hasApproximations`).

POST/charter/{vesselId}/bookings

Create a charter booking

Requires `bookingReference`, `startDate`, `endDate`. Financial fields (`totalPrice`, `apaAmount`, broker/agent commissions, etc.) are silently stripped unless the vessel's plan is Pro tier or higher for `bookings_guests`.

Path parameters

Name	In	Type	Required	Description
vesselId	path	string (uuid)	required	—

Request body

Field	Type	Required	Description
bookingReference	string	required	—
charterCompany	string	optional	—
startDate	string (date-time)	required	—
endDate	string (date-time)	required	—
embarkPort	string	optional	—
disembarkPort	string	optional	—
itinerary	object	optional	—
totalPrice	string	optional	Silently stripped unless the vessel plan is bookings_guests Pro+. Serialized as string to preserve Decimal precision.
currency	string	optional	—
depositPaid	string	optional	Serialized as string to preserve Decimal precision.
status	enum(inquiry \| confirmed \| in_progress \| completed \| cancelled)	optional	—
specialRequests	string	optional	—
provisioningNotes	string	optional	—
notes	string	optional	—
apaAmount	string	optional	Serialized as string to preserve Decimal precision.
apaPercentage	string	optional	Serialized as string to preserve Decimal precision.
deliveryFee	string	optional	Serialized as string to preserve Decimal precision.
redeliveryFee	string	optional	Serialized as string to preserve Decimal precision.
taxRate	string	optional	Serialized as string to preserve Decimal precision.
taxAmount	string	optional	Serialized as string to preserve Decimal precision.
brokerName	string	optional	—
brokerCommission	string	optional	Serialized as string to preserve Decimal precision.
agentCommission	string	optional	Serialized as string to preserve Decimal precision.

Response

Field	Type	Required	Description
data	object	required	—
data.id	string (uuid)	optional	—
data.vesselId	string (uuid) \| null	optional	—
data.bookingReference	string	optional	—
data.charterCompany	string \| null	optional	—
data.startDate	string (date-time)	optional	—
data.endDate	string (date-time)	optional	—
data.embarkPort	string \| null	optional	—
data.disembarkPort	string \| null	optional	—
data.itinerary	object \| array \| null	optional	—
data.totalPrice	string \| null	optional	Serialized as string to preserve Decimal precision.
data.currency	string	optional	—
data.depositPaid	string \| null	optional	Serialized as string to preserve Decimal precision.
data.status	enum(inquiry \| confirmed \| in_progress \| completed \| cancelled)	optional	—
data.specialRequests	string \| null	optional	—
data.provisioningNotes	string \| null	optional	—
data.notes	string \| null	optional	—
data.apaAmount	string \| null	optional	Serialized as string to preserve Decimal precision.
data.apaPercentage	string \| null	optional	Serialized as string to preserve Decimal precision.
data.deliveryFee	string \| null	optional	Serialized as string to preserve Decimal precision.
data.redeliveryFee	string \| null	optional	Serialized as string to preserve Decimal precision.
data.taxRate	string \| null	optional	Serialized as string to preserve Decimal precision.
data.taxAmount	string \| null	optional	Serialized as string to preserve Decimal precision.
data.brokerName	string \| null	optional	—
data.brokerCommission	string \| null	optional	Serialized as string to preserve Decimal precision.
data.agentCommission	string \| null	optional	Serialized as string to preserve Decimal precision.
data.isArchived	boolean	optional	—
data.isLocked	boolean	optional	Present only when the plan has downgraded below bookings_guests full-charter access.
data.lockReason	string	optional	—
data.guests	array<object>	optional	—
data.guests[].id	string (uuid)	optional	—
data.guests[].profile	object	optional	—
data.createdAt	string (date-time)	optional	—
data.updatedAt	string (date-time)	optional	—

GET/charter/{vesselId}/bookings/{bookingId}

Get a charter booking

Returns `{ data: { booking: BookingDetail, planContext: {...} } }` — the booking is nested under a `booking` key (not returned bare), matching what the underlying handler emits before envelope normalization wraps the whole thing in `data`.

Path parameters

Name	In	Type	Required	Description
vesselId	path	string (uuid)	required	—
bookingId	path	string (uuid)	required	—

Response

Field	Type	Required	Description
data	object	required	—
data.booking	any	optional	—
data.planContext	object	optional	—
data.planContext.isEnabled	boolean	optional	—
data.planContext.currentTier	string \| null	optional	—