Gateway XML

The carrier gateway XML format is designed by Viya to facilitate the communication between shippers and carriers. Changes are made to the format based on the feedback from carriers and shippers and the experience of Viya in the field.

Message format guidelines

  • The format(s) should be implemented in a way that additional fields can be added without breaking the implementation.
    • Viya will only remove fields or change the meaning of a field in a new mayor version of the format.
  • Inside the message an environment node indicates if this is a message for playground or production environment
  • Date/Datetime fields are in ISO 8601 format: YYYY-MM-DDThh:mm:ssZ where hh:mm:ss are 00:00:00 for date only
  • XML is in UTF-8 format

Revision history

  • 16-Jan-2024: Added link to the enumeration list of HandlingUnits.packageTypeCode
  • 02-Aug-2024: Added examples + REST API ordering

Supported message types

  • Ordering: Message contains one shipment that is requested by the shipper to be transported by the carrier
  • Comming soon: Manifest: Message contains all shipments loaded in one trailer

Ordering

  • The message can be communicated through SFTP, Email or through HTTP REST API (POST)
    • For SFTP + Email: No confirmation message is expected from the receiving party (=the carrier) of the message
    • For REST API: a response message is required, see Ordering Response
  • Once the message is generated, the execution of the shipment is considered to be argeed.
    • It can only be cancelled by an agreed method of cancellation outside the scope of this message.

See examples and schema of the XML format.

Format

Root element <Shipment>:

NameTypeRequired
Description
environmentstringtrueIndicates if the message is in a production or playground(test) environment.
Values production, playground
trackingReferencestringtrueUnique identifier of the order assigned by the shipper or Viya. Tracking events on shipment level should be reported against this reference.
referencestringtrueUnique identifier of the shipment assigned by the Shipper
addressesAddressCollectiontrueAll addresses related to this shipment
descriptionstringfalseGeneral description of goods
declaredValueAmountfalseThe declared value for customs purposes
timeWindowsTimeWindowstrueDate/Time windows for pickup and delivery of the shipment
incotermsIncotermsfalseDescribes the Transport Obligations, Costs and Risks through the definitions as released by the International Chamber of Commerce
weightUnitstringtrueUnit of Measure for any weight provided in the shipment.
Values: kgm (Kilogram), lbr (Pound)
dimensionUnitstringtrueUnit of Measure for any dimension (length, Width or Height) provided in the shipment
Values: cmt (Centimeter), inh (Inch)
inboundbooleanfalseIndicator if shipment is an inbound shipment, where Inbound is defined as:
A shipment being shipped into a facility belonging to the shipping platform customer, where the shipment is not a return
Where a return is defined as: a shipment that is returned to the shipping platform customer from an end-customer which can be directly related to an outbound shipment to that end-customer.
serviceLevelReferencestringfalseReference to service level of shipment
serviceOptionsServiceOptionsfalseAny service option that additionally applies to the shipment
referencesShipmentReferencesfalseCollection of References that can be included in the shipment
instructionsShipmentInstructionsfalseAny instructions on shipment level with an escape to add key/values at the end
commercialInvoiceCommercialInvoicefalseInvoice document used for Export Declaration
handlingUnits[HandlingUnit]trueList of Handling units containing the actual goods
accountsAccountsfalseAccounts for the order
isDomesticbooleanfalseCalculated field indicating if the shipment is domestic
isDutiablebooleanfalseCalculated field indicating if the shipment is dutiable
containsDangerousGoodsbooleanfalseCalculated field indicating if the shipment contains any dangerous goods
documents[Documents]falseList of documents associated with the shipment

AddressCollection

shipment > addresses

