--- title: "Update Shipment" method: PATCH path: "/shipments/{shipmentId}" --- # Update Shipment `PATCH /shipments/{shipmentId}` ## Request - Base URL: `https://api.cargoai.co/solutions` - URL: `https://api.cargoai.co/solutions/shipments/{shipmentId}` - Auth: API key in header `x-api-key` Updates an existing shipment record and returns 200 OK with the full record. Only the fields you send change, and version goes up by 1. ## Path parameters - `shipmentId` string, required ## Headers - `x-api-key` string, required ## Request body - object: Any subset of the shipment fields. Only the top-level keys present are changed. - `hawbNumber` string: House air waybill number issued by the forwarder. Required if no Master AWB Number provided in the request. - `mawbNumber` string: Master air waybill (AWB) number issued by the airline, format `XXX-NNNNNNNN`. Used to match booking callbacks. Required if no House AWB Number provided in the request. - `status` 'DRAFT' | 'BOOKED' | 'IN_TRANSIT' | 'AT_DESTINATION' | 'DELIVERED' | 'CANCELLED' | 'EXCEPTION': Overall status of the shipment. - `externalReferences` object[]: Your own references for the shipment, such as a PO or job number. - `scheme` string, required: Kind of reference. Free text, for example PO. - `value` string, required: The reference itself. - `dataSource` object: Who sent the data, from which system and when. - `forwarderId` string, required: Forwarder that owns the data. - `systemName` string: System that sent the record, for example your TMS. - `parties` object[]: Companies involved: shipper, consignee, forwarders, brokers. - `role` 'SHIPPER' | 'CONSIGNEE' | 'ORIGIN_FORWARDER' | 'PARTNER_FORWARDER' | 'ISSUING_CARRIER' | 'ISSUING_AGENT' | 'IMPORTER_OF_RECORD' | 'EXPORTER_OF_RECORD' | 'CUSTOMS_BROKER' | 'NOTIFY_PARTY', required: Part the company plays in the shipment. - `name` string, required: Company name. - `address` object, required: Company address. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `contact` object: Person to contact at the company. - `contactName` string: Name of the contact person. - `phone` string: Phone number. - `email` string: Email address. - `identifiers` object[]: Official IDs of the company, such as EORI or tax ID. - `type` 'IATA_AGENT_CODE' | 'EORI' | 'TAX_ID' | 'DUNS' | 'OTHER', required: Kind of identifier. - `value` string, required: The identifier itself. - `scheme` string: Name of the identifier system. Required when `type` is `OTHER`. - `goods` object: Summary of the cargo: pieces, weight, volume, nature. - `totalPieces` integer, required: Total number of pieces. - `totalGrossWeight` object, required: Total actual weight. - `value` number, required - `unit` 'kg' | 'lb', required - `totalChargeableWeight` object: Weight the freight is priced on, the greater of actual and volumetric weight. - `value` number, required - `unit` 'kg' | 'lb', required - `totalVolume` object: Total volume. - `value` number, required - `unit` 'm3' | 'ft3', required - `description` string, required: Nature of the goods. Must not be empty. - `specialHandlingCodes` string[]: Handling requirements for the whole shipment. IATA 3 letter SHC codes, for example ELI. - `pieces` object[]: Detail of each piece or group of identical pieces. - `pieceNumber` string: Your number or label for the piece. - `quantity` integer, required: Number of identical pieces this entry describes. - `grossWeight` object, required: Actual weight of the pieces. - `value` number, required - `unit` 'kg' | 'lb', required - `dimensions` object: Length, width and height of a piece. - `length` number, required - `width` number, required - `height` number, required - `unit` 'cm' | 'in', required - `description` string, required: What the pieces contain. - `specialHandlingCodes` string[]: Handling requirements for these pieces. - `routing` object: Origin, destination and flight legs. - `origin` object, required: Where the shipment starts. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `destination` object, required: Where the shipment ends. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `legs` object[], required: Flights from origin to destination, in order. - `legNumber` integer, required: Position of the leg in the route, starting at 1. - `departureLocation` object, required: Where the leg departs. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `arrivalLocation` object, required: Where the leg arrives. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `carrierCode` string: Airline operating the leg. IATA 2-letter airline code. - `carrierName` string: Airline name operating the leg. - `transportIdentifier` string: Flight operating the leg. Flight number, for example AF0011. - `scheduledDeparture` string: Planned departure time. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `scheduledArrival` string: Planned arrival time. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `customs` object: Customs declaration data. - `declarationType` string: Kind of declaration, for example EXPORT. - `commercialInvoiceReference` string: Number of the commercial invoice. - `packingListReference` string: Number of the packing list. - `totalDeclaredValue` object: Total value declared to customs. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `lines` object[], required: Declared goods, one line per HS code. - `lineNumber` integer, required: Position of the line in the declaration. - `hsCode` string, required: Harmonized System tariff code of the goods. 6 to 10 digits. - `description` string, required: Goods description for customs. - `quantity` number, required: Quantity declared. - `quantityUnit` string: Unit of the quantity, for example PCS. - `weight` object: Weight of the goods on this line. - `value` number, required - `unit` 'kg' | 'lb', required - `value` object, required: Declared value of the goods on this line. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `countryOfOrigin` string, required: Country where the goods were made. ISO 3166-1 alpha-2. - `financialLedger` object: Declared values and charges. - `declaredValueForCarriage` object: Value declared to the carrier, which sets its liability. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `declaredValueForCustoms` object: Value declared on the AWB for customs. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `charges` object[], required: Freight and other charges. - `description` string, required: What the charge is for. - `amount` object, required: Amount of the charge. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `paymentType` 'PREPAID' | 'COLLECT', required: Whether the charge is paid at origin or destination. - `entitlement` string: Who the charge is due to, AGENT or CARRIER. - `chargeCode` string: IATA charge code, for example FRT. - `isExpected` boolean, required: Whether the charge is an estimate. `true` for an estimated charge. - `totalPrepaid` object: Total of charges paid at origin. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `totalCollect` object: Total of charges paid at destination. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `milestones` object[]: Expected and actual events of the shipment. On PATCH, merged by `code`. - `code` 'PICKED_UP_FROM_SHIPPER' | 'ARRIVAL_AT_EXPORT_WAREHOUSE' | 'TRANSFERRED_TO_AIRLINE' | 'RECEIVED_BY_AIRLINE' | 'DEPARTED_ORIGIN_AIRPORT' | 'ARRIVED_DESTINATION_AIRPORT' | 'RECOVERED_FROM_AIRLINE' | 'CUSTOMS_ENTRY_SUBMITTED' | 'CUSTOMS_CLEARED' | 'DUTY_AND_TAX_PAID' | 'OUT_FOR_DELIVERY' | 'DELIVERED' | 'EXCEPTION', required: Type of event. Unique per shipment. - `label` string: Display name of the event. - `expectedAt` string: When the event is planned. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `actualAt` string: When the event happened. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `location` object: Where the event takes place. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `reportedBy` string: Who reported the event. - `notes` string: Free-text detail, such as the cause of an exception. Required when `code` is `EXCEPTION`. ## Response `200` OK. The full merged shipment. - object: The full stored shipment. Optional fields are left out when empty. - `shipmentId` string, required: Unique ID of the record, used in PATCH calls. UUID set by the server. - `version` integer, required: Revision number of the record. 1 on create, +1 on each PATCH. - `hawbNumber` string: House air waybill number issued by the forwarder. Required if no Master AWB Number provided in the request. - `mawbNumber` string: Master air waybill (AWB) number issued by the airline, format `XXX-NNNNNNNN`. Used to match booking callbacks. Required if no House AWB Number provided in the request. - `status` 'DRAFT' | 'BOOKED' | 'IN_TRANSIT' | 'AT_DESTINATION' | 'DELIVERED' | 'CANCELLED' | 'EXCEPTION', required: Overall status of the shipment. - `createdAt` string, required: When the record was created. RFC 3339, UTC. Set by the server. - `lastUpdatedAt` string, required: When the record was last changed. RFC 3339, UTC. Set by the server. - `dataSource` object, required: Who sent the data, from which system and when. - `forwarderId` string, required: Forwarder that owns the data. - `systemName` string: System that sent the record, for example your TMS. - `pushedAt` string: Time of the last write. Set by the server on every write. - `externalReferences` object[]: Your own references for the shipment, such as a PO or job number. - `scheme` string, required: Kind of reference. Free text, for example PO. - `value` string, required: The reference itself. - `parties` object[]: Companies involved: shipper, consignee, forwarders, brokers. - `role` 'SHIPPER' | 'CONSIGNEE' | 'ORIGIN_FORWARDER' | 'PARTNER_FORWARDER' | 'ISSUING_CARRIER' | 'ISSUING_AGENT' | 'IMPORTER_OF_RECORD' | 'EXPORTER_OF_RECORD' | 'CUSTOMS_BROKER' | 'NOTIFY_PARTY', required: Part the company plays in the shipment. - `name` string, required: Company name. - `address` object, required: Company address. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `contact` object: Person to contact at the company. - `contactName` string: Name of the contact person. - `phone` string: Phone number. - `email` string: Email address. - `identifiers` object[]: Official IDs of the company, such as EORI or tax ID. - `type` 'IATA_AGENT_CODE' | 'EORI' | 'TAX_ID' | 'DUNS' | 'OTHER', required: Kind of identifier. - `value` string, required: The identifier itself. - `scheme` string: Name of the identifier system. Required when `type` is `OTHER`. - `goods` object: Summary of the cargo: pieces, weight, volume, nature. - `totalPieces` integer, required: Total number of pieces. - `totalGrossWeight` object, required: Total actual weight. - `value` number, required - `unit` 'kg' | 'lb', required - `totalChargeableWeight` object: Weight the freight is priced on, the greater of actual and volumetric weight. - `value` number, required - `unit` 'kg' | 'lb', required - `totalVolume` object: Total volume. - `value` number, required - `unit` 'm3' | 'ft3', required - `description` string, required: Nature of the goods. Must not be empty. - `specialHandlingCodes` string[]: Handling requirements for the whole shipment. IATA 3 letter SHC codes, for example ELI. - `pieces` object[]: Detail of each piece or group of identical pieces. - `pieceNumber` string: Your number or label for the piece. - `quantity` integer, required: Number of identical pieces this entry describes. - `grossWeight` object, required: Actual weight of the pieces. - `value` number, required - `unit` 'kg' | 'lb', required - `dimensions` object: Length, width and height of a piece. - `length` number, required - `width` number, required - `height` number, required - `unit` 'cm' | 'in', required - `description` string, required: What the pieces contain. - `specialHandlingCodes` string[]: Handling requirements for these pieces. - `routing` object: Origin, destination and flight legs. - `origin` object, required: Where the shipment starts. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `destination` object, required: Where the shipment ends. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `legs` object[], required: Flights from origin to destination, in order. - `legNumber` integer, required: Position of the leg in the route, starting at 1. - `departureLocation` object, required: Where the leg departs. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `arrivalLocation` object, required: Where the leg arrives. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `carrierCode` string: Airline operating the leg. IATA 2-letter airline code. - `carrierName` string: Airline name operating the leg. - `transportIdentifier` string: Flight operating the leg. Flight number, for example AF0011. - `scheduledDeparture` string: Planned departure time. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `scheduledArrival` string: Planned arrival time. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `customs` object: Customs declaration data. - `declarationType` string: Kind of declaration, for example EXPORT. - `commercialInvoiceReference` string: Number of the commercial invoice. - `packingListReference` string: Number of the packing list. - `totalDeclaredValue` object: Total value declared to customs. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `lines` object[], required: Declared goods, one line per HS code. - `lineNumber` integer, required: Position of the line in the declaration. - `hsCode` string, required: Harmonized System tariff code of the goods. 6 to 10 digits. - `description` string, required: Goods description for customs. - `quantity` number, required: Quantity declared. - `quantityUnit` string: Unit of the quantity, for example PCS. - `weight` object: Weight of the goods on this line. - `value` number, required - `unit` 'kg' | 'lb', required - `value` object, required: Declared value of the goods on this line. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `countryOfOrigin` string, required: Country where the goods were made. ISO 3166-1 alpha-2. - `financialLedger` object: Declared values and charges. - `declaredValueForCarriage` object: Value declared to the carrier, which sets its liability. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `declaredValueForCustoms` object: Value declared on the AWB for customs. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `charges` object[], required: Freight and other charges. - `description` string, required: What the charge is for. - `amount` object, required: Amount of the charge. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `paymentType` 'PREPAID' | 'COLLECT', required: Whether the charge is paid at origin or destination. - `entitlement` string: Who the charge is due to, AGENT or CARRIER. - `chargeCode` string: IATA charge code, for example FRT. - `isExpected` boolean, required: Whether the charge is an estimate. `true` for an estimated charge. - `totalPrepaid` object: Total of charges paid at origin. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `totalCollect` object: Total of charges paid at destination. - `amount` number, required: The amount. - `currency` string, required: Currency of the amount. ISO 4217, for example USD. - `milestones` object[]: Expected and actual events of the shipment. On PATCH, merged by `code`. - `code` 'PICKED_UP_FROM_SHIPPER' | 'ARRIVAL_AT_EXPORT_WAREHOUSE' | 'TRANSFERRED_TO_AIRLINE' | 'RECEIVED_BY_AIRLINE' | 'DEPARTED_ORIGIN_AIRPORT' | 'ARRIVED_DESTINATION_AIRPORT' | 'RECOVERED_FROM_AIRLINE' | 'CUSTOMS_ENTRY_SUBMITTED' | 'CUSTOMS_CLEARED' | 'DUTY_AND_TAX_PAID' | 'OUT_FOR_DELIVERY' | 'DELIVERED' | 'EXCEPTION', required: Type of event. Unique per shipment. - `label` string: Display name of the event. - `expectedAt` string: When the event is planned. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `actualAt` string: When the event happened. RFC 3339. Explicit offset required, for example `Z` or `+02:00`. - `location` object: Where the event takes place. - `iataCode` string: Airport of the location. IATA 3-letter code, for example CDG. - `name` string: Name of the location, such as a warehouse. - `address` object: Street address of the location. - `street` string, required: Street name and number. - `city` string, required: City. - `postalCode` string: Postal or ZIP code. - `state` string: State, province or region. - `country` string, required: Country code ISO 3166-1 alpha-2. - `reportedBy` string: Who reported the event. - `notes` string: Free-text detail, such as the cause of an exception. Required when `code` is `EXCEPTION`. ## Other responses - `400`: Validation failed, or malformed JSON. - `404`: Unknown shipmentId, or a shipment created by another organization. ## Changes - **2026-11-03** `dfd7950d43d7`: 1 info - endpoint added [Operation history](https://skmtc.dev/cargoai/apis/solutions/changes/shipments/:shipmentId/patch.md) --- [API](https://skmtc.dev/cargoai/apis/solutions.md) - [All operations](https://skmtc.dev/cargoai/apis/solutions/llms.txt) - [OpenAPI document](https://skmtc.dev/cargoai/apis/solutions/revisions/dfd7950d43d7?raw)