Generic Data Fields

This article defines the data fields used in MachShip’s generic carrier integration formats (JSON, XML, and CSV). These field definitions apply across all three formats to ensure consistency. For format-specific implementation details and examples, see the JSON Format, XML Format, or CSV Format guides.

Manifest Structure

A manifest represents a pickup request containing one or more consignments. The manifest can be structured in two ways:

• Multi-Consignment Manifest: Multiple consignments in a single file (field: consignments array)
• Single-Line Manifest: One consignment per file (field: consignment object)

Root Level Fields

These fields apply to the entire manifest and all consignments within it:

Field	Type	Required	Description
account	String or Object	Yes	Account code for the shipping customer (applies to all consignments). Can be simple string (“ACMEFRT”) or object with accountCode field
payingAccount	String	No	Account code for carrier billing/payment if different from sender account
despatchDateTime	String (ISO 8601 date)	Yes	Date of despatch in YYYY-MM-DD format (local time)
pickupDateTime	String (ISO 8601 datetime)	Yes	Scheduled pickup date and time (local time)
pickupClosingDateTime	String (ISO 8601 datetime)	Yes	Latest acceptable pickup time (local time)
timeSlot	String	No	Preferred pickup/delivery time window (e.g., “9am-12pm”, “Before 5pm”). Format depends on carrier requirements
pickupAddress	Object	Yes	Common pickup location for all consignments
pickupRequired	Boolean	No	Indicates whether carrier pickup is required (true) or goods will be dropped off (false). Default: true
specialInstructions	String	No	Special handling or pickup instructions for entire manifest
dgsDeclaration	Boolean	Yes	Indicates if ANY consignment contains Dangerous Goods
consignments	Array	Yes*	Array of consignments (multi-consignment format)
consignment	Object	Yes*	Single consignment object (single-line format)

* Use either consignments array OR consignment object, not both

Address Object Fields

Used for both pickupAddress and toLocation:

Field	Type	Required	Description
name	String	Yes	Company or business name
contact	String	Yes	Contact person name
phone	String	Yes	Contact phone number (Australian format)
email	String	No	Contact email address
addressLine1	String	Yes	Primary street address
addressLine2	String	No	Secondary address line (suite, unit, etc.)
suburb	String	Yes	Suburb/locality
postcode	String	Yes	Australian postcode (4 digits)
state	String	Yes	Full state name (e.g., “Victoria”, “New South Wales”)
stateCode	String	Yes	State abbreviation code: NSW, VIC, QLD, SA, WA, TAS, NT, ACT

Consignment Fields

Each consignment represents a shipment to a specific destination:

Field	Type	Required	Description
reference	String	Yes	Unique carrier consignment identifier
service	String	Yes	Service level code (e.g., PEXP = Premium Express)
extraReferences	Object	No	Additional reference numbers for tracking
toLocation	Object	Yes	Receiver/delivery location details
specialInstructions	String	No	Consignment-specific delivery instructions
totalWeight	Number	No	Total weight for entire consignment in kilograms (calculated field)
totalVolume	Number	No	Total volume for entire consignment in cubic meters (calculated field)
totalCubic	Number	No	Total cubic measurement for entire consignment in cubic meters (calculated field)
palletTypes	Object	No	Pallet exchange information containing CHEP, LOSCAM, and PLAIN counts for this consignment
items	Array	Yes	List of items in this consignment

Extra References Object

Field	Type	Description
carrierConsignmentReference	String	Carrier’s internal consignment reference
customerReference	String	Customer’s primary reference number
customerReference2	String	Customer’s secondary reference (can contain multiple space-separated values)

Item Fields

Each item represents a physical package/pallet in the consignment:

Field	Type	Required	Description	UOM
itemType	String	Yes	Type of packaging (e.g., “Pallet”, “Carton”, “Crate”)	N/A
name	String	Yes	Item identifier or description	N/A
sku	String	No	Stock keeping unit / product code	N/A
quantity	Integer	Yes	Number of units of this item	Units
height	Number	Yes	Height of item	Centimeters (cm)
length	Number	Yes	Length of item	Centimeters (cm)
width	Number	Yes	Width of item	Centimeters (cm)
weight	Number	Yes	Weight of item	Kilograms (kg)
volume	Number	No	Volume of item (calculated field)	Cubic meters (m³)
cubic	Number	No	Cubic measurement of item (calculated field)	Cubic meters (m³)
Barcode	Array	No	Array of barcode objects – MUST match quantity count	N/A
carrierItemTypeName	String	No	Carrier’s description for this item type (e.g., “Standard Pallet”, “Oversized Carton”). Derived from carrier’s item type configuration	N/A
carrierItemTypeAbbreviation	String	No	Carrier’s abbreviated code for this item type (e.g., “SPAL”, “OCAR”). Derived from carrier’s item type configuration	N/A
palletTypes	Object	No	Pallet exchange information containing CHEP, LOSCAM, and PLAIN counts (moved from item level – this was incorrectly documented earlier)	N/A
consignmentItemDgItems	Array	No	Dangerous Goods declarations (required if item contains DG)	N/A

Barcode Count Rule

Critical: The number of barcode objects in the Barcode array MUST equal the quantity value:

• If quantity = 4, there must be exactly 4 barcode objects
• If quantity = 1, there must be exactly 1 barcode object