NameTypeRequired
Description
senderAddressWithAccounttrueThe party who initiates the shipment, responsible for the booking
receiverAddressWithAccounttrueThe party that should receive the goods being shipped
dutiesTaxesAddressWithAccountfalseParty that should pay for Duties and taxes if it is not the Sender or Receiver (depending on the chosen incoterm)
collectionAddressfalseAddress where the goods should be collected
thirdPartyAddressWithAccountfalseParty that should pay for the transportation costs (and potentially duties taxes depending on the chosen incoterm)
buyerAddressfalseBuyer of the goods
sellerAddressfalseParty that is selling the goods
ultimateAddressfalseParty that is considered the ultimate receiver of the goods in case goods are forwarded after they reached the Receiver
brokerAddressWithAccountfalseParty that is responsible for the brokerage of the shipment, only specify if specific/alternative broker should be used
importerOfRecordAddressWithAccountfalseParty that is acting as the importer of record in case that is not the Sender
dropOffDropOffAddressfalseAddress where the shipment can be dropped of for final delivery. The Receiver can then collect it from this Drop-off address.
returnAddressfalseAddress where the shipment can be returned to in case it cannot be delivered to the Receiver
carrierAgentAddressWithAccountfalseAddress of an agent that handles contact with the carrier, typically used for Ocean
notifyAddressfalseAddress of the party that should be notified about the shipment, typically used for Ocean or Air
shippingLocationAddressfalseAddress that is responsible for ordering the shipment
neutralSenderAddressfalseAddress the carrier should use as the sender address in its communication towards the receiver. This is used to ‘hide’ the actual sender address from the receiver of the shipment.

AddressWithAccount

shipment > addresses > various

NameTypeRequired
Description
companyNamestringfalseName of the company, for B2C this can be left empty
addressLine1stringtrueStreet name / PO Box
addressLine2stringfalseApartment, suite, unit, building floor etc.
addressLine3stringfalseAdditional address line for extra details
streetNumberstringfalseStreet/house number to identify a specific building or apartment in a street
citystringfalseCity of address
stateCodestringfalseState code used primarily for US, Canada, Italy
postCodestringfalsePostcode/zipcode
countryCodeCountryCodetrue2-digit ISO-3166 Country code
vatstringfalseValue Added Tax identifier
eoristringfalseEconomic Operators Registration and Identification
contactNamestringfalseName of contact person
contactPhonestringfalsePhone number of contact person
contactEmailstring(email)falseEmail address of contact person
carrierAccountReferencestringfalseAccount number known/given by the carrier for this address

Address

shipment > addresses > various

NameTypeRequired
Description
companyNamestringfalseName of the company, for B2C this can be left empty
addressLine1stringtrueStreet name / PO Box
addressLine2stringfalseApartment, suite, unit, building floor etc.
addressLine3stringfalseAdditional address line for extra details
streetNumberstringfalseStreet/house number to identify a specific building or apartment in a street
citystringfalseCity of address
stateCodestringfalseState code used primarily for US, Canada, Italy
postCodestringfalsePostcode/zipcode
countryCodeCountryCodetrue2-digit ISO-3166 Country code
vatstringfalseValue Added Tax identifier
eoristringfalseEconomic Operators Registration and Identification
contactNamestringfalseName of contact person
contactPhonestringfalsePhone number of contact person
contactEmailstring(email)falseEmail address of contact person

DropOffAddress

shipment > addresses > dropOffAddress

Address where the shipment can be dropped of for final delivery. The Receiver can then collect it from this Drop-off address.

NameTypeRequired
Description
companyNamestringfalseName of the company, for B2C this can be left empty
addressLine1stringtrueStreet name / PO Box
addressLine2stringfalseApartment, suite, unit, building floor etc.
addressLine3stringfalseAdditional address line for extra details
streetNumberstringfalseStreet/house number to identify a specific building or apartment in a street
citystringfalseCity of address
stateCodestringfalseState code used primarily for US, Canada, Italy
postCodestringfalsePostcode/zipcode
countryCodeCountryCodetrue2-digit ISO-3166 Country code
vatstringfalseValue Added Tax identifier
eoristringfalseEconomic Operators Registration and Identification
contactNamestringfalseName of contact person
contactPhonestringfalsePhone number of contact person
contactEmailstring(email)falseEmail address of contact person
carrierAssignedAddressIdstringfalseIdentifier by which the carrier identifies the drop-off location, the former DropOffId
Use this in combination with ServiceOptions.HoldForPickup

Amount

Monetary amount container

