GS1 Transport Instruction

The GS1 Transport Instruction message (GS1-TI) is used to communicate the details of a shipment from a shipper to a carrier. The message is used to provide the carrier with all the necessary information to execute the shipment.

GS1 links:

• GS1 Transport Instruction v3.2
• Download GS1 TI package v3.2 Version: 2.1, Date: 2024-09-20

Revision history

Implementation guidelines

The message is implemented using following business rules:

One message = one consignment

1. The GS1 TI standard allows multiple consignments in one message, but our implementation contains always one consignment per message.
2. The message describes
   1. Consignment: the details of a movement from location A to place B. This contains all relevant information for the carrier to execute the shipment except for:
      1. Dangerous goods information which has to be collected from shipment level.
      2. Shipment reference(s) that receivers often are aware off, they can also be found on shipment level.
   2. Shipments: the details of the goods that are part of the consignment. Multiple shipments can be included, they can be destined for different locations.
3. The goal of the message is to order/book transportation for the consignment
4. The transportInstructionConsignment/transportInstructionTransportMovement is only used once, it describes the movement of the whole consignment.

Tracking Reference

The main reference which is expected to be used for:

• Track & Trace: this value has to be used when reporting back status updates on the consignment
• Invoice: This value has to be included on the invoice for the consignment

The tracking reference can be found in one of 2 places:

• transportInstruction/transportInstructionConsignment/ginc —> example below: 6139486828
  • Use this when the tracking reference is provided by the shipper, carrier has no preference
• transportInstruction/transportInstructionConsignment/additionalConsignmentIdentification for CARRIER_ASSIGNED —> example below: ABCD1234567
  • Use this when the carrier requires specific tracking references to be used. Carrier to provide the range to be used in this instance. Viya can setup that range of tracking references to be used.

Example:

  </logisticServicesBuyer>
  <transportInstructionConsignment>
    <ginc>6139486828</ginc>
    <additionalConsignmentIdentification additionalConsignmentIdentificationTypeCode="CARRIER_ASSIGNED">ABCD1234567</additionalConsignmentIdentification>
    <transportInstructionStatusCode>CONFIRMED</transportInstructionStatusCode>
    <consignor>

Our suggestion: Always use the transportInstruction/transportInstructionConsignment/additionalConsignmentIdentification for CARRIER_ASSIGNED, if there is no specific requirement for a number range: it will contain the same value as the GINC

Addresses

Take from the transportInstructionConsignment:

• pickUpParty: this is the shipFrom, this can be a hub or source shipping location.
• consignee: This is the shipTo, this can be an intermediate location or the final destination. But for the scope of the consignment this is the destination.
• consignor: The party who books the consignment

Optional:

• notitifyParty: The party who is expect to receive commercial invoice information, eg importer of record.
  • In case notifyParty is provided: the receiver is not entitled to get the commercial invoice.
  • Note: The VAT number is stored in: notitifyParty.dutyFeeTaxRegistration.dutyFeeTaxRegistrationID
• dropOffParty: intermediate address, if the goods are not delivered to the final receiver, but to e.g. an import agent. DropOffParty is the same as consignee in regular delivery scenarios and does only differ in case of an intermediate customer ship to scenario (DIAA instruction keeps this address) (Identification of the physical location to where goods will be or have been shipped)

Other addresses

• transportInstruction\logisticServicesBuyer: The party who is buying the transport services and should receive the freight invoice.

  • Note: Custom implementation exists, which should only be used in case directed during implementation. Implementations exists to use:

    Option a: The first 7 digits of the TransportInstuctionConsignment\containedShipmentReference\gsin

    The first GSIN determines the party who should receive the invoice.

    Option b: StandardBusinessDocumentHeader\Sender\Identifier

    <?xml version="1.0" encoding="UTF-8"?>
    <ns0:transportInstructionMessage xmlns:ns0="urn:gs1:ecom:transport_instruction:xsd:3">
      <ns1:StandardBusinessDocumentHeader xmlns:ns1="http://www.unece.org/cefact/namespaces/StandardBusinessDocumentHeader">
        <ns1:HeaderVersion>1.0</ns1:HeaderVersion>
        <ns1:Sender>
          <ns1:Identifier Authority="GS1">4001895000003</ns1:Identifier>
        </ns1:Sender>

  • Carrier assigned account number for a shipper is to be found in: transportInstructionMessage/transportInstruction/logisticServicesBuyer/financialInstitutionInformation/financialAccount/financialAccountNumber