Barcode Object

Field	Type	Description
barcodeNumber	String	Carrier-generated item tracking barcode

Pallet Types Object

Optional object for specifying pallet exchange requirements:

Field	Type	Description
palletCHEP	Integer	Number of CHEP pallets for exchange
palletLOSCAM	Integer	Number of LOSCAM pallets for exchange
palletPLAIN	Integer	Number of plain (one-way) pallets

Dangerous Goods Fields

Required when an item contains Dangerous Goods. Each object in the consignmentItemDgItems array represents one DG substance:

Field	Type	Required	Description
unNumber	Integer	Yes	UN Number (e.g., “1203”)
packingGroup	String	Yes	Packing group: “I”, “II”, “III”, or “N/A”
containerType	String	Yes	Container type (see enum values below)
aggregateQuantity	Number	Yes	Total quantity of DG substance (kg or L)
isAggregateQuantityWeight	Boolean	Yes	true = kg, false = litres
numberOfContainers	Integer	Yes	Number of inner receptacles/containers
isMarinePollutant	Boolean	Yes	Marine pollutant indicator
isTemperatureControlled	Boolean	Yes	Requires temperature control
isEmptyDgContainer	Boolean	Yes	Empty uncleaned container
dgClassType	String	No	Primary DG class (see values below)
subDgClassTypes	Array[String]	No	Secondary/subsidiary hazard classes
technicalOrChemicalGroupNames	String	No	Required only when mandated by UN Number
hazchem	String	No	Hazchem code (AU: recommended, NZ: required)
dgHazchemId	Integer	No	Hazchem ID enum (use hazchem OR dgHazchemId, not both)
flashpoint	Number	No	Flashpoint temperature in °C (required for Class 3 DGs)
ProperShippingName	String	No	Official proper shipping name

Container Type Values

Drum, Carton, IBC, Pail, DemountableTank, Bottle, PressureDrum, Tube, MEGCs, Aerosol, Bag, Packaging

Packing Group Values

I, II, III, N/A Note: “N/A” is sent when a packing group does not exist for a given UN number – it will not be blank/empty.

DG Class Values

Valid DG class codes and their descriptions:

DG Class	Description
2.1	FlammableGas
2.2	OtherGas
2.3	ToxicGas
3	FlammableLiquid
4.1	FlammableSolid
4.2	SpontaneouslyCombustible
4.3	DangerousWhenWet
5.1	OxidizingAgent
5.2	OrganicPeroxide
6.1	ToxicSubstance
6.2	InfectiousSubstance
7	Radioactive
8	Corrosive
9	Miscellaneous
1.1A – 1.6N	Various Explosive subclasses

Hazchem Code Values

1W, 1X, 1Y, 1Z, 2P, 2RE, 2SE, 2T, 2TE, 2WE, 2XE, 2YE, 3W, 3WE, 3X, 3Y, 3YE, 3Z, 4W, 4WE, 4Y, ●2W, ●2WE, ●3W, ●3WE, ●2Y, ●2YE, ●3Y, ●3YE, -2, -3

numberOfContainers Calculation Rules

• Carton (containerType = “Carton”): Can be set to 1 per carton if DG is not in defined inner receptacles. If shipping multiple cartons on a pallet (e.g., 12 boxes), set to 12.
• If item quantity > 1: numberOfContainers should reflect containers per unit, NOT total. Example: quantity = 3, each has 1 drum → numberOfContainers = 1
• Other container types (Bottle, Drum, Aerosol, etc.): Must specify actual number of inner receptacles per package. Example: 1 carton containing 12 bottles → numberOfContainers = 12

Implementation Notes

• Date/Time Format: All dates and times use ISO 8601 format and represent local time at the pickup location
• Australian Addressing: Both full state names (e.g., “Victoria”) and state codes (e.g., “VIC”) are required in address objects
• Service Field: The service field contains the service code/abbreviation (e.g., “PEXP” for Priority Express, “GEN” for General, “STD” for Standard)
• Reference Fields: The reference field contains the primary consignment identifier. Additional references can be provided in extraReferences: carrierConsignmentReference, customerReference, and customerReference2
• Carrier Item Types: The carrierItemTypeName and carrierItemTypeAbbreviation fields identify the item type for carrier handling (e.g., “Carton”, “CTN”)
• Measurements: All dimensions in centimeters (cm), all weights in kilograms (kg)
• Boolean Values: Use true/false (not 1/0 or yes/no)
• Dangerous Goods: The manifest-level dgsDeclaration should be true if ANY consignment contains DG items
• Special Instructions: Can be specified at both manifest level (pickup instructions) and consignment level (delivery instructions)
• Pallet Exchange: Use palletTypes object at consignment level with palletCHEP, palletLOSCAM, and palletPLAIN fields to specify pallet exchange requirements
• Field Order: In JSON, Barcode array appears at the end of item structure after all other fields

Next Steps

For format-specific implementation details and complete examples:

• JSON Format Guide: JSON structure, syntax, and complete manifest examples
• XML Format Guide: XML structure, tags, and complete manifest examples
• CSV Format Guide: CSV structure, column headers, and row formatting

Support

For integration assistance, contact MachShip carrier support via our carrier integrations form here.