{ "$schema": "https://json-schema.org/draft/2020-12/schema", "$id": "https://raw.githubusercontent.com/api-evangelist/evergreen-marine/main/json-schema/evergreen-marine-update-shipping-instructions-schema.json", "title": "Update Shipping Instructions", "description": "The `Shipping Instructions` to update.\n", "x-generated": "2026-10-18", "x-method": "derived", "x-generator": "derive-json-schema.py", "x-source": "openapi/evergreen-marine-shipping-instructions-openapi.yml#/components/schemas/UpdateShippingInstructions", "type": "object", "properties": { "shippingInstructionsReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 100, "description": "The identifier for a `Shipping Instructions` provided by the carrier for system purposes.\n" }, "transportDocumentTypeCode": { "type": "string", "description": "Specifies the type of the transport document\n- `BOL` (Bill of Lading)\n- `SWB` (Sea Waybill)\n", "enum": [ "BOL", "SWB" ] }, "isShippedOnBoardType": { "type": "boolean", "description": "Specifies whether the Transport Document is a received for shipment, or shipped on board.\n" }, "freightPaymentTermCode": { "type": "string", "description": "An indicator of whether freight and ancillary fees for the main transport are prepaid (`PRE`) or collect (`COL`). When prepaid the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", "enum": [ "PRE", "COL" ] }, "originChargesPaymentTerm": { "$ref": "#/$defs/OriginChargesPaymentTerm" }, "destinationChargesPaymentTerm": { "$ref": "#/$defs/DestinationChargesPaymentTerm" }, "isElectronic": { "type": "boolean", "description": "An indicator whether the transport document is electronically transferred.\n" }, "isToOrder": { "type": "boolean", "description": "Indicates whether the B/L is issued `to order` or not. If `true`, the B/L is considered negotiable and an Endorsee party can be defined in the Document parties. If no Endorsee is defined, the B/L is blank endorsed. If `false`, the B/L is considered non-negotiable (also referred to as `straight`).\n\n`isToOrder` must be `false` if `transportDocumentTypeCode='SWB'` (Sea Waybill).\n" }, "numberOfCopiesWithCharges": { "type": "integer", "format": "int32", "minimum": 0, "description": "The requested number of copies of the `Transport Document` to be issued by the carrier including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier with charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges should be included in the electronic `SWB`|\n" }, "numberOfCopiesWithoutCharges": { "type": "integer", "format": "int32", "minimum": 0, "description": "The requested number of copies of the `Transport Document` to be issued by the carrier **NOT** including charges.\n\n**Conditions:** The following table defines the conditions for the `numberOfCopiesWithoutCharges` property:\n| Transport Document Type Code | Is Electronic | Meaning |\n|-------|:-------:|-------|\n|`BOL`|`false`|How many paper copies of the Original BL to be issued by the carrier without charges|\n|`BOL`|`true`|Not applicable, there are no copies|\n|`SWB`|`false`|Indicates that charges should NOT be included in the `SWB` (pdf or other formats)|\n|`SWB`|`true`|Indicates that charges NOT should be included in the electronic `SWB`|\n" }, "numberOfOriginalsWithCharges": { "type": "integer", "format": "int32", "minimum": 0, "description": "Number of originals of the Bill of Lading that has been requested by the customer with charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n" }, "numberOfOriginalsWithoutCharges": { "type": "integer", "format": "int32", "minimum": 0, "description": "Number of originals of the Bill of Lading that has been requested by the customer without charges.\n \n**Condition:** Only applicable if `transportDocumentType` = `BOL` (Bill of Lading). If `isElectronic = 'True'`, accepted value is `1` (one) or `0` (zero)\n" }, "displayedNameForPlaceOfReceipt": { "description": "The name to be used in order to specify how the `Place of Receipt` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 35, "description": "A line of the address to be displayed on the transport document.\n" } }, "displayedNameForPortOfLoad": { "description": "The name to be used in order to specify how the `Port of Load` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 35, "description": "A line of the address to be displayed on the transport document.\n" } }, "displayedNameForPortOfDischarge": { "description": "The name to be used in order to specify how the `Port of Discharge` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 35, "description": "A line of the address to be displayed on the transport document.\n" } }, "displayedNameForPlaceOfDelivery": { "description": "The name to be used in order to specify how the `Place of Delivery` should be displayed on the `Transport Document` to match the name and/or address provided on the `Letter of Credit`.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "type": "array", "maxItems": 5, "items": { "type": "string", "maxLength": 35, "description": "A line of the address to be displayed on the transport document.\n" } }, "placeOfIssue": { "$ref": "#/$defs/PlaceOfIssue" }, "invoicePayableAt": { "$ref": "#/$defs/InvoicePayableAtShippingInstructions" }, "partyContactDetails": { "type": "array", "minItems": 1, "description": "The contact details of the person(s) to contact in relation to the **Transport Document** (changes, notifications etc.) \n", "items": { "$ref": "#/$defs/PartyContactDetail" } }, "isCarriersAgentAtDestinationRequired": { "type": "boolean", "description": "Indicates whether the Carrier's agent at destination name, address and contact details should be included in the `Transport Document`.\n" }, "documentParties": { "$ref": "#/$defs/DocumentPartiesShippingInstructions" }, "isCargoDeliveredInICS2Zone": { "type": "boolean", "description": "Indicates whether cargo is delivered to EU, Norway, Switzerland or Northern Ireland.\n" }, "consignmentItems": { "type": "array", "minItems": 1, "description": "A list of `ConsignmentItems`\n", "items": { "$ref": "#/$defs/ConsignmentItemShipper" } }, "utilizedTransportEquipments": { "type": "array", "minItems": 1, "description": "A list of `Utilized Transport Equipments` describing the equipment being used.\n", "items": { "$ref": "#/$defs/UtilizedTransportEquipmentShipper" } }, "exportLicense": { "$ref": "#/$defs/ExportLicenseShipper" }, "importLicense": { "$ref": "#/$defs/ImportLicenseShipper" }, "references": { "type": "array", "description": "A list of `References`\n", "items": { "$ref": "#/$defs/Reference" } }, "customsReferences": { "type": "array", "description": "A list of `Customs references`\n", "items": { "$ref": "#/$defs/CustomsReference" } }, "advanceManifestFilings": { "type": "array", "description": "A list of `Advance Manifest Filings` specified by the Shipper to indicate whom is to do the Filing\n", "items": { "$ref": "#/$defs/AdvanceManifestFiling" } }, "isHouseBillOfLadingsIssued": { "type": "boolean", "description": "Indicates whether one or more `House Bill of Lading(s)` have been issued.\n\n**Condition:** Mandatory if `manifestTypeCode` is `ENS`\n" }, "houseBillOfLadings": { "type": "array", "description": "A list of `House Bill of Ladings` specified by the Shipper.\n", "items": { "$ref": "#/$defs/HouseBillOfLading" } }, "requestedCarrierCertificates": { "type": "array", "description": "Certificate(s) requested by the Shipper for the Carrier to include as part of the shipment documentation pack\n", "items": { "type": "string", "maxLength": 100, "description": "Name of the certificate. Detailed information about carrier certificates can be found [here](https://dcsa.org/wp-content/uploads/2023/12/28-12-2023_Carrier-Certificates-shipment-voyage-particulars-and-vessel-particulars.pdf). Possible values are:\n- `SHIPMENT_VOYAGE_PARTICULARS_1` (Shipment-Voyage Particulars 1)\n- `SHIPMENT_VOYAGE_PARTICULARS_2` (Shipment-Voyage Particulars 2)\n- `SHIPMENT_VOYAGE_PARTICULARS_3` (Shipment-Voyage Particulars 3)\n- `SHIPMENT_VOYAGE_PARTICULARS_4` (Shipment-Voyage Particulars 4)\n- `SHIPMENT_VOYAGE_PARTICULARS_5` (Shipment-Voyage Particulars 5)\n- `SHIPMENT_VOYAGE_PARTICULARS_6` (Shipment-Voyage Particulars 6)\n- `SHIPMENT_VOYAGE_PARTICULARS_7` (Shipment-Voyage Particulars 7)\n- `VESSEL_PARTICULARS_1` (Vessel Particulars 1)\n- `VESSEL_PARTICULARS_2` (Vessel Particulars 2)\n- `VESSEL_PARTICULARS_3` (Vessel Particulars 3)\n- `VESSEL_PARTICULARS_4` (Vessel Particulars 4)\n- `VESSEL_PARTICULARS_5` (Vessel Particulars 5)\n- `VESSEL_PARTICULARS_6` (Vessel Particulars 6)\n- `VESSEL_PARTICULARS_7` (Vessel Particulars 7)\n- `VESSEL_PARTICULARS_8` (Vessel Particulars 8)\n- `VESSEL_PARTICULARS_9` (Vessel Particulars 9)\n- `VESSEL_PARTICULARS_10` (Vessel Particulars 10)\n- `VESSEL_PARTICULARS_11` (Vessel Particulars 11)\n- `VESSEL_PARTICULARS_12` (Vessel Particulars 12)\n- `VESSEL_PARTICULARS_13` (Vessel Particulars 13)\n- `VESSEL_PARTICULARS_14` (Vessel Particulars 14)\n- `VESSEL_PARTICULARS_15` (Vessel Particulars 15)\n- `VESSEL_PARTICULARS_16` (Vessel Particulars 16)\n- `VESSEL_PARTICULARS_17` (Vessel Particulars 17)\n- `VESSEL_PARTICULARS_18` (Vessel Particulars 18)\n" } }, "requestedCarrierClauses": { "type": "array", "description": "Clauses requested by the Shipper for the Carrier to include in the `Transport Document` `Carrier clauses`\n", "items": { "type": "string", "maxLength": 100, "description": "A clause to request from the carrier. Detailed information about the carrier clauses can be found [here](https://dcsa-website.cdn.prismic.io/dcsa-website/ZvaCMbVsGrYSwERk_202409StandardisedClausesBL-Final.pdf). Possible values are:\n- `CARGO_CARGOSPECIFICS` (Cargo/Cargo specifics)\n- `VESSELCONVEYANCE_COUNTRYSPECIFIC` (Vessel conveyance/Country Specific)\n- `CARGO_RETURNOFEMPTYCONTAINER` (Cargo/Return of Empty Container)\n- `CARGO_CARGOVALUE` (Cargo/Cargo value)\n- `CARGO_REEFERTEMPERATURE` (Cargo/Reefer temperature)\n- `CARGO_CONFLICTINGTEMPERATURES_MIXEDLOADS` (Cargo/Conflicting temperatures/Mixed loads)\n- `SHIPPERSLOADSTOWWEIGHTANDCOUNT` (Shipper's Load, Stow, Weight and Count)\n- `INTRANSITCLAUSE` (In transit clause)\n" } } }, "required": [ "shippingInstructionsReference", "transportDocumentTypeCode", "isShippedOnBoardType", "isElectronic", "isToOrder", "freightPaymentTermCode", "partyContactDetails", "documentParties", "isCargoDeliveredInICS2Zone", "consignmentItems", "utilizedTransportEquipments" ], "$defs": { "Address": { "type": "object", "title": "Address", "description": "An object for storing address related information\n", "properties": { "street": { "type": "string", "maxLength": 70, "description": "The name of the street." }, "streetNumber": { "type": "string", "maxLength": 50, "description": "The number of the street." }, "floor": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 50, "description": "The floor of the street number.\n" }, "postCode": { "type": "string", "maxLength": 10, "description": "The post code of the address." }, "POBox": { "type": "string", "maxLength": 20, "description": "A numbered box at a post office where a person or business can have mail or parcels delivered." }, "city": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "The name of the city.\n" }, "stateRegion": { "type": "string", "maxLength": 65, "description": "The name of the state/region." }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" } }, "required": [ "street", "city", "countryCode" ] }, "AdvanceManifestFiling": { "type": "object", "title": "Advance Manifest Filing", "description": "An Advance Manifest Filing defined by a Manifest type code in combination with a country code.\n\nA small list of **potential** examples:\n\n| manifestTypeCode | countryCode | Description |\n|-----------------------|:-------------:|-------------|\n|ACI|EG|Advance Cargo Information in Egypt|\n|ACE|US|Automated Commercial Environment in the United States|\n|AFR|JP|Cargo Summary Notification (CSN)|\n|ENS|NL|Entry Summary Declaration|\n", "properties": { "manifestTypeCode": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 50, "description": "The Manifest type code as defined by the provider.\n" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" }, "advanceManifestFilingsHouseBLPerformedBy": { "type": "string", "description": "Indicates whether the shipper (`SELF`) will perform the advance manifest filing(s) for the House BL directly or if the carrier (`CARRIER`) should file them on their behalf. Allowed values are:\n\n- `SELF` (filing done by the House filer)\n- `CARRIER` (the carrier does the filing)\n\nIn case of self-filing (`SELF`), the shipper can provide their `selfFilerCode` for each manifest.\n\n**Condition:** The `selfFilerCode` must be provided when `manifestTypeCode` is one of `ACE` (US) or `ACI` (CA) and the `advanceManifestFilingsHouseBLPerformedBy` is set to `SELF`.\n", "enum": [ "SELF", "CARRIER" ] }, "selfFilerCode": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 100, "description": "Code identifying the party who will submit the advance manifest filing(s) for the House BL.\n\n**Mandatory** if `manifestTypeCode` is one of `ACE` (US) or `ACI` (CA) and `advanceManifestFilingsHouseBLPerformedBy` is set to `SELF`.\n" }, "identificationNumber": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 17, "description": "An identification number of the house filer responsible for submitting the `Advance Manifest Filing`.\n\n**Condition:** Mandatory if `manifestTypeCode` is `ENS` and `advanceManifestFilingsHouseBLPerformedBy` is `SELF`.\n" } }, "required": [ "manifestTypeCode", "advanceManifestFilingsHouseBLPerformedBy" ] }, "Buyer": { "type": "object", "title": "Buyer", "description": "The buyer is the last known entity to whom the goods are sold or agreed to be sold. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided.\n\n**Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` and `manifesttypecode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'` and `isHouseBillofLadingsIssued=false`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailWithPattern" } } }, "required": [ "partyName", "typeOfPerson" ] }, "BuyerHBL": { "type": "object", "title": "Buyer (House B/L)", "description": "The buyer is the last known entity to whom the goods are sold or agreed to be sold. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided.\n\n**Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` (on House B/L level) and `manifesttypecode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailHBL" } } }, "required": [ "partyName", "typeOfPerson" ] }, "CargoGrossVolume": { "type": "object", "title": "Cargo Gross Volume", "description": "Calculated by multiplying the width, height, and length of the packed cargo.\n", "properties": { "value": { "type": "number", "format": "float", "minimum": 0, "exclusiveMinimum": true, "description": "Calculated by multiplying the width, height, and length of the packed cargo. A maximum of 4 decimals should be provided.\n" }, "unit": { "type": "string", "description": "The unit of measure which can be expressed in imperial or metric terms:\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", "enum": [ "MTQ", "FTQ" ] } }, "required": [ "value", "unit" ] }, "CargoGrossWeight": { "type": "object", "title": "Cargo Gross Weight", "description": "The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container.\n", "properties": { "value": { "type": "number", "format": "float", "minimum": 0, "exclusiveMinimum": true, "description": "The weight of the cargo item including packaging being carried in the container. Excludes the tare weight of the container. A maximum of 3 decimals should be provided.\n" }, "unit": { "type": "string", "description": "The unit of measure which can be expressed in imperial or metric terms:\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", "enum": [ "KGM", "LBR" ] } }, "required": [ "value", "unit" ] }, "CargoItemHBL": { "type": "object", "title": "Cargo Item (House B/L)", "description": "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", "properties": { "equipmentReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 11, "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit).\n\nIf a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n" }, "cargoGrossWeight": { "$ref": "#/$defs/CargoGrossWeight" }, "outerPackaging": { "$ref": "#/$defs/OuterPackagingHBL" } }, "required": [ "equipmentReference", "cargoGrossWeight", "outerPackaging" ] }, "CargoItemShipper": { "type": "object", "title": "Cargo Item (Shipper)", "description": "A `cargoItem` is the smallest unit used by stuffing. A `cargoItem` cannot be split across containers.\n", "properties": { "equipmentReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 11, "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit).\n\nIf a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n" }, "cargoGrossWeight": { "$ref": "#/$defs/CargoGrossWeight" }, "cargoGrossVolume": { "$ref": "#/$defs/CargoGrossVolume" }, "cargoNetWeight": { "$ref": "#/$defs/CargoNetWeight" }, "cargoNetVolume": { "$ref": "#/$defs/CargoNetVolume" }, "exportLicense": { "$ref": "#/$defs/ExportLicenseShipper" }, "importLicense": { "$ref": "#/$defs/ImportLicenseShipper" }, "outerPackaging": { "$ref": "#/$defs/OuterPackagingShipper" }, "nationalCommodityCodes": { "type": "array", "description": "A list of `National Commodity Codes` that apply to this `cargoItem`\n", "items": { "$ref": "#/$defs/NationalCommodityCode" } }, "houseBillOfLadingReference": { "type": "string", "maxLength": 20, "pattern": "^\\S(?:.*\\S)?$", "description": "Link to the House Bill of Lading this cargoItem is connected to.\n" }, "customsReferences": { "type": "array", "description": "A list of `Customs references`\n", "items": { "$ref": "#/$defs/CustomsReference" } } }, "required": [ "equipmentReference", "cargoGrossWeight" ] }, "CargoNetVolume": { "type": "object", "title": "Cargo Net Volume", "description": "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n", "properties": { "value": { "type": "number", "format": "float", "minimum": 0, "exclusiveMinimum": true, "description": "Calculated by multiplying the width, height, and length of the cargo, excluding packaging.\n" }, "unit": { "type": "string", "description": "The unit of measure which can be expressed in imperial or metric terms:\n- `FTQ` (Cubic foot)\n- `MTQ` (Cubic meter)\n", "enum": [ "MTQ", "FTQ" ] } }, "required": [ "value", "unit" ] }, "CargoNetWeight": { "type": "object", "title": "Cargo Net Weight", "description": "The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container.\n", "properties": { "value": { "type": "number", "format": "float", "minimum": 0, "exclusiveMinimum": true, "description": "The weight of the cargo item excluding packaging being carried in the container. Excludes the tare weight of the container. A maximum of 3 decimals should be provided.\n" }, "unit": { "type": "string", "description": "The unit of measure which can be expressed in imperial or metric terms:\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", "enum": [ "KGM", "LBR" ] } }, "required": [ "value", "unit" ] }, "ConsigneeHBL": { "type": "object", "title": "Consignee (House B/L)", "description": "The ultimate recipient of the cargo. It must be different from the freight forwarder, (de)consolidator, postal operator, or customs agent.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailHBL" } } }, "required": [ "partyName", "typeOfPerson" ] }, "ConsigneeShipper": { "type": "object", "title": "Consignee (Shipper provided)", "description": "The party to which goods are consigned in the `Master Bill of Lading`.\n\n**Condition:** Mandatory for non-negotiable BL (`isToOrder=false`)\n\n**Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/PartyAddress" }, "displayedAddress": { "type": "array", "maxItems": 6, "description": "The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "type": "string", "maxLength": 35, "description": "A single address line\n" } }, "identifyingCodes": { "type": "array", "description": "**Condition:** Either the `address` or a party `identifyingCode` must be provided. \n", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetail" } }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A reference linked to the `Consignee`.\n" }, "purchaseOrderReferences": { "type": "array", "description": "A list of `Purchase Order Reference`s linked to the `Consignee`.\n", "items": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A purchase order reference linked to the `Consignee`.\n" } } }, "required": [ "partyName" ] }, "ConsignmentItemHBL": { "type": "object", "title": "Consignment Item (House B/L)", "description": "Defines a list of `CargoItems` belonging together in the same consignment. A `ConsignmentItem` can be split across multiple containers (`UtilizedTransportEquipment`) by referencing multiple `CargoItems`\n", "properties": { "descriptionOfGoods": { "type": "string", "maxLength": 512, "pattern": "^\\S(?:.*\\S)?$", "description": "A plain language description that is precise enough for Customs services to be able to identify the goods. General terms (i.e. 'consolidated', 'general cargo' 'parts' or 'freight of all kinds') or not sufficiently precise description cannot be accepted. Where the declarant provides the CUS code for chemical substances and preparations, Member States may waive the requirement of providing a precise description of the goods.\n" }, "nationalCommodityCode": { "$ref": "#/$defs/NationalCommodityCode" }, "cargoItems": { "type": "array", "minItems": 1, "description": "A list of all `cargoItems`\n", "items": { "$ref": "#/$defs/CargoItemHBL" } }, "customsReferences": { "type": "array", "description": "A list of `Customs references`\n", "items": { "$ref": "#/$defs/CustomsReference" } } }, "required": [ "descriptionOfGoods", "cargoItems", "nationalCommodityCode" ] }, "ConsignmentItemShipper": { "type": "object", "title": "Consignment Item (Shipper)", "description": "Defines a list of `CargoItems` belonging together and the associated `Booking`. A `ConsignmentItem` can be split across multiple containers (`UtilizedTransportEquipment`) by referencing multiple `CargoItems`\n", "properties": { "carrierBookingReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "The associated booking number provided by the carrier for this `Consignment Item`.\n" }, "commoditySubReference": { "type": "string", "maxLength": 100, "pattern": "^\\S(?:.*\\S)?$", "description": "A unique reference to the commodity object assigned by the carrier in the booking confirmation. The reference must be provided by the shipper as part of the `Shipping Instructions` for the carrier to link this consignment item to the commodity. A commodity reference is only unique in the context of a booking.\n" }, "descriptionOfGoods": { "type": "array", "description": "A plain language description that is precise enough for Customs services to be able to identify the goods. General terms (i.e. 'consolidated', 'general cargo' 'parts' or 'freight of all kinds') or not sufficiently precise description cannot be accepted.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "maxItems": 150, "items": { "type": "string", "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "description": "A line describing the cargo" } }, "HSCodes": { "type": "array", "minItems": 1, "description": "A list of `HS Codes` that apply to this `consignmentItem`\n", "items": { "type": "string", "pattern": "^\\d{6,10}$", "minLength": 6, "maxLength": 10, "description": "Used by customs to classify the product being shipped. The type of HS code depends on country and customs requirements. The code must be at least 6 and at most 10 digits.\n\nMore information can be found here: [HS Nomenclature](https://www.wcoomd.org/en/topics/nomenclature/instrument-and-tools).\n" } }, "nationalCommodityCodes": { "type": "array", "description": "A list of `National Commodity Codes` that apply to this `commodity`\n", "items": { "$ref": "#/$defs/NationalCommodityCode" } }, "shippingMarks": { "type": "array", "maxItems": 50, "description": "A list of the `ShippingMarks` applicable to this `consignmentItem`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "type": "string", "maxLength": 35, "description": "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n" } }, "cargoItems": { "type": "array", "minItems": 1, "description": "A list of all `cargoItems`\n", "items": { "$ref": "#/$defs/CargoItemShipper" } }, "exportLicense": { "$ref": "#/$defs/ExportLicenseShipper" }, "importLicense": { "$ref": "#/$defs/ImportLicenseShipper" }, "references": { "type": "array", "description": "A list of `References`\n", "items": { "$ref": "#/$defs/ReferenceConsignmentItem" } }, "customsReferences": { "type": "array", "description": "A list of `Customs references`\n", "items": { "$ref": "#/$defs/CustomsReference" } } }, "required": [ "carrierBookingReference", "descriptionOfGoods", "HSCodes", "cargoItems" ] }, "CustomsReference": { "type": "object", "title": "Customs Reference", "description": "Reference associated with customs and/or excise purposes required by the relevant authorities for the import, export, or transit of the goods.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|UCR|NL|Unique Consignment Reference|\n|CUS|NL|Customs Union and Statistics|\n|ACID|EG|Advance Cargo Information Declaration in Egypt|\n|CERS|CA|Canadian Export Reporting System|\n|ITN|US|Internal Transaction Number in US|\n|PEB|ID|PEB reference number|\n|CSN|IN|Cargo Summary Notification (CSN)|\n", "properties": { "type": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 50, "description": "The reference type code as defined in the relevant customs jurisdiction.\n" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" }, "values": { "type": "array", "minItems": 1, "items": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "The value of the `customsReference`\n" } } }, "required": [ "type", "countryCode", "values" ] }, "DestinationChargesPaymentTerm": { "type": "object", "title": "Destination Charges Payment Term", "description": "An indicator of whether destination charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n", "properties": { "haulageChargesPaymentTermCode": { "type": "string", "description": "An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", "enum": [ "PRE", "COL" ] }, "portChargesPaymentTermCode": { "type": "string", "description": "An indicator of whether the destination port charges are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", "enum": [ "PRE", "COL" ] }, "otherChargesPaymentTermCode": { "type": "string", "enum": [ "PRE", "COL" ], "description": "An indicator of whether destination charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n" } } }, "DocumentPartiesHouseBL": { "type": "object", "title": "Document Parties (House B/L)", "description": "All `Parties` with associated roles for this `House Bill of Lading`.\n\n**Condition:** `Buyer` and `Seller` are mandatory if `isCargoDeliveredInICS2Zone=true` (on House B/L level) **and** `advancedManifestFilingPerformedBy=CARRIER`\n", "properties": { "shipper": { "$ref": "#/$defs/ShipperHBL" }, "consignee": { "$ref": "#/$defs/ConsigneeHBL" }, "notifyParty": { "$ref": "#/$defs/NotifyPartyHBL" }, "seller": { "$ref": "#/$defs/SellerHBL" }, "buyer": { "$ref": "#/$defs/BuyerHBL" }, "other": { "type": "array", "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", "items": { "$ref": "#/$defs/OtherDocumentPartyHBL" } } }, "required": [ "shipper" ] }, "DocumentPartiesShippingInstructions": { "type": "object", "title": "Document Parties (Shipping Instructions)", "description": "All `Parties` with associated roles.\n\n**Condition:** `Buyer` and `Seller` are mandatory if `isCargoDeliveredInICS2Zone=true` **and** `advancedManifestFilingPerformedBy=CARRIER` and `isHouseBillOfLadingsIssued=false`\n", "properties": { "shipper": { "$ref": "#/$defs/Shipper" }, "consignee": { "$ref": "#/$defs/ConsigneeShipper" }, "endorsee": { "$ref": "#/$defs/EndorseeShipper" }, "issueTo": { "$ref": "#/$defs/IssueToParty" }, "seller": { "$ref": "#/$defs/Seller" }, "buyer": { "$ref": "#/$defs/Buyer" }, "notifyParties": { "type": "array", "maxItems": 3, "description": "List of up to 3 `Notify Parties`. The first item in the list is the **First Notify Party** (`N1`), the second item is the **Second Notify Party** (`N2`) and the last item is the **Other Notify Party** (`NI`).\n\n**Condition:** If provided:\n - Mandatory for To Order BLs, `isToOrder=true`\n - The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "$ref": "#/$defs/NotifyParty" } }, "other": { "type": "array", "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.", "items": { "$ref": "#/$defs/OtherDocumentParty" } } }, "required": [ "shipper" ] }, "EndorseeShipper": { "type": "object", "title": "Endorsee (Shipper provided)", "description": "The party to whom the title to the goods is transferred by means of endorsement.\n\n**Condition:** Can only be provided for negotiable BLs (`isToOrder=true`). If a negotiable BL does not have an `Endorsee`, the BL is said to be \"blank endorsed\". Note `Consignee` and `Endorsee` are mutually exclusive.\n\n**Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "address": { "$ref": "#/$defs/PartyAddress" }, "displayedAddress": { "type": "array", "maxItems": 6, "description": "The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "type": "string", "maxLength": 35, "description": "A single address line\n" } }, "identifyingCodes": { "type": "array", "description": "**Condition:** Either the `address` or a party `identifyingCode` must be provided. \n", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetail" } } }, "required": [ "partyName" ] }, "ExportLicenseShipper": { "type": "object", "title": "Export License (Shipper)", "description": "`Export License` requirements\n\n**Condition:** Subject to local customs requirements and commodity.\n", "properties": { "isRequired": { "type": "boolean", "description": "Information provided by the shipper to indicate whether an `Export License` or permit is required for this shipment/commodity/destination.\n \n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n" }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "Reference number assigned to an `Export License` or permit, which authorizes a business or individual to export specific goods to specific countries under defined conditions. It is a permit that is required when shipping certain restricted or controlled goods, such as military equipment, high-tech items, chemicals, or items subject to international regulations. The `Export License` must be valid at time of departure.\n" }, "issueDate": { "type": "string", "format": "date", "description": "Issue date of the `Export License`.\n" }, "expiryDate": { "type": "string", "format": "date", "description": "Expiry date of the `Export License`.\n" } } }, "HouseBillOfLading": { "type": "object", "title": "House Bill of Lading", "description": "A legal contract between the Ocean Transport Intermediary (OTI), such as a Non-Vessel Operating Common Carrier (NVOCC) or a freight forwarder, and the shipper that acknowledges the receipt of goods and outlines the terms of shipment.\n", "properties": { "houseBillOfLadingReference": { "type": "string", "maxLength": 20, "pattern": "^\\S(?:.*\\S)?$", "description": "A unique number allocated by the Ocean Transport Intermediary (OTI) to the `House Bill of Lading`.\n" }, "isToOrder": { "type": "boolean", "description": "Indicates whether the `House Bill of Lading` (HBL) is issued `to order` or not. If `true`, `Notify party` at `HBL` level is mandatory\n" }, "placeOfAcceptance": { "$ref": "#/$defs/PlaceOfAcceptance" }, "placeOfFinalDelivery": { "$ref": "#/$defs/PlaceOfFinalDelivery" }, "methodOfPayment": { "type": "string", "maxLength": 1, "description": "Method used for the payment of freight charges. It can be one of the following values: \n- `A` (Payment in cash)\n- `B` (Payment by credit card)\n- `C` (Payment by cheque)\n- `D` (Other (e.g. direct debit to cash account))\n- `H` (Electronic funds transfer)\n- `Y` (Account holder with carrier)\n- `Z` (Not pre-paid)\n" }, "documentParties": { "$ref": "#/$defs/DocumentPartiesHouseBL" }, "isCargoDeliveredInICS2Zone": { "type": "boolean", "description": "Indicates whether cargo is delivered to EU, Norway, Switzerland or Northern Ireland.\n" }, "routingOfConsignmentCountries": { "type": "array", "minItems": 1, "description": "Identification in a chronological order of the countries through which the goods are routed between the country of original departure and final destination as stipulated in the lowest House Bill of Lading.\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n\n**Condition:** If provided - the first country in the list must be the country of `Place of Acceptance`; the last country in the list must be the country of `Place of Final Delivery`.\n", "items": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" } }, "consignmentItems": { "type": "array", "minItems": 1, "description": "A list of `ConsignmentItems` for this `House Bill of Lading`\n", "items": { "$ref": "#/$defs/ConsignmentItemHBL" } }, "utilizedTransportEquipments": { "type": "array", "minItems": 1, "description": "A list of `Utilized Transport Equipment` for this `House Bill of Lading`\n", "items": { "$ref": "#/$defs/UtilizedTransportEquipmentHBL" } } }, "required": [ "houseBillOfLadingReference", "isToOrder", "methodOfPayment", "documentParties", "isCargoDeliveredInICS2Zone", "routingOfConsignmentCountries", "consignmentItems", "utilizedTransportEquipments" ] }, "IdentifyingCode": { "type": "object", "title": "Identifying Code", "properties": { "codeListProvider": { "type": "string", "maxLength": 100, "description": "A list of codes identifying a party. Possible values are:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (Enigio trace:original)\n- `BRIT` (BRITC eBL)\n- `GSBN` (Global Shipping Business Network)\n- `WISE` (WiseTech)\n- `GLEIF` (Global Legal Entity Identifier Foundation)\n- `W3C` (World Wide Web Consortium)\n- `DNB` (Dun and Bradstreet)\n- `FMC` (Federal Maritime Commission)\n- `DCSA` (Digital Container Shipping Association)\n- `ZZZ` (Mutually defined)\n" }, "partyCode": { "type": "string", "maxLength": 150, "description": "Code to identify the party as provided by the code list provider\n" }, "codeListName": { "type": "string", "maxLength": 100, "description": "The name of the code list, code generation mechanism or code authority for the `partyCode`. Example values could be:\n- `DID` (Decentralized Identifier) for `codeListProvider` `W3C`\n- `LEI` (Legal Entity Identifier) for `codeListProvider` `GLEIF`\n- `DUNS` (Data Universal Numbering System) for `codeListProvider` `DNB`\n" } }, "required": [ "codeListProvider", "partyCode" ] }, "ImportLicenseShipper": { "type": "object", "title": "Import License (Shipper)", "description": "`Import License` requirements\n\n**Condition:** Subject to local customs requirements and commodity.\n", "properties": { "isRequired": { "type": "boolean", "description": "Information provided by the shipper to indicate whether an `Import License` or permit is required for this shipment/commodity/destination.\n \n**Note:** If this property is omitted, it may be interpreted differently by different API providers and by the same API provider in different contexts.\n" }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "Reference number assigned to an `Import License` or permit, issued by countries exercising import controls that authorizes the importation of the articles stated in the license. The `Import License` must be valid at time of arrival.\n" }, "issueDate": { "type": "string", "format": "date", "description": "Issue date of the `Import License`.\n" }, "expiryDate": { "type": "string", "format": "date", "description": "Expiry date of the `Import License`.\n" } } }, "InvoicePayableAtShippingInstructions": { "type": "object", "title": "Invoice Payable At (Shipping Instructions)", "description": "Location where payment of ocean freight and charges for the main transport will take place by the customer.\n\nThe location must be provided as a `UN Location Code`\n", "properties": { "UNLocationCode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", "minLength": 5, "maxLength": 5, "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)" } }, "required": [ "UNLocationCode" ] }, "IssueToParty": { "type": "object", "title": "Issue To Party", "description": "The party to whom the `Bill of Lading` must be issued.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "sendToPlatform": { "type": "string", "pattern": "^\\S+$", "maxLength": 4, "description": "The eBL platform of the transaction party. \nThe value **MUST** be one of:\n- `WAVE` (Wave)\n- `CARX` (CargoX)\n- `ESSD` (EssDOCS)\n- `IDT` (ICE Digital Trade)\n- `BOLE` (Bolero)\n- `EDOX` (EdoxOnline)\n- `IQAX` (IQAX)\n- `SECR` (Secro)\n- `TRGO` (TradeGO)\n- `ETEU` (eTEU)\n- `TRAC` (Enigio trace:original)\n- `BRIT` (BRITC eBL)\n\n**Condition:** Only applicable when `isElectronic=true` and `transportDocumentTypeCode=BOL`. The property **MUST** be absent for paper B/Ls (`isElectronic=false`)\n" }, "identifyingCodes": { "type": "array", "minItems": 1, "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } } }, "required": [ "partyName", "identifyingCodes" ] }, "NationalCommodityCode": { "type": "object", "title": "National Commodity Code", "description": "The national commodity classification code linked to a country with a value.\n\nAn example could look like this:\n\n| Type | Country | Value |\n|-------|:-------:|-------------|\n|NCM|BR|['1515', '2106', '2507', '2512']|\n", "properties": { "type": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 10, "description": "The national commodity classification code, which can be one of the following values defined by DCSA:\n- `NCM` (Nomenclatura Comum do Mercosul)\n- `HTS` (Harmonized Tariff Schedule)\n- `SCHEDULE_B` ( Schedule B)\n- `TARIC` (Integrated Tariff of the European Communities)\n- `CN` (Combined Nomenclature)\n- `CUS` (Customs Union and Statistics)\n" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" }, "values": { "type": "array", "minItems": 1, "description": "A list of `national commodity codes` values.\n", "items": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 10, "description": "The value of the `National Commodity Code`\n" } } }, "required": [ "type", "values" ] }, "NotifyParty": { "type": "object", "title": "Notify Party", "description": "The person to be notified when a shipment arrives at its destination.\n\n**Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/PartyAddress" }, "displayedAddress": { "type": "array", "maxItems": 6, "description": "The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "type": "string", "maxLength": 35, "description": "A single address line\n" } }, "identifyingCodes": { "type": "array", "description": "**Condition:** Either the `address` or a party `identifyingCode` must be provided. \n", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetail" } }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A reference linked to the `NotifyParty`.\n" } }, "required": [ "partyName" ] }, "NotifyPartyHBL": { "type": "object", "title": "Notify Party (House B/L)", "description": "The person to be notified when a shipment arrives at its destination.\n\n**Condition:** Mandatory for To Order HBLs (HouseBL `isToOrder=true`)\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailHBL" } } }, "required": [ "partyName", "partyContactDetails", "typeOfPerson" ] }, "OriginChargesPaymentTerm": { "type": "object", "title": "Origin Charges Payment Term", "description": "An indicator of whether origin charges are prepaid (`PRE`) or collect (`COL`). When prepaid, the charges are the responsibility of the shipper or the Invoice payer on behalf of the shipper (if provided). When collect, the charges are the responsibility of the consignee or the Invoice payer on behalf of the consignee (if provided).\n", "properties": { "haulageChargesPaymentTermCode": { "type": "string", "description": "An indicator of whether the costs for inland transportation to the port, when applicable, are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", "enum": [ "PRE", "COL" ] }, "portChargesPaymentTermCode": { "type": "string", "description": "An indicator of whether the origin port charges are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n", "enum": [ "PRE", "COL" ] }, "otherChargesPaymentTermCode": { "type": "string", "enum": [ "PRE", "COL" ], "description": "An indicator of whether origin charges (excluding port and haulage) are prepaid (`PRE`) or collect (`COL`).\n\n- `PRE` (Prepaid)\n- `COL` (Collect)\n" } } }, "OtherDocumentParty": { "type": "object", "title": "Other Document Party", "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n", "properties": { "party": { "$ref": "#/$defs/Party" }, "partyFunction": { "type": "string", "maxLength": 3, "description": "Specifies the role of the party in a given context. Possible values are:\n\n- `SCO` (Service Contract Owner)\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `COW` (Invoice payer on behalf of the consignor (shipper))\n- `COX` (Invoice payer on behalf of the consignee)\n- `CS` (Consolidator)\n- `MF` (Manufacturer)\n- `WH` (Warehouse Keeper)\n" } }, "required": [ "party", "partyFunction" ] }, "OtherDocumentPartyHBL": { "type": "object", "title": "Other Document Party (House B/L)", "description": "A list of document parties that can be optionally provided in the `Shipping Instructions` and `Transport Document`.\n", "properties": { "party": { "$ref": "#/$defs/PartyHBL" }, "partyFunction": { "type": "string", "maxLength": 3, "description": "Specifies the role of the party in a given context. Possible values are:\n\n- `DDR` (Consignor's freight forwarder)\n- `DDS` (Consignee's freight forwarder)\n- `CS` (Consolidator)\n- `MF` (Manufacturer)\n- `WH` (Warehouse Keeper)\n" } }, "required": [ "party", "partyFunction" ] }, "OuterPackagingHBL": { "type": "object", "title": "Outer Packaging (House B/L)", "description": "Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport.\n", "properties": { "packageCode": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2, "description": "A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations)\n" }, "numberOfPackages": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 99999999, "description": "Specifies the number of outer packagings/overpacks associated with this `Cargo Item`.\n\n**Condition:** Mandatory if `packageCode` is **NOT** one of the following values:\n\n- `VY` (Bulk, solid, fine particles (\"powders\"))\n- `VS` (Bulk, scrap metal)\n- `VR` (Bulk, solid, granular particles (\"grains\"))\n- `VQ` (Bulk, liquefied gas (at abnormal temperature/pressure))\n- `VO` (Bulk, solid, large particles (\"nodules\"))\n- `VL` (Bulk, liquid)\n- `NG` (Unpacked or unpackaged, multiple units)\n- `NF` (Unpacked or unpackaged, single unit)\n- `NE` (Unpacked or unpackaged)\n- `VG` (Bulk, gas (at 1031 mbar and 15°C))\n" }, "shippingMarks": { "type": "string", "maxLength": 512, "description": "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n" }, "UNNumber": { "type": "string", "pattern": "^\\d{4}$", "minLength": 4, "maxLength": 4, "description": "United Nations Dangerous Goods Identifier (UNDG) assigned by the UN Sub-Committee of Experts on the Transport of Dangerous Goods and shown in the IMO IMDG.\n" } }, "required": [ "packageCode" ] }, "OuterPackagingShipper": { "type": "object", "title": "Outer Packaging (Shipper)", "description": "Object for outer packaging/overpack specification. Examples of overpacks are a number of packages stacked on to a pallet and secured by strapping or placed in a protective outer packaging such as a box or crate to form one unit for the convenience of handling and stowage during transport.\n\n**Condition:** Mandatory for non-dangerous goods cargo.\n", "properties": { "packageCode": { "type": "string", "pattern": "^[A-Z0-9]{2}$", "minLength": 2, "maxLength": 2, "description": "A code identifying the outer packaging/overpack. `PackageCode` must follow the codes specified in [Recommendation N°21](https://unece.org/trade/uncefact/cl-recommendations)\n\n**Condition:** only applicable to dangerous goods if the `IMO packaging code` is not available.\n" }, "numberOfPackages": { "type": "integer", "format": "int32", "minimum": 1, "maximum": 99999999, "description": "Specifies the number of outer packagings/overpacks associated with this `Cargo Item`.\n" }, "description": { "type": "string", "maxLength": 100, "description": "Description of the outer packaging/overpack.\n" }, "woodDeclaration": { "type": "string", "maxLength": 30, "description": "Property to clearly indicate if the products, packaging and any other items are made of wood. Possible values include:\n- `NOT_APPLICABLE` (if no wood or any other wood product such as packaging and supports are being shipped)\n- `NOT_TREATED_AND_NOT_CERTIFIED` (if the wood or wooden materials have not been treated nor fumigated and do not include a certificate)\n- `PROCESSED` (if the wood or wooden materials are entirely made of processed wood, such as plywood, particle board, sliver plates of wood and wood laminate sheets produced using glue, heat, pressure or a combination of these)\n- `TREATED_AND_CERTIFIED` (if the wood or wooden materials have been treated and/or fumigated and include a certificate)\n" } }, "required": [ "numberOfPackages", "description" ] }, "Party": { "type": "object", "title": "Party", "description": "Refers to a company or a legal entity.\n\n**Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "address": { "$ref": "#/$defs/PartyAddress" }, "identifyingCodes": { "type": "array", "description": "**Condition:** Either the `address` or a party `identifyingCode` must be provided. \n", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetail" } }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A reference linked to the `Party`.\n" } }, "required": [ "partyName" ] }, "PartyAddress": { "type": "object", "title": "Party Address", "description": "Address where the party is located. It is an object of the attributes below.\n", "properties": { "street": { "type": "string", "description": "The name of the street of the party’s address.", "maxLength": 70 }, "streetNumber": { "type": "string", "description": "The number of the street of the party’s address.", "maxLength": 50 }, "floor": { "type": "string", "description": "The floor of the party’s street number.\n", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 50 }, "postCode": { "type": "string", "description": "The post code of the party’s address.", "maxLength": 10 }, "POBox": { "type": "string", "maxLength": 20, "description": "A numbered box at a post office where a person or business can have mail or parcels delivered." }, "city": { "type": "string", "description": "The city name of the party’s address.\n", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35 }, "UNLocationCode": { "type": "string", "description": "The UN Location code specifying where the carrier booking office is located. The pattern used must be\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", "minLength": 5, "maxLength": 5 }, "stateRegion": { "type": "string", "description": "The state/region of the party’s address.", "maxLength": 65 }, "countryCode": { "type": "string", "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2 } }, "required": [ "street", "city", "countryCode" ] }, "PartyContactDetail": { "type": "object", "title": "Party Contact Detail", "description": "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided.\n", "properties": { "name": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "Name of the contact\n" } }, "anyOf": [ { "type": "object", "title": "Phone required", "description": "`Phone` is mandatory to provide\n", "properties": { "phone": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 30, "description": "Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en).\n" } }, "required": [ "phone" ] }, { "type": "object", "title": "Email required", "description": "`Email` is mandatory to provide\n", "properties": { "email": { "type": "string", "pattern": "^.+@\\S+$", "maxLength": 100, "description": "`E-mail` address to be used\n" } }, "required": [ "email" ] } ], "required": [ "name" ] }, "PartyContactDetailHBL": { "type": "object", "title": "Party Contact Detail (House B/L)", "description": "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided.\n", "properties": { "name": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "Name of the contact\n" } }, "anyOf": [ { "type": "object", "title": "Phone required", "description": "`Phone` is mandatory to provide\n", "properties": { "phone": { "type": "string", "pattern": "^\\+(?:[0-9] ?){6,14}[0-9]$", "maxLength": 30, "description": "Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en).\n" } }, "required": [ "phone" ] }, { "type": "object", "title": "Email required", "description": "`Email` is mandatory to provide\n", "properties": { "email": { "type": "string", "pattern": "^.+@\\S+$", "maxLength": 100, "description": "`E-mail` address to be used\n" } }, "required": [ "email" ] } ], "required": [ "name" ] }, "PartyContactDetailWithPattern": { "type": "object", "title": "Party Contact Detail (with phone pattern)", "description": "The contact details of the person to contact. It is mandatory to provide either `phone` and/or `email` along with the `name`, both can be provided.\n", "properties": { "name": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "Name of the contact\n" } }, "anyOf": [ { "type": "object", "title": "Phone required", "description": "`Phone` is mandatory to provide\n", "properties": { "phone": { "type": "string", "pattern": "^\\+(?:[0-9] ?){6,14}[0-9]$", "maxLength": 30, "description": "Phone number for the contact. Phone **MUST** include an international phone number format as defined in the [ITU-T recommendation E.123](https://www.itu.int/rec/T-REC-E.123/en).\n" } }, "required": [ "phone" ] }, { "type": "object", "title": "Email required", "description": "`Email` is mandatory to provide\n", "properties": { "email": { "type": "string", "pattern": "^.+@\\S+$", "maxLength": 100, "description": "`E-mail` address to be used\n" } }, "required": [ "email" ] } ], "required": [ "name" ] }, "PartyHBL": { "type": "object", "title": "Party (House B/L)", "description": "Refers to a company or a legal entity.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailHBL" } }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A reference linked to the `Party`.\n" } }, "required": [ "partyName" ] }, "PlaceOfAcceptance": { "type": "object", "title": "Place of Acceptance", "description": "An object to capture `Place of Acceptance` location specified as: identification of the seaport, freight terminal or other place at which the goods are taken over from the shipper by the Ocean Transport Intermediary (OTI) issuing the `House Bill of Lading`.\n\n**Condition:** Mandatory if different from `Place of Receipt` or `Port of Loading` at the `Master Transport Document` level.\n\n**Condition:** The location can be specified either using `UN Location Code` and/or (`Location Name` together with `Country Code`), all three properties can be specified.\n", "properties": { "locationName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "The name of the location.\n\n**Condition:** Mandatory to provide in case `UN Location Code` is not provided\n" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** Mandatory to provide in case `UN Location Code` is not provided\n" }, "UNLocationCode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", "minLength": 5, "maxLength": 5, "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n" } } }, "PlaceOfFinalDelivery": { "type": "object", "title": "Place of Final Delivery", "description": "An object to capture `Place of Final Delivery` location specified as: Identification of the seaport, freight terminal or other place at which the goods are handed over from the `Ocean Transport Intermediary` (OTI) issuing the `House Bill of Lading` to the `Consignee`.\n\n**Condition:** Mandatory if different from `Place of Delivery` at the `Master Transport Document` level.\n\n**Condition:** The location can be specified either using `UN Location Code` and/or (`Location Name` together with `Country Code`), all three properties can be specified.\n", "properties": { "locationName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "The name of the location.\n\n**Condition:** Mandatory to provide in case `UN Location Code` is not provided\n" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n\n**Condition:** Mandatory to provide in case `UN Location Code` is not provided\n" }, "UNLocationCode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", "minLength": 5, "maxLength": 5, "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)\n" } } }, "PlaceOfIssue": { "type": "object", "title": "Place of Issue", "description": "An object to capture where the original Transport Document (`Bill of Lading`) will be issued.\n\n**Condition:** The location can be specified as one of `UN Location Code` or `CountryCode`, but not both.\n", "properties": { "locationName": { "type": "string", "description": "The name of the location.", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 100 } }, "oneOf": [ { "type": "object", "title": "UN Location Code", "properties": { "UNLocationCode": { "type": "string", "pattern": "^[A-Z]{2}[A-Z2-9]{3}$", "minLength": 5, "maxLength": 5, "description": "The UN Location code specifying where the place is located. The pattern used must be\n\n- 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n- 3 characters to code a location within that country. Letters A-Z and numbers from 2-9 can be used\n\nMore info can be found here: [UN/LOCODE](https://unece.org/trade/cefact/UNLOCODE-Download)" } }, "required": [ "UNLocationCode" ] }, { "type": "object", "title": "Country Code", "properties": { "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" } }, "required": [ "countryCode" ] } ] }, "Reference": { "type": "object", "title": "Reference", "description": "References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems.\n", "properties": { "type": { "type": "string", "maxLength": 3, "description": "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n" }, "value": { "type": "string", "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "description": "The value of the reference. \n" } }, "required": [ "type", "value" ] }, "ReferenceConsignmentItem": { "type": "object", "title": "Reference (Consignment Item)", "description": "References provided by the shipper or freight forwarder at the time of `Booking` or at the time of providing `Shipping Instructions`. Carriers share it back when providing `Track & Trace` event updates, some are also printed on the B/L. Customers can use these references to track shipments in their internal systems.\n", "properties": { "type": { "type": "string", "maxLength": 3, "description": "The reference type codes defined by DCSA. Possible values are:\n- `CR` (Customer’s Reference)\n- `AKG` (Vehicle Identification Number)\n- `SPO` (Shipper's Purchase Order)\n- `CPO` (Consignee's Purchase Order)\n" }, "values": { "type": "array", "minItems": 1, "description": "List of `referenceValues` for a given `referenceType`.\n", "items": { "type": "string", "maxLength": 35, "pattern": "^\\S(?:.*\\S)?$", "description": "The value of the reference. \n" } } }, "required": [ "type", "values" ] }, "RequiredEquipment": { "type": "object", "title": "Equipment (Required Properties)", "description": "Used for storing cargo in/on during transport. The equipment size/type is defined by the ISO 6346 code. The most common equipment size/type is 20'/40'/45' DRY Freight Container, but several different versions exist.\n", "properties": { "equipmentReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 11, "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit).\n\nIf a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n" }, "ISOEquipmentCode": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 4, "description": "Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard.\n" }, "tareWeight": { "$ref": "#/$defs/TareWeight" } }, "required": [ "equipmentReference", "ISOEquipmentCode", "tareWeight" ] }, "Seal": { "type": "object", "title": "Seal", "description": "Addresses the seal-related information associated with the shipment equipment. A seal is put on a shipment equipment once it is loaded. This `Seal` is meant to stay on until the shipment equipment reaches its final destination.\n", "properties": { "number": { "type": "string", "maxLength": 15, "description": "Identifies a seal affixed to the container." }, "source": { "type": "string", "description": "The source of the seal, namely who has affixed the seal.\n- `CAR` (Carrier)\n- `SHI` (Shipper)\n- `VET` (Veterinary)\n- `CUS` (Customs)\n\n**Condition:** Seal source may be required depending on the type of commodity being shipped.\n", "enum": [ "CAR", "SHI", "VET", "CUS" ] } }, "required": [ "number" ] }, "Seller": { "type": "object", "title": "Seller", "description": "The seller is the last known entity by whom the goods are sold or agreed to be sold to the buyer. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided.\n\n**Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` and `manifesttypecode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'` and `isHouseBillofLadingsIssued=false`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailWithPattern" } } }, "required": [ "partyName", "typeOfPerson" ] }, "SellerHBL": { "type": "object", "title": "Seller (House B/L)", "description": "The seller is the last known entity by whom the goods are sold or agreed to be sold to the buyer. If the goods are to be imported otherwise than in pursuance of a purchase, the details of the owner of the goods shall be provided.\n\n**Condition:** Buyer and Seller are mandatory if `isCargoDeliveredInICS2Zone=true` (on House B/L level) and `manifesttypecode='ENS'` and `advancedManifestFilingPerformedBy='CARRIER'`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailHBL" } } }, "required": [ "partyName", "typeOfPerson" ] }, "Shipper": { "type": "object", "title": "Shipper", "description": "The party by whom or in whose name or on whose behalf a contract of carriage of goods by sea has been concluded with a carrier, or the party by whom or in whose name, or on whose behalf, the goods are actually delivered to the carrier in relation to the contract of carriage by sea.\n\n**Condition:** Either the `address` or a party `identifyingCode` must be provided in the `Shipping Instructions`. If a `displayedAddress` is provided, it must be included in the `Transport Document` instead of the `address`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/PartyAddress" }, "displayedAddress": { "type": "array", "maxItems": 6, "description": "The address of the party to be displayed on the `Transport Document`. The displayed address may be used to match the address provided in the `Letter of Credit`.\n\n**Conditions:** If provided:\n - the displayed address must be included in the `Transport Document`.\n - for physical BL (`isElectronic=false`), it is only allowed to provide max 2 lines of 35 characters\n - for electronic BL (`isElectronic=true`), the limit is 6 lines of 35 characters\n - the order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "type": "string", "maxLength": 35, "description": "A single address line\n" } }, "identifyingCodes": { "type": "array", "description": "**Condition:** Either the `address` or a party `identifyingCode` must be provided. \n", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetail" } }, "reference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A reference linked to the `Shipper`.\n" }, "purchaseOrderReferences": { "type": "array", "description": "A list of `Purchase Order Reference`s linked to the `Shipper`.\n", "items": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "A purchase order reference linked to the `Shipper`.\n" } } }, "required": [ "partyName" ] }, "ShipperHBL": { "type": "object", "title": "Shipper (House B/L)", "description": "The `Shipper` on the `House Bill of Lading`.\n", "properties": { "partyName": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 70, "description": "Name of the party.\n" }, "typeOfPerson": { "type": "string", "maxLength": 50, "pattern": "^\\S(?:.*\\S)?$", "description": "Can be one of the following values as per the Union Customs Code art. 5(4):\n- `NATURAL_PERSON` (A person that is an individual living human being)\n- `LEGAL_PERSON` (person (including a human being and public or private organizations) that can perform legal actions, such as own a property, sue and be sued)\n- `ASSOCIATION_OF_PERSONS` (Not a legal person, but recognised under Union or National law as having the capacity to perform legal acts)\n" }, "address": { "$ref": "#/$defs/Address" }, "identifyingCodes": { "type": "array", "items": { "$ref": "#/$defs/IdentifyingCode" } }, "taxLegalReferences": { "description": "A list of `Tax References` for a `Party`\n", "type": "array", "items": { "$ref": "#/$defs/TaxLegalReference" } }, "partyContactDetails": { "type": "array", "description": "A list of contact details\n", "items": { "$ref": "#/$defs/PartyContactDetailHBL" } } }, "required": [ "partyName", "typeOfPerson" ] }, "TareWeight": { "type": "object", "title": "Tare Weight", "description": "The weight of an empty container (gross container weight).\n", "properties": { "value": { "type": "number", "format": "float", "minimum": 0, "exclusiveMinimum": true, "description": "The weight of an empty container (gross container weight).\n" }, "unit": { "type": "string", "description": "The unit of measure which can be expressed in imperial or metric terms\n- `KGM` (Kilograms)\n- `LBR` (Pounds)\n", "enum": [ "KGM", "LBR" ] } }, "required": [ "value", "unit" ] }, "TaxLegalReference": { "type": "object", "title": "Tax & Legal Reference", "description": "Reference that uniquely identifies a party for tax and/or legal purposes in accordance with the relevant jurisdiction.\n\nA small list of **potential** examples:\n\n| Type | Country | Description |\n|-------|:-------:|-------------|\n|EORI|NL|Economic Operators Registration and Identification|\n|PAN|IN|Goods and Services Tax Identification Number in India|\n|GSTIN|IN|Goods and Services Tax Identification Number in India|\n|IEC|IN|Importer-Exported Code in India|\n|RUC|EC|Registro Único del Contribuyente in Ecuador|\n|RUC|PE|Registro Único del Contribuyente in Peru|\n|NIF|MG|Numéro d'Identification Fiscal in Madagascar|\n|NIF|DZ|Numéro d'Identification Fiscal in Algeria|\n", "properties": { "type": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 50, "description": "The reference type code as defined by the relevant tax and/or legal authority.\n" }, "countryCode": { "type": "string", "pattern": "^[A-Z]{2}$", "minLength": 2, "maxLength": 2, "description": "The 2 characters for the country code using [ISO 3166-1 alpha-2](https://www.iso.org/obp/ui/#iso:pub:PUB500001:en)\n" }, "value": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 35, "description": "The value of the `taxLegalReference`\n" } }, "required": [ "type", "countryCode", "value" ] }, "UTEquipment": { "type": "object", "title": "Shipper Owned Equipment (SoC)", "description": "To be used for SoC (Shipper owned Containers). If `isShipperOwned` is true then the equipment used needs to be specified\n", "properties": { "isShipperOwned": { "type": "boolean", "description": "Indicates whether the container is shipper owned (SOC).\n" }, "equipment": { "$ref": "#/$defs/RequiredEquipment" } }, "required": [ "isShipperOwned", "equipment" ] }, "UTEquipmentReference": { "type": "object", "title": "Carrier Owned Equipment", "description": "To be used when referring to carrier owned containers (`isShipperOwned` is false). In this case it is only necessary to provide `equipmentReference`\n", "properties": { "isShipperOwned": { "type": "boolean", "description": "Indicates whether the container is shipper owned (SOC).\n" }, "equipmentReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 11, "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit).\n\nIf a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n" } }, "required": [ "isShipperOwned", "equipmentReference" ] }, "UtilizedTransportEquipmentHBL": { "type": "object", "title": "Utilized Transport Equipment (House B/L)", "description": "Specifies the container (`Equipment`), `Seals` and `References`\n", "properties": { "seals": { "type": "array", "minItems": 1, "description": "A list of `Seals`\n", "items": { "$ref": "#/$defs/Seal" } }, "emptyIndicatorCode": { "type": "string", "description": "Indication if the container is `EMPTY` or `LADEN`.\n\n- `EMPTY` (Empty)\n- `LADEN` (Laden)\n", "enum": [ "LADEN", "EMPTY" ] }, "isShipperOwned": { "type": "boolean", "description": "Indicates whether the container is shipper owned (SOC).\n" }, "equipmentReference": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 11, "description": "The unique identifier for the equipment, which should follow the BIC ISO Container Identification Number where possible.\nAccording to [ISO 6346](https://www.iso.org/standard/83558.html), a container identification code consists of a 4-letter prefix and a 7-digit number (composed of a 3-letter owner code, a category identifier, a serial number, and a check-digit).\n\nIf a container does not comply with [ISO 6346](https://www.iso.org/standard/83558.html), it is suggested to follow [Recommendation #2: Containers with non-ISO identification](https://smdg.org/documents/smdg-recommendations) from SMDG.\n" }, "ISOEquipmentCode": { "type": "string", "pattern": "^\\S(?:.*\\S)?$", "maxLength": 4, "description": "Unique code for the different equipment size and type used to transport commodities. The code can refer to one of ISO size type (e.g. 22G1) or ISO type group (e.g. 22GP) following the [ISO 6346](https://www.iso.org/standard/83558.html) standard.\n" } }, "required": [ "emptyIndicatorCode", "isShipperOwned", "equipmentReference", "ISOEquipmentCode" ] }, "UtilizedTransportEquipmentShipper": { "type": "object", "title": "Utilized Transport Equipment (Shipper)", "description": "Specifies the container (`Equipment`), `Seals` and `References`\n", "properties": { "shippingMarks": { "type": "array", "maxItems": 50, "description": "A list of the `ShippingMarks` applicable to this `UtilizedTransportEquipment`\n\n**Condition:** The order of the items in this array **MUST** be preserved as by the provider of the API.\n", "items": { "type": "string", "maxLength": 35, "description": "The identifying details of a package or the actual markings that appear on the package(s). This information is provided by the customer.\n" } }, "seals": { "type": "array", "minItems": 1, "description": "A list of `Seals`\n", "items": { "$ref": "#/$defs/Seal" } }, "emptyIndicatorCode": { "type": "string", "description": "Indication if the container is `EMPTY` or `LADEN`.\n\n- `EMPTY` (Empty)\n- `LADEN` (Laden)\n", "enum": [ "LADEN", "EMPTY" ] }, "references": { "type": "array", "description": "A list of `References`\n", "items": { "$ref": "#/$defs/Reference" } }, "customsReferences": { "type": "array", "description": "A list of `Customs references`\n", "items": { "$ref": "#/$defs/CustomsReference" } } }, "oneOf": [ { "$ref": "#/$defs/UTEquipment" }, { "$ref": "#/$defs/UTEquipmentReference" } ], "required": [ "seals" ] } } }