Handling Units

Totals

The totals per handling unit type (boxes or pallets) are shown in: transportInstructionConsignment\packageTotal The packageTotal node is repeated for each packageTypeCode.

So if there are 2 boxes and 1 pallet, the message will contain:

<packageTotal>
  <packageTypeCode>BX</packageTypeCode>
  <totalPackageQuantity>2</totalPackageQuantity>
  <totalGrossVolume measurementUnitCode="CBM">0.713</totalGrossVolume>
  <totalGrossWeight measurementUnitCode="KGM">64.848 </totalGrossWeight>
</packageTotal>
<packageTotal>
  <packageTypeCode>PE</packageTypeCode>
  <totalPackageQuantity>1</totalPackageQuantity>
  <totalGrossVolume measurementUnitCode="CBM">1.250</totalGrossVolume>
  <totalGrossWeight measurementUnitCode="KGM">195.000 </totalGrossWeight>
</packageTotal>

Details

The physical handling units (Loose boxes / pallets) are shown in: transportInstructionConsignmetnItem\logisticUnit This contains a list of all logisticUnits with the weight and dimensions of each unit.

      <transportInstructionConsignmentItem>
        <lineItemNumber>1</lineItemNumber>
        <transportCargoCharacteristics>
          <cargoTypeCode>12</cargoTypeCode>
          <harmonizedSystemCode>0</harmonizedSystemCode>
        </transportCargoCharacteristics>
        <logisticUnit>
          <sscc>084100010250908857</sscc>
          <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000100</additionalLogisticUnitIdentification>
          <grossWeight measurementUnitCode="KGM">195.000</grossWeight>
          <packageTypeCode>PE</packageTypeCode>
          <dimension>
            <depth measurementUnitCode="CM">80.000000</depth>
            <height measurementUnitCode="CM">125.000000</height>
            <width measurementUnitCode="CM">120.000000</width>
          </dimension>
        </logisticUnit>
        <logisticUnit>
          <sscc>084100010250908864</sscc>
          <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000110</additionalLogisticUnitIdentification>
          <grossWeight measurementUnitCode="KGM">34.269</grossWeight>
          <packageTypeCode>BX</packageTypeCode>
          <dimension>
            <depth measurementUnitCode="CM">40.000000</depth>
            <height measurementUnitCode="CM">24.600000</height>
            <width measurementUnitCode="CM">30.000000</width>
          </dimension>
        </logisticUnit>
        <logisticUnit>
          <sscc>084100010250908865</sscc>
          <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000120</additionalLogisticUnitIdentification>
          <grossWeight measurementUnitCode="KGM">34.269</grossWeight>
          <packageTypeCode>BX</packageTypeCode>
          <dimension>
            <depth measurementUnitCode="CM">40.000000</depth>
            <height measurementUnitCode="CM">24.600000</height>
            <width measurementUnitCode="CM">30.000000</width>
          </dimension>
        </logisticUnit>
      </transportInstructionConsignmentItem>

Package type codes

The packageTypeCode is a code that describes the type of packaging used for the goods.
It is based on an international reference table and the code meaning must be agreed upon usage.

• Standard reference on gs1 website
• download package types
  • Filter in column B (“Code List”) on “PackageTypeCode”

In our package types page all mapped package types are listed, the unece code is used in the message.

Transport service

The service level code is based on the agreement between carrier and shipper. This must be used in the freight price determination and included in the freight invoice issued by the carrier.

The service level can be found in: transportInstructionConsignment\transportInstructionTerms\transportServiceLevelCode

<transportInstructionTerms>
  <transportServiceCategoryType>TM</transportServiceCategoryType>
  <transportServiceConditionType>SERVICE_LEVEL_NOT_DEFINED</transportServiceConditionType>
  <transportServiceLevelCode>DIRECT</transportServiceLevelCode>
</transportInstructionTerms>

Incoterms

