POST /v1/shipments

Attach or update the shipment of a deal

One shipment per deal: the first call attaches the container / bill of lading, later calls update it. If a container or B/L number is given the container tracker is queried immediately; a tracker failure is returned in warnings and the shipment is still saved. Emits shipment.updated (webhook). Supports Idempotency-Key. Requires scope write:deals.

Authentication: header Authorization: Bearer rv_live_... (API keys and scopes)
Required scope: write:deals

Descriptions of the operation, parameters and fields come from the OpenAPI specification (openapi.json).

Parameters

Field	In	Type	Required	Description
`idempotency-key`	header	`string`	no	Makes a retry of this POST safe for 24 hours: the same key and body returns the stored response (Idempotent-Replay: true).

Request body

Field	Type	Required
`dealId`	`string (uuid)`	yes
`mode`	`"container" \| "roro" \| "truck"`	no
`containerNo`	`string`	no
`billOfLading`	`string`	no
`bookingNo`	`string`	no
`carrier`	`string`	no
`vessel`	`string`	no
`portFrom`	`string`	no
`portTo`	`string`	no
`warehouse`	`string`	no
`etd`	`string (date-time)`	no
`eta`	`string (date-time)`	no
`trackingProvider`	`"shipsgo" \| "terminal49" \| "manual"`	no
`refresh`	`boolean`	no

Responses

200

The shipment after the update.

application/json · Schema: Shipment

Field	Type	Required	Description
`id`	`string (uuid)`	yes
`dealId`	`string (uuid)`	yes
`status`	`"planned" \| "booked" \| "loaded" \| "in_transit" \| "at_port" \| "discharged" \| "released" \| "delivered"`	yes
`containerNo`	`string \| null`	yes
`billOfLading`	`string \| null`	yes
`vessel`	`string \| null`	yes
`portFrom`	`string \| null`	yes
`portTo`	`string \| null`	yes
`etd`	`string \| null`	yes	ISO 8601 date-time (UTC).
`eta`	`string \| null`	yes	ISO 8601 date-time (UTC).
`ata`	`string \| null`	yes	ISO 8601 date-time (UTC).
`events`	`object[]`	yes
`events[].at`	`string`	no
`events[].code`	`string`	no
`events[].description`	`string`	no
`events[].location`	`string`	no
`events[].vessel`	`string`	no
`lastTrackedAt`	`string \| null`	yes	ISO 8601 date-time (UTC).
`warnings`	`string[]`	yes