NameTypeRequired
Description
valuenumber(double)trueThe value of the monetary amount in the given currency
currencyCodestringtrue3-digit ISO-4217 currency code.
Currency codes based on ISO 4217, see wikipedia: : AED, AFN, ALL, AMD, ANG, AOA, ARS, AUD, AWG, AZN, BAM, BBD, BDT, BGN, BHD, BIF, BMD, BND, BOB, BOV, BRL, BSD, BTN, BWP, BYN, BZD, CAD, CDF, CHE, CHF, CHW, CLF, CLP, COP, COU, CRC, CUC, CUP, CVE, CZK, DJF, DKK, DOP, DZD, EGP, ERN, ETB, EUR, FJD, FKP, GBP, GEL, GHS, GIP, GMD, GNF, GTQ, GYD, HKD, HNL, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JMD, JOD, JPY, KES, KGS, KHR, KMF, KPW, KRW, KWD, KYD, KZT, LAK, LBP, LKR, LRD, LSL, LYD, MAD, MDL, MGA, MKD, MMK, MNT, MOP, MRU, MUR, MVR, MWK, MXN, MXV, MYR, MZN, NAD, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PGK, PHP, PKR, PLN, PYG, QAR, RON, RSD, CNY, RUB, RWF, SAR, SBD, SCR, SDG, SEK, SGD, SHP, SLE, SLL, SOS, SRD, SSP, STN, SVC, SYP, SZL, THB, TJS, TMT, TND, TOP, TRY, TTD, TWD, TZS, UAH, UGX, USD, USN, UYI, UYU, UYW, UZS, VED, VES, VND, VUV, WST, XAF, XAG, XAU, XBA, XBB, XBC, XBD, XCD, XDR, XOF, XPD, XPF, XPT, XSU, XTS, XUA, XXX, YER, ZAR, ZMW, ZWL

TimeWindows

shipment > timeWindows

NameTypeRequired
Description
pickupcontainertrueDate range regarding the pickup/collection moment
pickup\startdateTimetrueStart DateTime of range. NOTE: Time zone specification is mandatory
pickup\enddateTimefalseEnd DateTime of range. NOTE: Time zone specification is mandatory
deliverycontainerfalseDate range regarding the delivery moment
delivery\startdateTimetrueStart DateTime of range. NOTE: Time zone specification is not allowed
delivery\enddateTimefalseEnd DateTime of range. NOTE: Time zone specification is not allowed
delivery\fixedBooleanfalseIs the date range a fixed time
delivery\onlySaturdayBooleanfalseIs this date range an only-saturday window

Incoterms

shipment > incoterms

Indicates the Responsibilities for Cost/Insurance/Risks for the shipment

NameTypeRequired
Description
scopestringtrueDescribes the scope of the incoterm
Allowed values:
-doorToDoor
-doorToPort
-portToDoor
-portToPort
incotermstringtrueAny of the Incoterms as released in 2000,2010,2020
Values: exw, fca, cpt, cip, dat, dap, ddp, ddu, cif, fob, dpu, fas, cfr
placestringfalseThe Named Place that applies to the incoterm
versionstringtrueThe International Chamber of Commerce (ICC) releases updates periodically, indicate which version of the release is being applied
Values: 2000, 2010, 2020

ServiceOptions

shipment > serviceOptions