Incoterms can be found in transportInstructionConsignment\deliveryTerms\incotermsCode.

<transportInstructionConsignment>
      <ginc>6139486828</ginc>
      <additionalConsignmentIdentification additionalConsignmentIdentificationTypeCode="CARRIER_ASSIGNED">ABCD1234567</additionalConsignmentIdentification>
      <transportInstructionStatusCode>CONFIRMED</transportInstructionStatusCode>
      <consignor>..</consignor>
      <consignee>..</consignee>
      <pickUpParty>..</pickUpParty>
      <transportInstructionTerms>..</transportInstructionTerms>
      <transportCargoCharacteristics>..</transportCargoCharacteristics>
      <transportInstructionTransportMovement>....</transportInstructionTransportMovement>
      <deliveryTerms>
        <incotermsCode>DAP</incotermsCode>
      </deliveryTerms>

Mode of transport

A mode-of-transport indicator is present in transportInstructionConsignment\transportInstructionTransportMovement. Expect values:

• 10 = Ocean
• 20 = Rail
• 30 = Road
• 40 = Air

<transportInstructionConsignment>
  <ginc>6139486828</ginc>
  <additionalConsignmentIdentification additionalConsignmentIdentificationTypeCode="CARRIER_ASSIGNED">ABCD1234567</additionalConsignmentIdentification>
  <transportInstructionStatusCode>CONFIRMED</transportInstructionStatusCode>
  <consignor>..</consignor>
  <consignee>..</consignee>
  <pickUpParty>..</pickUpParty>
  <transportInstructionTerms>..</transportInstructionTerms>
  <transportCargoCharacteristics>..</transportCargoCharacteristics>
  <transportInstructionTransportMovement>
    <sequenceNumber>1</sequenceNumber>
    <transportModeTypeCode>30</transportModeTypeCode>
    <carrier>

Service options

Planned dropoff / Customer requested delivery date

If a planned dropoff date is provided, it is shown in: transportInstructionConsignment.plannedDropOff.logisticEventDateTime for logisticEventTypeCode: CUSTOMER_REQUESTED_DELIVERY.

If this is provided, it is mandatory to delivery exactly on that date at the dropoff location.

Handling instructions

Various specific handling instructions can be provided in the message.
These are shown in: transportInstructionConsignment\handlingInstructions

Example:

    <transportInstructionConsignment>
      <ginc>4010000108006134370825</ginc>
      <transportInstructionStatusCode>CONFIRMED</transportInstructionStatusCode>
      <consignor>..</consignor>
      <consignee>..</consignee>
      <pickUpParty>..</pickUpParty>
      <transportInstructionTerms>..</transportInstructionTerms>
      <transportCargoCharacteristics>..</transportCargoCharacteristics>
      <transportInstructionTransportMovement>..</transportInstructionTransportMovement>
      <deliveryTerms>..</deliveryTerms>
      <packageTotal>..</packageTotal>
      <containedShipmentReference>..</containedShipmentReference>
      <transportReference>..</transportReference>
      <handlingInstruction>
        <handlingInstructionText languageCode="EN">TR02|packinglist is included</handlingInstructionText>
      </handlingInstruction>
      <handlingInstruction>
        <handlingInstructionText languageCode="EN">DDFD | Liefertermin fix:21.02.2024</handlingInstructionText>
      </handlingInstruction>
      <handlingInstruction>
        <handlingInstructionText languageCode="EN">DIAA|12345678#Companyname#Address line 1#Address line 2#streetnumber#CountryCode#postalcode#City#StateCode</handlingInstructionText>
      </handlingInstruction>

The instructions are alreays pipe-delimited with a code and additional information.
Expected codes are:

Shipments

The shipments contain the details of the goods that are part of the consignment. Multiple shipments can be included, they can be destined for different locations.

Customer references

Additional references that might be of interest of the receiver are shown as “additionalShipmentIdentification” in the shipment.

<transportInstructionShipment>
  <gsin>40236092991420471</gsin>
  <additionalShipmentIdentification additionalShipmentIdentificationTypeCode="CARRIER_ASSIGNED">8102260913_2025-03-26</additionalShipmentIdentification>
  <additionalShipmentIdentification additionalShipmentIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">2260913</additionalShipmentIdentification>
  <transportInstructionStatusCode>CONFIRMED</transportInstructionStatusCode>

