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>`:

Name	Type	Required	Description
environment	string	true	Indicates if the message is in a production or playground(test) environment. Values `production`, `playground`
trackingReference	string	true	Unique identifier of the order assigned by the shipper or Viya. Tracking events on shipment level should be reported against this reference.
reference	string	true	Unique identifier of the shipment assigned by the Shipper
addresses	AddressCollection	true	All addresses related to this shipment
description	string	false	General description of goods
declaredValue	Amount	false	The declared value for customs purposes
timeWindows	TimeWindows	true	Date/Time windows for pickup and delivery of the shipment
incoterms	Incoterms	false	Describes the Transport Obligations, Costs and Risks through the definitions as released by the International Chamber of Commerce
weightUnit	string	true	Unit of Measure for any weight provided in the shipment. Values: `kgm` (Kilogram), `lbr` (Pound)
dimensionUnit	string	true	Unit of Measure for any dimension (length, Width or Height) provided in the shipment Values: `cmt` (Centimeter), `inh` (Inch)
inbound	boolean	false	Indicator 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.
serviceLevelReference	string	false	Reference to service level of shipment
serviceOptions	ServiceOptions	false	Any service option that additionally applies to the shipment
references	ShipmentReferences	false	Collection of References that can be included in the shipment
instructions	ShipmentInstructions	false	Any instructions on shipment level with an escape to add key/values at the end
commercialInvoice	CommercialInvoice	false	Invoice document used for Export Declaration
handlingUnits	[HandlingUnit]	true	List of Handling units containing the actual goods
accounts	Accounts	false	Accounts for the order
isDomestic	boolean	false	Calculated field indicating if the shipment is domestic
isDutiable	boolean	false	Calculated field indicating if the shipment is dutiable
containsDangerousGoods	boolean	false	Calculated field indicating if the shipment contains any dangerous goods
documents	[Documents]	false	List of documents associated with the shipment

AddressCollection

shipment > addresses

Name	Type	Required	Description
sender	AddressWithAccount	true	The party who initiates the shipment, responsible for the booking
receiver	AddressWithAccount	true	The party that should receive the goods being shipped
dutiesTaxes	AddressWithAccount	false	Party that should pay for Duties and taxes if it is not the Sender or Receiver (depending on the chosen incoterm)
collection	Address	false	Address where the goods should be collected
thirdParty	AddressWithAccount	false	Party that should pay for the transportation costs (and potentially duties taxes depending on the chosen incoterm)
buyer	Address	false	Buyer of the goods
seller	Address	false	Party that is selling the goods
ultimate	Address	false	Party that is considered the ultimate receiver of the goods in case goods are forwarded after they reached the Receiver
broker	AddressWithAccount	false	Party that is responsible for the brokerage of the shipment, only specify if specific/alternative broker should be used
importerOfRecord	AddressWithAccount	false	Party that is acting as the importer of record in case that is not the Sender
dropOff	DropOffAddress	false	Address where the shipment can be dropped of for final delivery. The Receiver can then collect it from this Drop-off address.
return	Address	false	Address where the shipment can be returned to in case it cannot be delivered to the Receiver
carrierAgent	AddressWithAccount	false	Address of an agent that handles contact with the carrier, typically used for Ocean
notify	Address	false	Address of the party that should be notified about the shipment, typically used for Ocean or Air
shippingLocation	Address	false	Address that is responsible for ordering the shipment
neutralSender	Address	false	Address 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

Name	Type	Required	Description
companyName	string	false	Name of the company, for B2C this can be left empty
addressLine1	string	true	Street name / PO Box
addressLine2	string	false	Apartment, suite, unit, building floor etc.
addressLine3	string	false	Additional address line for extra details
streetNumber	string	false	Street/house number to identify a specific building or apartment in a street
city	string	false	City of address
stateCode	string	false	State code used primarily for US, Canada, Italy
postCode	string	false	Postcode/zipcode
countryCode	CountryCode	true	2-digit ISO-3166 Country code
vat	string	false	Value Added Tax identifier
eori	string	false	Economic Operators Registration and Identification
contactName	string	false	Name of contact person
contactPhone	string	false	Phone number of contact person
contactEmail	string(email)	false	Email address of contact person
carrierAccountReference	string	false	Account number known/given by the carrier for this address

Address

shipment > addresses > various

Name	Type	Required	Description
companyName	string	false	Name of the company, for B2C this can be left empty
addressLine1	string	true	Street name / PO Box
addressLine2	string	false	Apartment, suite, unit, building floor etc.
addressLine3	string	false	Additional address line for extra details
streetNumber	string	false	Street/house number to identify a specific building or apartment in a street
city	string	false	City of address
stateCode	string	false	State code used primarily for US, Canada, Italy
postCode	string	false	Postcode/zipcode
countryCode	CountryCode	true	2-digit ISO-3166 Country code
vat	string	false	Value Added Tax identifier
eori	string	false	Economic Operators Registration and Identification
contactName	string	false	Name of contact person
contactPhone	string	false	Phone number of contact person
contactEmail	string(email)	false	Email 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.

Name	Type	Required	Description
companyName	string	false	Name of the company, for B2C this can be left empty
addressLine1	string	true	Street name / PO Box
addressLine2	string	false	Apartment, suite, unit, building floor etc.
addressLine3	string	false	Additional address line for extra details
streetNumber	string	false	Street/house number to identify a specific building or apartment in a street
city	string	false	City of address
stateCode	string	false	State code used primarily for US, Canada, Italy
postCode	string	false	Postcode/zipcode
countryCode	CountryCode	true	2-digit ISO-3166 Country code
vat	string	false	Value Added Tax identifier
eori	string	false	Economic Operators Registration and Identification
contactName	string	false	Name of contact person
contactPhone	string	false	Phone number of contact person
contactEmail	string(email)	false	Email address of contact person
carrierAssignedAddressId	string	false	Identifier by which the carrier identifies the drop-off location, the former DropOffId Use this in combination with ServiceOptions.HoldForPickup

Amount

Monetary amount container

Name	Type	Required	Description
value	number(double)	true	The value of the monetary amount in the given currency
currencyCode	string	true	3-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

Name	Type	Required	Description
pickup	container	true	Date range regarding the pickup/collection moment
pickup\start	dateTime	true	Start DateTime of range. NOTE: Time zone specification is mandatory
pickup\end	dateTime	false	End DateTime of range. NOTE: Time zone specification is mandatory
delivery	container	false	Date range regarding the delivery moment
delivery\start	dateTime	true	Start DateTime of range. NOTE: Time zone specification is not allowed
delivery\end	dateTime	false	End DateTime of range. NOTE: Time zone specification is not allowed
delivery\fixed	Boolean	false	Is the date range a fixed time
delivery\onlySaturday	Boolean	false	Is this date range an only-saturday window

Incoterms

shipment > incoterms

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

Name	Type	Required	Description
scope	string	true	Describes the scope of the incoterm Allowed values: -`doorToDoor` -`doorToPort` -`portToDoor` -`portToPort`
incoterm	string	true	Any of the Incoterms as released in 2000,2010,2020 Values: `exw`, `fca`, `cpt`, `cip`, `dat`, `dap`, `ddp`, `ddu`, `cif`, `fob`, `dpu`, `fas`, `cfr`
place	string	false	The Named Place that applies to the incoterm
version	string	true	The International Chamber of Commerce (ICC) releases updates periodically, indicate which version of the release is being applied Values: `2000`, `2010`, `2020`

ServiceOptions

shipment > serviceOptions

Name	Type	Required	Description
allowDeliveryToNeighbour	boolean	false	Carrier is allowed to deliver the shipment to the neighbour
appointmentForDelivery	boolean	false	Carrier has to contact the Receiver to make an appointment for delivering the shipment
cargoArrangement	string	false	Used in Air booking form. Values: `pickup`, `selfDelivery`
cargoClix	boolean	false	Indicate if carriers should use the CargoClix platform to make an appointment
cashOnDelivery	container	false	Receiver to pay the transportation company for the goods upon delivery
cashOnDelivery\value	decimal	true	Cash on delivery amount
cashOnDelivery\currencyCode	string	true	3-digit ISO-4217 currency code. Currency codes based on ISO 4217, see wikipedia
cashOnDelivery\type	string	true	Cash on Delivery type that indicates how the payment should be handled Values: `cash`, `cheque`, `draft`, `moneyOrder`, `cashierCheque`
constructionSite	boolean	false	Ship to address ia a construction site
containsLithiumBatteries	boolean	false	Set to true if the shipment contains Lithium Batteries
customsClearance	boolean	false	If 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.
deliveryInside	boolean	false	Shipment has to be delivered inside a building to a specific room
documentService	container	false	Used Ocean and Air booking form.
documentService\serviceCode	string	true	Code indicating how the document shall be delivered to the forwarder Values: `original`, `house`, `telex`, `forwardsCargoReceipt`, `pickup`
documentService\date	dateTime	false	Date the document (air booking form) is available for collection by the carrier if ServiceCode=Pickup. NOTE: Time zone specification is mandatory.
dryIceAudit	boolean	false	Carrier is expected to verify if Dry Ice is in correct shape during the transportation process
equipmentTemperature	string	false	Describes the temperature under which the shipment should be transported in case of temperature sensitive goods. Values: `ambient`, `cooled`, `frozen`, `dryIceReplenishment`, `cryo`
fragile	boolean	false	Indicates if the shipment contains Fragile goods
holdForPickup	boolean	false	Set to True in combination with Drop off Address, this is used for carrier services like “hold at depot”
liftGate	container	false	Indicator if a liftGate is required for pickup or delivery
liftGate\collection	boolean	false	Indicator if a liftGate is required for pickup
liftGate\delivery	boolean	false	Indicator if a liftGate is required for delivery
lockerDelivery	container	false	Container to indicate details in case delivery should be made into locker
lockerDelivery\locationCode	string	false	Code that identifies the physical location of the locker
lockerDelivery\lockerReference	string	true	Reference that uniquely identifies a locker at a given location
lockerDelivery\entryCode	string	false	Entry code to access the Locker
lockerDelivery\providerName	string	false	Name of the provider who services the Locker
neutralDelivery	boolean	false	true = 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
photoAtDelivery	boolean	false	Carrier is requested to make a photo of the package upon delivery
preAdviceDelivery	container	false	Communication properties that can be used to pre-advice a receiver of a pending delivery
preAdviceDelivery\useEmail	boolean	false	An Email should be sent to the receiver
preAdviceDelivery\useSms	boolean	false	An SMS prior to delivery
preAdviceDelivery\usePhone	boolean	false	A call should be made prior to delivery, eg a call made by the planning department a (few) day(s) in advance
preAdviceDelivery\useDriverPhone	boolean	false	The driver should call short moments prior to delivery
residentialDelivery	boolean	false	Indicator that flags the shipment is shipped to a residential address
scannedPodRequested	boolean	false	Carrier is requested to provide a scanned image of a signed POD
signatureForDelivery	string	false	Signature upon delivery options. Valus: `none`, `consigneeOnly`, `indirect`, `adult`, `noSignatureRequired`
smallVehicle	boolean	false	Carrier should use a small vehicle for delivery
splitDutiesFromVat	boolean	false	Carrier 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

Name	Type	Required	Description
billOfLadingNumber	string	false	Can also be put in TrackingReference depends on mapping for your solution. Discuss with your implementation resource for use of this field
bookingConfirmationNumber	string	false	A confirmation number obtained from the carrier
complaintNumber	string	false	Reference number of a complaint that initiated this shipment
containerNumber	string	false	Container number in which this shipment is included
costCenter	string	false	Reference 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.
customsClearanceNumber	string	false	The reference provided by from customs (eg MRN number)
customerPurchaseOrder	string	false	Purchase order number from the Receiving Party
flightNumber	string	false	Flight number for Airfreight shipment
generalLedgerCode	string	false	GL code to be visible in reporting
loadNumber	string	false	Shipments can be grouped into loads, this number identifies which group this shipment belongs to
purchaseOrder	string	false	Purchase order number from the Sending Party
rmaNumber	string	false	Return Material Authorization reference
sapDelivery	string	false	Delivery number when using SAP
sapSalesOrder	string	false	SAP Sales order reference
shipmentNumber	string	false	Receiver Shipment number
voyage	string	false	Reference to the Voyage in Sea shipment

ShipmentInstructions

shipment > instructions

Any instructions related to the shipment

Name	Type	Required	Description
airportFrom	string	false	IATA Airport code for origin Airport
airportTo	string	false	IATA Airport code for destination Airport
branch	string	false	Branch/Plant ordering the PO.
carrierInstructions	container	false	Special instructions for the carrier
carrierInstructions\collection	string	false	Instructions for the carrier to be carried out during collection
carrierInstructions\transport	string	false	Instructions for the carrier to be carried out during transport
carrierInstructions\delivery	string	false	Instructions for the carrier to be carried out during delivery
carrierOriginDepot	string	false	Origin depot of the carrier when injecting shipments into the carrier’s network
carrierRouteCode	string	false	A carrier defined identifier that indicates which route they will use to execute the transport of the shipment
containsPackingList	boolean	false	Indicates whether or not the Packing List is enclosed with the shipment
dock	container	false	Information about the dock used for a shipment
dock\loading	string	false	Dock to be used for loading the shipment
dock\unloading	string	false	Dock to be used for unloading the shipment
justification	string	false	Free Text justifying why the specific service was chosen. Typically used when more expensive service is chosen by the user.
latestCancelDate	string(date-time)	false	Latest Date the shipment can be cancelled. This is for reference only, no system logic is used on this.. NOTE: Time zone specification is mandatory
licensePlate	string	false	LicensePlate of the trailer collecting the shipment
loadMeter	number(double)	false	If provided the load meter that overwrites any possible calculated load meter based on the handling units
modeOfTransport	string	false	Indicates the primary mode of transport for the shipment. Values: `none`, `air`, `express`, `road`, `ocean`
multipleBol	boolean	false	Indicates if multiple BillOfLading are included in the shipment
notifyEmails	container	false	Extra email addresses that should be included in shipment notifications
notifyEmails\email	string(email) 1..n occurances.	false	Email address that should be included in shipment notifications
orderingCompany	string	false	Company ordering the PO
orderType	string	false	Order type of the order in the shipment
paymentType	string	false	Type indicating how the order is paid by the Customer Values: `creditCard`, `cashOnDelivery`, `accountsReceivable`, `accountsReceivableIntercompany`
piecesOnPallets	integer(int32)	false	Total number of pieces in all pallets in the shipment
placeDocumentCollection	string	false	Used in air and ocean booking form
portFrom	string	false	Departure Sea port name
portTo	string	false	Destination Sea port name
purchaseOrderCancelDate	string(date-time)	false	Cancel date of the PO. NOTE: Time zone specification is not allowed
purchaseOrderStartDate	string(date-time)	false	Start date of the Purchase Order, this is the earliest date it can be delivered to the customer. NOTE: Time zone specification is not allowed
reasonForReturn	string	false	Free text indicating why shipment was returned
replenishment	boolean	false	Indicates if shipment is a replenishment of stock for a Distribution Center
rmaDate	string(date-time)	false	Date the Return Material Authorization was given. NOTE: Time zone specification is mandatory
vesselName	string	false	Vessel name for sea transport
woodDeclaration	boolean	false	True 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

Name	Type	Required	Description
id	integer(int32)	true	Sequential number for each invoice line, starting with 1 and incrementing with 1
externalId	string	false	Row identifier in Sender host system if required
description	string	true	Goods description
quantity	container	true	Quantity of the SKU
quantity\value	decimal	true	Number
quantity\unitOfMeasure	string	true	Values: `ea`, `kgm`, `lbr`, `ltr`, `mtr`, `cmt`, `bx`
unitCustomsValue	container	true	Customs value per unit/each. To get the line value multiply this with lines.quantity.amount
unitCustomsValue\value	decimal	true	The value of the monetary amount in the given currency
unitCustomsValue\currencyCode	string	true	Currency codes based on ISO 4217, see wikipedia
countryOfOrigin	CountryCode	false	2-digit ISO-3166 country code for the primary country that the product originates from.
itemNumber	string	true	SKU number
purchaseOrder	string	false	The PO number of the PO of the sending party, typically in drop-ship/cross-dock
purchaseOrderLineNumber	integer(int32)	false	The PO line number of the PO of the sending party
customerPurchaseOrder	string	false	The PO of the receiving party
weight	container	false	Weight of the total InvoiceLine for this ItemNumber Customs value per unit/each. To get the line value multiply this with lines.quantity.amount
weight\gross	decimal	false	Gross weight
weight\nett	decimal	false	Nett weight
lotNumber	string	false	Lot/Batch number
temperatureLoggerReference	string	false	Reference to a temperature logging device for temperature controlled goods
expirationDate	string(date-time)	false	The date the goods will expire. NOTE: Time zone specification is mandatory
customs	container	false	Section containing customs identification for the given SKU
customs\customsCode	string	false	The HS code for the goods, US government documentation: https://www.trade.gov/harmonized-system-hs-codes
customs\eccn	string	false	Export Control Classification Number, see https://www.bis.doc.gov/index.php/licensing/commerce-control-list-classification/export-control-classification-number-eccn
customs\scheduleB	string	false	The 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

Name	Type	Required	Description
sequence	integer(int32)	true	Unique sequence number per HandlingUnit, start with 1 and increment with 1 for each HandlingUnit
weight	number(double)	true	Weight of the HandlingUnit in unit of measure set in WeightUnit
length	number(double)	true	Length of HandlingUnit in unit of measure set in VolumeUnit
width	number(double)	true	Width of HandlingUnit in unit of measure set in VolumeUnit
height	number(double)	true	Height of HandlingUnit in unit of measure set in VolumeUnit
packageTypeCode	string	true	Package code identifying the packaging used, for valid codes see Handlingunit package types
isDocument	boolean	false	Indicates if the HandlingUnit is a document
description	string	false	Free text that indicates what goods are packed in the HandlingUnit
isStackable	boolean	false	Indicates if the HandlingUnit can be stacked onto or on other stackable HandlingUnits
references	container	false	Any references identifying this HandlingUnit
references\reference	string	false	Unique reference to the HandlingUnit, typically a packageId or SSCC code from a WMS
references\temperatureLoggerReference	string	false	Reference to a temperature logging device for temperature controlled goods
references\trackingReference	string	false	Handling unit specific trackingReference. This is generated by Viya if desired. Tracking events on handling unit should reference this value.
references\rfidReference	string	false	This is the RFID tag number
serviceOptions	HandlingUnitServiceOptions	false	This indicates any additional service that should be applied for this handling unit
goodsItems	[GoodsItem]	false	Identifies goods inside a handlingUnit

HandlingUnitServiceOptions

shipment > handlingUnit > serviceOptions

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

Name	Type	Required	Description
additionalHandling	boolean	false	Indicates if the handling unit requires additional handling
equipmentTemperature	string	false	Describes the temperature under which the shipment should be transported in case of temperature sensitive goods. Values: `ambient`, `cooled`, `frozen`, `dryIceReplenishment`, `cryo`
insuredValue	container	false	Value to be insured
insuredValue\value	decimal	true	The value of the monetary amount in the given currency
insuredValue\currencyCode	string	true	Currency codes based on ISO 4217, see wikipedia

GoodsItem

shipment > handlingUnit > goodsItems > goodsItem

Identifies goods inside a handlingUnit

Name	Type	Required	Description
itemNumber	string	true	SKU
description	string	true	Description of the SKU
quantity	container	false	Quantity of the SKU in the handlingUnit
quantity\value	decimal	true	Number
quantity\unitOfMeasure	string	true	Values: `ea`, `kgm`, `lbr`, `ltr`, `mtr`, `cmt`, `bx`
purchaseOrder	string	false	The PO number of the PO of the sending party, typically in drop-ship/cross-dock
purchaseOrderLineNumber	integer(int32)	false	The PO line number of the PO of the sending party
customerPurchaseOrder	string	false	The PO of the receiving party
weight	container	false	Weight of the total GoodsItem for this ItemNumber in unit of measure set in WeightUnit
weight\gross	decimal	false	Gross weight
weight\nett	decimal	false	Nett weight
lotNumber	string	false	Lot/Batch number
expirationDate	string(date-time)	false	The date the goods will expire. NOTE: Time zone specification is mandatory
dangerousGoods	[DangerousGoodsItem]	false	Container that holds list of dangerous goods components for the given goodsItem

DangerousGoodsItem

shipment > handlingUnit > goodsItem > dangerousGoods > dangerousGood

All properties for one dangerous goods component

Name	Type	Required	Description
type	string	true	classifies the GoodsItem on how it is regulated. If multiple regulations apply, take the highest regulated type Values: `exceptedQuantity`, `limitedQuantity`, `lithiumBatteries`, `dryIce`, `passengerAircraftOk`, `cargoAircraftOnly`, `radioActiveMaterial`
unNumber	string	false	The UN number or DOT number, eg UN3313
class	string	false	Dangerous goods Class, eg 3.1
properShippingName	string	false	Proper shipping name in English
technicalName	string	false	Technical name in english
packingGroup	string	false	Packing group. Eg I, II or III
quantity	container	false	Quantity In relation to UnitOfMeasure (e.g. if UnitOfMeasure = LTR and quantity = 0.1 - > item contains 0.1 Liter of Dangerous goods
quantity\value	decimal	true	Number
quantity\unitOfMeasure	string	true	Values: `ea`, `kgm`, `lbr`, `ltr`, `mtr`, `cmt`, `bx`
packingInstructions	container	false	For 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\instruction	string 1..n occurances	true	The packing instruction code: Eg: PI965, PI967 and PI970
packingCode	string	false	Code like 4G for fibreboard box
packingDescription	string	false	Package code like “Fibreboard box”
section	string	false	Used for LithiumBatteries, this is the section of the Packing instruction that applies to the Battery, eg section II or IA
subrisk	string	false	Additional risk next to its primary class.
classificationCode	string	false	See https://adrbook.com/en/2017/ADR/1.9.5.2.2 and search for example code “TFC”
transportCategory	string	false	Category used to determine hwo many units can be combined into 1 transport unit
tunnelRestrictionCode	string	false	Code that indicates if /when goods are restricted to be transported through tunnels
isEnvironmentallyHazardous	boolean	false	Is the item Environmentally Hazardous
aircraftAccessibility	string	false	How accessible is the aircraft for loading and unloading. Values: `accessible` (Goods have to stored directly accessible to cabin-crew) or `inaccessible`.
weight	container	false	Gross and net weight of the dangerous goods component in unit of measure set in WeightUnit
weight\gross	decimal	false	Gross weight
weight\nett	decimal	false	Nett weight
volume	container	false	Gross and net volume of the dangerous goods component in cubic unit of measure set in VolumeUnit
volume\gross	decimal	false	Gross Volume
volume\nett	decimal	false	Nett Volume

Accounts

shipment > accounts

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

Name	Type	Required	Description
sender	container	true	Reference for the party that booked the shipment.
sender\reference	string	true	Account reference code.
sender\relationType	string	true	Relation type of account Values: `sender`, `receiver`, `thirdParty`, `dutiesAndTaxes`
transport	container	true	Reference for the party that is responsible for paying the transport charges.
transport\reference	string	true	Account reference code.
transport\relationType	string	true	Relation type of account Values: `sender`, `receiver`, `thirdParty`, `dutiesAndTaxes`
duties	container	false	Reference for the party that is responsible for paying the duties and taxes charges.
duties\reference	string	true	Account reference code.
duties\relationType	string	true	Relation type of account Values: `sender`, `receiver`, `thirdParty`, `dutiesAndTaxes`

Documents

shipment > documents > document

Any document associated with the shipment

Name	Type	Required	Description
fileExtension	string	true	File extension eg jpeg, pdf, docx etc..
fileName	string	true
fileContent	string	true	Base64 encoded content of the file
documentType	string	true	Type 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`

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>