NameTypeRequired
Description
allowDeliveryToNeighbourbooleanfalseCarrier is allowed to deliver the shipment to the neighbour
appointmentForDeliverybooleanfalseCarrier has to contact the Receiver to make an appointment for delivering the shipment
cargoArrangementstringfalseUsed in Air booking form.
Values: pickup, selfDelivery
cargoClixbooleanfalseIndicate if carriers should use the CargoClix platform to make an appointment
cashOnDeliverycontainerfalseReceiver to pay the transportation company for the goods upon delivery
cashOnDelivery\valuedecimaltrueCash on delivery amount
cashOnDelivery\currencyCodestringtrue3-digit ISO-4217 currency code.
Currency codes based on ISO 4217, see wikipedia
cashOnDelivery\typestringtrueCash on Delivery type that indicates how the payment should be handled
Values: cash, cheque, draft, moneyOrder, cashierCheque
constructionSitebooleanfalseShip to address ia a construction site
containsLithiumBatteriesbooleanfalseSet to true if the shipment contains Lithium Batteries
customsClearancebooleanfalseIf shipments are shipped within the EU from a bonded warehouse, this field can be provided to indicate the shipment is dutiable. Note that not all carrier interfaces are able to handle this information.
deliveryInsidebooleanfalseShipment has to be delivered inside a building to a specific room
documentServicecontainerfalseUsed Ocean and Air booking form.
documentService\serviceCodestringtrueCode indicating how the document shall be delivered to the forwarder
Values: original, house, telex, forwardsCargoReceipt, pickup
documentService\datedateTimefalseDate the document (air booking form) is available for collection by the carrier if ServiceCode=Pickup. NOTE: Time zone specification is mandatory.
dryIceAuditbooleanfalseCarrier is expected to verify if Dry Ice is in correct shape during the transportation process
equipmentTemperaturestringfalseDescribes the temperature under which the shipment should be transported in case of temperature sensitive goods.
Values: ambient, cooled, frozen, dryIceReplenishment, cryo
fragilebooleanfalseIndicates if the shipment contains Fragile goods
holdForPickupbooleanfalseSet to True in combination with Drop off Address, this is used for carrier services like “hold at depot”
liftGatecontainerfalseIndicator if a liftGate is required for pickup or delivery
liftGate\collectionbooleanfalseIndicator if a liftGate is required for pickup
liftGate\deliverybooleanfalseIndicator if a liftGate is required for delivery
lockerDeliverycontainerfalseContainer to indicate details in case delivery should be made into locker
lockerDelivery\locationCodestringfalseCode that identifies the physical location of the locker
lockerDelivery\lockerReferencestringtrueReference that uniquely identifies a locker at a given location
lockerDelivery\entryCodestringfalseEntry code to access the Locker
lockerDelivery\providerNamestringfalseName of the provider who services the Locker
neutralDeliverybooleanfalsetrue = neutral delivery, carrier to remove invoice from package before delivery to customer
false = different company may pays duties and taxes but no need for the carrier to remove the inter-company invoice
photoAtDeliverybooleanfalseCarrier is requested to make a photo of the package upon delivery
preAdviceDeliverycontainerfalseCommunication properties that can be used to pre-advice a receiver of a pending delivery
preAdviceDelivery\useEmailbooleanfalseAn Email should be sent to the receiver
preAdviceDelivery\useSmsbooleanfalseAn SMS prior to delivery
preAdviceDelivery\usePhonebooleanfalseA call should be made prior to delivery, eg a call made by the planning department a (few) day(s) in advance
preAdviceDelivery\useDriverPhonebooleanfalseThe driver should call short moments prior to delivery
residentialDeliverybooleanfalseIndicator that flags the shipment is shipped to a residential address
scannedPodRequestedbooleanfalseCarrier is requested to provide a scanned image of a signed POD
signatureForDeliverystringfalseSignature upon delivery options.
Valus: none, consigneeOnly, indirect, adult, noSignatureRequired
smallVehiclebooleanfalseCarrier should use a small vehicle for delivery
splitDutiesFromVatbooleanfalseCarrier to split the Duties and the VAT across different accounts (UPS/DPD)

ShipmentReferences

shipment > references

Collection of References that can be included in the shipment

NameTypeRequired
Description
billOfLadingNumberstringfalseCan also be put in TrackingReference depends on mapping for your solution. Discuss with your implementation resource for use of this field
bookingConfirmationNumberstringfalseA confirmation number obtained from the carrier
complaintNumberstringfalseReference number of a complaint that initiated this shipment
containerNumberstringfalseContainer number in which this shipment is included
costCenterstringfalseReference to where the costs of this shipment are expected to be charged to. This is a reference field only, no cost assignments are made based on this field by default.
customsClearanceNumberstringfalseThe reference provided by from customs (eg MRN number)
customerPurchaseOrderstringfalsePurchase order number from the Receiving Party
flightNumberstringfalseFlight number for Airfreight shipment
generalLedgerCodestringfalseGL code to be visible in reporting
loadNumberstringfalseShipments can be grouped into loads, this number identifies which group this shipment belongs to
purchaseOrderstringfalsePurchase order number from the Sending Party
rmaNumberstringfalseReturn Material Authorization reference
sapDeliverystringfalseDelivery number when using SAP
sapSalesOrderstringfalseSAP Sales order reference
shipmentNumberstringfalseReceiver Shipment number
voyagestringfalseReference to the Voyage in Sea shipment

ShipmentInstructions

shipment > instructions

Any instructions related to the shipment