Handling Units - packing hierarchy

The shipment contains all lower level handling unit information.
Handling Units that are packed onto another handling Unit (overpacked) are referring to the overpacked handling Unit which is displayed on Consignment level.

Consignment level contains all top level handling units, shipments contain all lowest level handling units with an optional reference to the top level handling unit.

The link between highest and lowest level handling unit is made in the shipment level where the lowest level handlingUnit has a parentLogisticUnitId that refers to the top level handling unit.

High level Example

Consignment contains 1 pallet (contains 3 boxes) and 2 loose boxes.

• The pallet is the overpacked/top handling unit.
• The 2 loose boxes are both visible as lowest level handling unit (in shipment) and top level handling unit (in consignment).

XML sample

logistic unit SSCC ..732 is packed onto an handling unit with SSCC ..916

• Consignment level: Only top level handling units are shown = SSCC ..916

  <transportInstructionConsignmentItem>
    <lineItemNumber>1</lineItemNumber>
    <transportCargoCharacteristics>
      <cargoTypeCode>12</cargoTypeCode>
      <harmonizedSystemCode>0</harmonizedSystemCode>
    </transportCargoCharacteristics>
    <logisticUnit>
      <sscc>200511443130723916</sscc>
      <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000010</additionalLogisticUnitIdentification>
      <grossWeight measurementUnitCode="KGM">103.000</grossWeight>
      <packageTypeCode>PE</packageTypeCode>
      <dimension>
        <depth measurementUnitCode="CM">120.000</depth>
        <height measurementUnitCode="CM">12.000</height>
        <width measurementUnitCode="CM">80.000</width>
      </dimension>
    </logisticUnit>
  </transportInstructionConsignmentItem>
</transportInstructionConsignment>

• Shipment level: Link is made between lowest level (SSCC ..732) and top level handling unit (SSCC ..916)

<transportInstructionShipmentItem>
  <lineItemNumber>1</lineItemNumber>
  <logisticUnit>
    <sscc>200511443130723732</sscc>
    <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000060</additionalLogisticUnitIdentification>
    <parentLogisticUnitId>
      <sscc>200511443130723916</sscc>
      <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000010</additionalLogisticUnitIdentification>
    </parentLogisticUnitId>
    <grossWeight measurementUnitCode="KGM">1.925</grossWeight>
    <packageTypeCode>BX</packageTypeCode>
    <dimension>
      <depth measurementUnitCode="CM">30.000</depth>
      <height measurementUnitCode="CM">19.000</height>
      <width measurementUnitCode="CM">25.500</width>
    </dimension>
  </logisticUnit>

Note 1: logisticUnits on shipment level that do not have a parentLogsiticUnitId, are top level handling units and will also be shown on consignment level.

Note 2: A logisticUnit with the same sscc can occur in multiple transportShipmentItem records, if that is the case: only 1 logistic was build but it contains multiple items. This is done to support multiple dangerousGoods records on the same handlingUnit.

Dangerous goods

The information is found on shipmentItem level but as it is part of the consignment, it can be rolled up to consignment level from carrier perspective.

Some items do not have a hazardous class but need to appear on a dangerous goods declaration, they are then listed with hazardous class “NO_INFORMATION”.

• The outer carton information is contained in the note node, the inner carton information is contained in the dangerous goods information node in the element dangerous goods description in a text string separated by pipe symbols (|). Example:

<transportInstructionShipmentItem>
        <lineItemNumber>14</lineItemNumber>
        <note languageCode="EN">NUMBER_OF_OUTER_PACKAGES=1.00 |GROSS_WEIGHT_DANGEROUS=5,679|OUTER_PACKAGE_INFORMATION=1.00 FIBREBOARD BOX (NON UN APPROVED)|HAZARDOUS_PACKAGE_TYPE=FIBREBOARD BOX (NON UN APPROVED)|DG_PACKING=BOX</note>
        <logisticUnit>
          <sscc>084100010250907362</sscc>
          <additionalLogisticUnitIdentification additionalLogisticUnitIdentificationTypeCode="LOGISTICS_SERVICE_PROVIDER_ASSIGNED">0000000530</additionalLogisticUnitIdentification>
          <grossWeight measurementUnitCode="KGM">143.739</grossWeight>
          <packageTypeCode>PE</packageTypeCode>
          <dimension>
            <depth measurementUnitCode="CM">80.000000</depth>
            <height measurementUnitCode="CM">100.700000</height>
            <width measurementUnitCode="CM">120.000000</width>
          </dimension>
        </logisticUnit>
        <transactionalTradeItem>
          <gtin>00051131050969</gtin>