NameTypeRequired
Description
airportFromstringfalseIATA Airport code for origin Airport
airportTostringfalseIATA Airport code for destination Airport
branchstringfalseBranch/Plant ordering the PO.
carrierInstructionscontainerfalseSpecial instructions for the carrier
carrierInstructions\collectionstringfalseInstructions for the carrier to be carried out during collection
carrierInstructions\transportstringfalseInstructions for the carrier to be carried out during transport
carrierInstructions\deliverystringfalseInstructions for the carrier to be carried out during delivery
carrierOriginDepotstringfalseOrigin depot of the carrier when injecting shipments into the carrier’s network
carrierRouteCodestringfalseA carrier defined identifier that indicates which route they will use to execute the transport of the shipment
containsPackingListbooleanfalseIndicates whether or not the Packing List is enclosed with the shipment
dockcontainerfalseInformation about the dock used for a shipment
dock\loadingstringfalseDock to be used for loading the shipment
dock\unloadingstringfalseDock to be used for unloading the shipment
justificationstringfalseFree Text justifying why the specific service was chosen. Typically used when more expensive service is chosen by the user.
latestCancelDatestring(date-time)falseLatest Date the shipment can be cancelled. This is for reference only, no system logic is used on this.. NOTE: Time zone specification is mandatory
licensePlatestringfalseLicensePlate of the trailer collecting the shipment
loadMeternumber(double)falseIf provided the load meter that overwrites any possible calculated load meter based on the handling units
modeOfTransportstringfalseIndicates the primary mode of transport for the shipment.
Values: none, air, express, road, ocean
multipleBolbooleanfalseIndicates if multiple BillOfLading are included in the shipment
notifyEmailscontainerfalseExtra email addresses that should be included in shipment notifications
notifyEmails\emailstring(email)
1..n occurances.
falseEmail address that should be included in shipment notifications
orderingCompanystringfalseCompany ordering the PO
orderTypestringfalseOrder type of the order in the shipment
paymentTypestringfalseType indicating how the order is paid by the Customer
Values: creditCard, cashOnDelivery, accountsReceivable, accountsReceivableIntercompany
piecesOnPalletsinteger(int32)falseTotal number of pieces in all pallets in the shipment
placeDocumentCollectionstringfalseUsed in air and ocean booking form
portFromstringfalseDeparture Sea port name
portTostringfalseDestination Sea port name
purchaseOrderCancelDatestring(date-time)falseCancel date of the PO. NOTE: Time zone specification is not allowed
purchaseOrderStartDatestring(date-time)falseStart date of the Purchase Order, this is the earliest date it can be delivered to the customer. NOTE: Time zone specification is not allowed
reasonForReturnstringfalseFree text indicating why shipment was returned
replenishmentbooleanfalseIndicates if shipment is a replenishment of stock for a Distribution Center
rmaDatestring(date-time)falseDate the Return Material Authorization was given. NOTE: Time zone specification is mandatory
vesselNamestringfalseVessel name for sea transport
woodDeclarationbooleanfalseTrue if a wood declaration is provided/included in the shipment

CommercialInvoice

shipment > commercialInvoice

Invoice document used for Export Declaration

| Name | Type | Required | Description | | ------------------------------ | ------------------------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --- | ----- | ----- | | invoiceNumber | string | false | Invoice number assigned to this invoice | | charges | container | false | Additional charges besides the charges on Invoice line level | | charges\freight | container | false | Additional charges besides the charges on Invoice line level | | charges\freight\value | decimal | true | The value of the monetary amount in the given currency | | charges\freight\currencyCode | string | true | The value of the monetary amount in the given currency
Currency codes based on ISO 4217, see wikipedia | | charges\insurance | container | false | Additional charges besides the charges on Invoice line level | | false | false | | charges\insurance\value | decimal | true | The value of the monetary amount in the given currency | | charges\insurance\currencyCode | string | true | The value of the monetary amount in the given currency
Currency codes based on ISO 4217, see wikipedia | | charges\discount | container | false | Additional charges besides the charges on Invoice line level | | charges\discount\value | decimal | true | The value of the monetary amount in the given currency | | charges\discount\currencyCode | string | true | The value of the monetary amount in the given currency
Currency codes based on ISO 4217, see wikipedia | | declarationStatement | string | false | Custom Declaration statement to be shown at invoice | | exportReason | container | false | Reason for exporting goods | | exportReason\reason | string | false | Free Text to indicate the reason | | exportReason\type | string | true | List of most commonly used codes by carriers implemented
Values: permanent, temporary, returnToOrigin, return, exhibition, interCompany, sale, personalUse, sample, gift, diplomatic, defence | | remarks | string | false | Additional remarks to include on the invoice | | lines | [CommercialInvoiceLine] | true | All goodsItem lines on the invoice | | customsProcedureCode | string | false | Procedure code for customs |

CommercialInvoiceLine

shipment > commercialInvoice > lines > line

One line on a commercialInvoice

NameTypeRequired
Description
idinteger(int32)trueSequential number for each invoice line, starting with 1 and incrementing with 1
externalIdstringfalseRow identifier in Sender host system if required
descriptionstringtrueGoods description
quantitycontainertrueQuantity of the SKU
quantity\valuedecimaltrueNumber
quantity\unitOfMeasurestringtrueValues: ea, kgm, lbr, ltr, mtr, cmt, bx
unitCustomsValuecontainertrueCustoms value per unit/each. To get the line value multiply this with lines.quantity.amount
unitCustomsValue\valuedecimaltrueThe value of the monetary amount in the given currency
unitCustomsValue\currencyCodestringtrueCurrency codes based on ISO 4217, see wikipedia
countryOfOriginCountryCodefalse2-digit ISO-3166 country code for the primary country that the product originates from.
itemNumberstringtrueSKU number
purchaseOrderstringfalseThe PO number of the PO of the sending party, typically in drop-ship/cross-dock
purchaseOrderLineNumberinteger(int32)falseThe PO line number of the PO of the sending party
customerPurchaseOrderstringfalseThe PO of the receiving party
weightcontainerfalseWeight of the total InvoiceLine for this ItemNumber
Customs value per unit/each. To get the line value multiply this with lines.quantity.amount
weight\grossdecimalfalseGross weight
weight\nettdecimalfalseNett weight
lotNumberstringfalseLot/Batch number
temperatureLoggerReferencestringfalseReference to a temperature logging device for temperature controlled goods
expirationDatestring(date-time)falseThe date the goods will expire. NOTE: Time zone specification is mandatory
customscontainerfalseSection containing customs identification for the given SKU
customs\customsCodestringfalseThe HS code for the goods, US government documentation: https://www.trade.gov/harmonized-system-hs-codes
customs\eccnstringfalseExport Control Classification Number, see https://www.bis.doc.gov/index.php/licensing/commerce-control-list-classification/export-control-classification-number-eccn
customs\scheduleBstringfalseThe Schedule B code is a U.S.-specific coding system used by the U.S. government to monitor U.S. exports. According to the export.gov website: https://www.census.gov/foreign-trade/schedules/b/index.html

HandlingUnit

shipment > handlingUnits > handlingUnit

Handling unit containing the actual goods

NameTypeRequired
Description
sequenceinteger(int32)trueUnique sequence number per HandlingUnit, start with 1 and increment with 1 for each HandlingUnit
weightnumber(double)trueWeight of the HandlingUnit in unit of measure set in WeightUnit
lengthnumber(double)trueLength of HandlingUnit in unit of measure set in VolumeUnit
widthnumber(double)trueWidth of HandlingUnit in unit of measure set in VolumeUnit
heightnumber(double)trueHeight of HandlingUnit in unit of measure set in VolumeUnit
packageTypeCodestringtruePackage code identifying the packaging used, for valid codes see Handlingunit package types
isDocumentbooleanfalseIndicates if the HandlingUnit is a document
descriptionstringfalseFree text that indicates what goods are packed in the HandlingUnit
isStackablebooleanfalseIndicates if the HandlingUnit can be stacked onto or on other stackable HandlingUnits
referencescontainerfalseAny references identifying this HandlingUnit
references\referencestringfalseUnique reference to the HandlingUnit, typically a packageId or SSCC code from a WMS
references\temperatureLoggerReferencestringfalseReference to a temperature logging device for temperature controlled goods
references\trackingReferencestringfalseHandling unit specific trackingReference. This is generated by Viya if desired. Tracking events on handling unit should reference this value.
references\rfidReferencestringfalseThis is the RFID tag number
serviceOptionsHandlingUnitServiceOptionsfalseThis indicates any additional service that should be applied for this handling unit
goodsItems[GoodsItem]falseIdentifies goods inside a handlingUnit