• Always all agency declarations are transferred (ADR, IMD, ICA).
  • ADR shows information in local language of the pickup location and English, the other regulations in English only.
  • Main key for the DG is the UN number, which is posted as 6-character string containing prefix UN and following the 4 digits number
• All agency declarations have slightly different attributes but were mainly harmonized. The dangerousGoodsAttibute is optional.
• The ADR and IMD have max 1 class, ICA can have multiple classes.

Dangerous goods fields

Unfortunately there is a mix of keys for the same set of fields in the message. The same information can be found in 3 different places.
Use the following order to find the information, the first found is leading:

1. Try to find findKey in transportInstructionShipmentItem\dangerousGoodsInformation\dangerousGoodsRegulationInformation\ dangerousGoodsAttribute
2. Try to find findKey in string in transportInstructionShipmentItem\dangerousGoodsInformation\ dangerousGoodsDescription
3. Try to find findKey in string in transportInstructionShipmentItem\ note

Consider each field as optional as it can be missing in the message.

Keys:

• MARINE_POLLUTANT: Y or N
• MARINE_TECHNICAL_NAME: The technical name of the marine pollutant
• FLASHPOINT: Watch out, this is a string as it contains value like 17.20°C
• TUNNEL_RESTRICTION_CODE: eg (E)
• PACKAGING_INFORMATION: Contains the packingInstructions
• PACKAGING_INSTRUCTION_PASSENGER: Packing instructions for passenger aircraft
• PACKAGING_INSTRUCTION_CARGO: Packing instructions for cargo aircraft
• DG_PACKING: Contains the packaging type code, eg. 4G
• HAZARDOUS_PACKAGE_TYPE: THe packageing type description: eg FIBREBOARD BOX (NON UN APPROVED)
• NUMBER_OF_OUTER_PACKAGES: Number of outerpackages, eg 1.00
• GROSS_WEIGHT_DANGEROUS: Gross weight of the dangerous goods, eg 5,679
• OUTER_PACKAGE_INFORMATION: Outer packing description, eg 1.00 FIBREBOARD BOX (NON UN APPROVED)
• IP_INFO: Innerpacking information in long readable string, eg 12 INNER PACKAGING, METAL CAN, TIN OR TUBES (ALUMINIUM) 0.26 L
• IP_INNR: Number of innerpackages within an outerpack, eg 12
• IP_TYPE: Innerpacking description, eg INNER PACKAGING, METAL CAN, TIN OR TUBES (ALUMINIUM)
• IP_UNIT: Innerpacking unit, eg L
• IP_QTY: Innerpackaging quantity inside the inner package, eg 0.26
• SUBSIDIARY_CLASS1: The first Subsidiary Hazardous Class/Division that may be associated with a regulated material, eg 3
• TRANSPORT_CATEGORY: Transport category giving the limit for the exemp-tion according to ADR 1.1.3.6.
• TREM_CARD_NUMBER: TREMcard-number is the number of the information sheet used in case of an accident
• IND_EXCEPTED_QTY: Y or N
• IND_LIMITED_QTY: Y or N
• EMS_NUMBER
• MSDS_NUMBER
• DG_PHRASE: Plan text that can be used on dg declaration, eg UN1263, PAINT RELATED MATERIAL, 3, II
• DG_PHRASE2

Communication

1. The message is provided through SFTP, contact our carrier integration team for the details .
2. No confirmation message is expected from the carrier, this message is a one-way communication from shipper to carrier.
   1. Tracking messages are expected when executing the shipment, that can use any different format.

Examples

Browse through the examples to see how the message is structured and what fields are available.