HandlingUnitServiceOptions

shipment > handlingUnit > serviceOptions

This indicates any additional service that should be applied for this handling unit

NameTypeRequired
Description
additionalHandlingbooleanfalseIndicates if the handling unit requires additional handling
equipmentTemperaturestringfalseDescribes the temperature under which the shipment should be transported in case of temperature sensitive goods.
Values: ambient, cooled, frozen, dryIceReplenishment, cryo
insuredValuecontainerfalseValue to be insured
insuredValue\valuedecimaltrueThe value of the monetary amount in the given currency
insuredValue\currencyCodestringtrueCurrency codes based on ISO 4217, see wikipedia

GoodsItem

shipment > handlingUnit > goodsItems > goodsItem

Identifies goods inside a handlingUnit

NameTypeRequired
Description
itemNumberstringtrueSKU
descriptionstringtrueDescription of the SKU
quantitycontainerfalseQuantity of the SKU in the handlingUnit
quantity\valuedecimaltrueNumber
quantity\unitOfMeasurestringtrueValues: ea, kgm, lbr, ltr, mtr, cmt, bx
purchaseOrderstringfalseThe PO number of the PO of the sending party, typically in drop-ship/cross-dock
purchaseOrderLineNumberinteger(int32)falseThe PO line number of the PO of the sending party
customerPurchaseOrderstringfalseThe PO of the receiving party
weightcontainerfalseWeight of the total GoodsItem for this ItemNumber in unit of measure set in WeightUnit
weight\grossdecimalfalseGross weight
weight\nettdecimalfalseNett weight
lotNumberstringfalseLot/Batch number
expirationDatestring(date-time)falseThe date the goods will expire. NOTE: Time zone specification is mandatory
dangerousGoods[DangerousGoodsItem]falseContainer that holds list of dangerous goods components for the given goodsItem

DangerousGoodsItem

shipment > handlingUnit > goodsItem > dangerousGoods > dangerousGood

All properties for one dangerous goods component

NameTypeRequired
Description
typestringtrueclassifies the GoodsItem on how it is regulated. If multiple regulations apply, take the highest regulated type
Values: exceptedQuantity, limitedQuantity, lithiumBatteries, dryIce, passengerAircraftOk, cargoAircraftOnly, radioActiveMaterial
unNumberstringfalseThe UN number or DOT number, eg UN3313
classstringfalseDangerous goods Class, eg 3.1
properShippingNamestringfalseProper shipping name in English
technicalNamestringfalseTechnical name in english
packingGroupstringfalsePacking group. Eg I, II or III
quantitycontainerfalseQuantity In relation to UnitOfMeasure (e.g. if UnitOfMeasure = LTR and quantity = 0.1 - > item contains 0.1 Liter of Dangerous goods
quantity\valuedecimaltrueNumber
quantity\unitOfMeasurestringtrueValues: ea, kgm, lbr, ltr, mtr, cmt, bx
packingInstructionscontainerfalseFor DangerousGoodsType LithiumBatteries (LB) provide the proper packaging information. Please note that not all PI combinations are allowed nor will the software check the values if it is possible.
packingInstructions\instructionstring
1..n occurances
trueThe packing instruction code: Eg: PI965, PI967 and PI970
packingCodestringfalseCode like 4G for fibreboard box
packingDescriptionstringfalsePackage code like “Fibreboard box”
sectionstringfalseUsed for LithiumBatteries, this is the section of the Packing instruction that applies to the Battery, eg section II or IA
subriskstringfalseAdditional risk next to its primary class.
classificationCodestringfalseSee https://adrbook.com/en/2017/ADR/1.9.5.2.2 and search for example code “TFC”
transportCategorystringfalseCategory used to determine hwo many units can be combined into 1 transport unit
tunnelRestrictionCodestringfalseCode that indicates if /when goods are restricted to be transported through tunnels
isEnvironmentallyHazardousbooleanfalseIs the item Environmentally Hazardous
aircraftAccessibilitystringfalseHow accessible is the aircraft for loading and unloading.
Values: accessible (Goods have to stored directly accessible to cabin-crew) or inaccessible.
weightcontainerfalseGross and net weight of the dangerous goods component in unit of measure set in WeightUnit
weight\grossdecimalfalseGross weight
weight\nettdecimalfalseNett weight
volumecontainerfalseGross and net volume of the dangerous goods component in cubic unit of measure set in VolumeUnit
volume\grossdecimalfalseGross Volume
volume\nettdecimalfalseNett Volume

Accounts

shipment > accounts

Model to hold the account references used by the carriers to identify responsible parties

NameTypeRequired
Description
sendercontainertrueReference for the party that booked the shipment.
sender\referencestringtrueAccount reference code.
sender\relationTypestringtrueRelation type of account
Values: sender, receiver, thirdParty, dutiesAndTaxes
transportcontainertrueReference for the party that is responsible for paying the transport charges.
transport\referencestringtrueAccount reference code.
transport\relationTypestringtrueRelation type of account
Values: sender, receiver, thirdParty, dutiesAndTaxes
dutiescontainerfalseReference for the party that is responsible for paying the duties and taxes charges.
duties\referencestringtrueAccount reference code.
duties\relationTypestringtrueRelation type of account
Values: sender, receiver, thirdParty, dutiesAndTaxes

Documents

shipment > documents > document

Any document associated with the shipment

NameTypeRequired
Description
fileExtensionstringtrueFile extension eg jpeg, pdf, docx etc..
fileNamestringtrue
fileContentstringtrueBase64 encoded content of the file
documentTypestringtrueType of document
Values: packingList, commercialInvoice, proformaInvoice, certificateOfOrigin, exportDeclaration, letterOfCredit, cmr, billOfLading, other

CountryCode

Country codes based on ISO 3166, see wikipedia:
Codes
AD, AE, AF, AG, AI, AL, AM, AO, AQ, AR, AS, AT, AU, AW, AX, AZ, BA, BB, BD, BE, BF, BG, BH, BI, BJ, BL, BM, BN, BO, BQ, BR, BS, BT, BV, BW, BY, BZ, CA, CC, CD, CF, CG, CH, CI, CK, CL, CM, CN, CO, CR, CU, CV, CW, CX, CY, CZ, DE, DJ, DK, DM, DO, DZ, EC, EE, EG, EH, ER, ES, ET, FI, FJ, FK, FM, FO, FR, GA, GB, GD, GE, GF, GG, GH, GI, GL, GM, GN, GP, GQ, GR, GS, GT, GU, GW, GY, HK, HM, HN, HR, HT, HU, ID, IE, IL, IM, IN, IO, IQ, IR, IS, IT, JE, JM, JO, JP, KE, KG, KH, KI, KM, KN, KP, KR, KW, KY, KZ, LA, LB, LC, LI, LK, LR, LS, LT, LU, LV, LY, MA, MC, MD, ME, MF, MG, MH, MK, ML, MM, MN, MO, MP, MQ, MR, MS, MT, MU, MV, MW, MX, MY, MZ, NA, NC, NE, NF, NG, NI, NL, NO, NP, NR, NU, NZ, OM, PA, PE, PF, PG, PH, PK, PL, PM, PN, PR, PS, PT, PW, PY, QA, RE, RO, RS, RU, RW, SA, SB, SC, SD, SE, SG, SH, SI, SJ, SK, SL, SM, SN, SO, SR, SS, ST, SV, SX, SY, SZ, TC, TD, TF, TG, TH, TJ, TK, TL, TM, TN, TO, TR, TT, TV, TW, TZ, UA, UG, UM, US, UY, UZ, VA, VC, VE, VG, VI, VN, VU, WF, WS, YE, YT, ZA, ZM, ZW, AC, CP, CQ, DG, EA, EU, EZ, FX, IC, SU, TA, UK, UN, XK

Ordering response

When Viya uses REST API to communicate the Ordering message, the receiver of the message should respond with:

  • Success message with HTTP status code 200, with optional body
<response>
<resultMessages>
<message>Optional: Any message user should see</message>
<message>extra lines</message>
</resultMessages>
</response>
  • Error message with HTTP status code 400 with at least 1 <error> element:
<response>
<errors>
<error>
<code>Mandatory: Unique code per error type</code>
<message>Mandatory: Short text indicating the error</message>
<explanation>Optional: Any explanation for user on cause and optional how to resolve the error</explanation>
</error>
</errors>
</response>