D2 API — Flat-file to API Field Mapping

How to use this guide

This guide maps every field in the D2 flat-file layouts to the JSON property that carries it in the D2 v2 API. It is a companion to the D2 API — Vendor Integration Guide. That guide covers authentication, endpoints, validation and the integration flow. This one answers a narrower question: "I populate field X at position N in my flat file today — where does it go in the JSON?"

Layouts covered

The layout documents are on the Paltrack Helpdesk under General → Downloads → Transmission File Layouts. Positions and lengths in this guide are taken from those versions. Payloads you receive through GetPayload have the same shape as the request bodies above.

Reading the tables

Each file type has a short Shape table showing which flat-file record becomes which JSON object. That's followed by Before you start, the points most likely to trip up a migration. Then there is one table per record, listing every field in layout order:

Each type also lists its API-only properties, meaning JSON properties with no flat-file equivalent, and a summary of what is Not in the API.

Rules that apply to every file type

• The batch header and trailer are not records in the API. The BH header values that survive become top-level properties: LocationId, BatchNumber, the file creation date and time, Provider and Version. The BT trailer's record counts and totals are not sent.
• Record-type codes are not sent. The JSON object a value sits in tells the API which record it belongs to. The same goes for the flat file's link fields that tie records together (for example a load id repeated on every record). The JSON nesting does that job, although several link fields are still accepted as properties where the tables say so.
• One file name property per payload. POFileName, PIFileName, PSFileName, MTFileName, DIFileName and LIFileName carry the file name you would have used for the flat file. Keep the same naming convention. The two-letter prefix (PO, RL, PI, PS, MT, DI, LI) matters.
• Dates and times. Where the layout splits a value into a date field and a time field, the API has one datetime property. Send datetimes in ISO 8601, for example 2026-09-30T14:05:00. Some older properties are typed string although they hold a date. The tables flag these, and ISO 8601 is recommended for them too.
• Numbers. Send JSON numbers with . as the decimal separator. There's no zero-padding, no implied decimals and no fixed width. 12.5 means 12.5, not 0001250.
• Strings. Send the value, trimmed. There's no need to pad to the layout length. The layout lengths still show the longest value receiving systems expect.
• Replaced ("old") fields. Some layouts keep a short field in its original position and add a longer replacement further along the record. In the API, send the value in the property the table points to. The Notes column says which one.
• Paltrack-internal fields. Where the layout says a field is set by Paltrack or should be left blank, it is either not in the API or can be left out. The Notes column says which.
• Pallets are identified by SSCC. Where a layout has both a pallet id and an SSCC field, the SSCC replaces the pallet id. Use the SSCC property.
• Part pallets are not accepted. For Dispatch, Intake and Mates, the PalletQuantity values for one SSCC must add up to exactly 1. For Stock they must not exceed 1: a lower total is accepted, because stock can include a broken-down pallet. See Validation in the Vendor Integration Guide.

What the API does not carry

Most layout fields have a JSON property. The main exceptions are listed under Not in the API for each type. The biggest is that the Intake API has no equivalent of the IS (summary) and EV (evaluation) records. PM (pallet movement) records are carried, in PalletMovements[] (see PI).

What changed

• 1 October 2026: Intake carries PM (pallet movement) records in PalletMovements[]. Each movement is routed on its own fields by the recipient's split rules, and a payload may carry movements only.
• 30 September 2026: First version. It reflects two rule changes released the same day. Stock accepts a PalletQuantity total below 1 per SSCC (a broken-down pallet), and Mates identifies pallets by SSCC, with PalletId now optional.

PO — Dispatch

Truck dispatches (PO) and railings (RL) are submitted with POST /v2/SubmitDispatch, with a POFileDTO request body. Recipients get the same shape back from POST /v1/GetPayload. This section maps every field of the RL/PO flat-file layout (v2.18, 17 November 2022) to its JSON property.

Shape

• One truck per payload, as in the flat file.
• Each OC becomes one Consignments[] element. It carries its own copy of the loading OL (LoadingLocation), the discharge OL it sits under (DispatchLocaton), its OK record (Container) and its OP records (Pallets[]).
• Container is a single object, not an array. Send null when the consignment has no container.
• Pallets[] has one element per pallet sequence (SSCC + SequenceNumber). Put each pallet only under its own consignment.
• Nesting replaces the flat-file record order, but the link fields are still sent: Container.DocumentNumber and Pallets[].ConsignmentNumber carry the consignment number.

Before you start

• PO and RL share this endpoint and POFileDTO. POFileName must start with PO (dispatch) or RL (railings), and the prefix decides which type the payload is. Follow the flat-file convention: POxxxyyy.zzz or RLxxxyyy.zzz.
• Send both Consignments[].DispatchLocaton.LocationCode and Consignments[].DestinationCode, with the same value, on every consignment. The destination is taken from them; if either is missing or they differ, the dispatch will not reach the right recipient. DispatchLocaton is spelt that way in the API (no "i"). A property named DispatchLocation is not read.
• Root LocationCode is the sending depot's Paltrack depot code. It is required and must be a depot registered with Paltrack, or the payload is rejected.
• Consignments[].LoadId is a string. Every other LoadId (TruckHeader, LoadingLocation, DispatchLocaton, Container, Pallets[]) is an integer. In all of them, send only the internal load id (the 6 digits after xxx- in the flat-file load_id).
• No part pallets. For each SSCC, the sum of Pallets[].PalletQuantity across all consignments must be 1 (±0.001), or the payload is rejected with PART_PALLET.
• Some properties must be present even when they have no value. Send "", not null, and do not leave them out: TruckHeader.NextType, TruckHeader.NextCode, Container.DocumentNumber, and on each pallet StackVariance, PackhouseCode, Orchard, TargetRegion, TargetCountry.
• Formats: every datetime takes ISO 8601, e.g. 2026-09-30T14:05:00, and each layout date + time pair is one property. Numbers use . as the decimal separator, with no padding. Send the same value twice where noted: ProductionId and ProductionRun, and SAECSVoyage and ExtSAECSVoyage.

BH — Batch header → POFileDTO (root)

OH — Truck header → TruckHeader

OL — Transport location → Consignments[].LoadingLocation / Consignments[].DispatchLocaton

The loading OL (seq 1, tran_type L) goes into LoadingLocation on every consignment. The discharge OL that a consignment sits under goes into that consignment's DispatchLocaton. Req applies whenever the object is sent. Send DispatchLocaton on every consignment (see Before you start).

OC — Truck document → Consignments[]

OK — Truck container → Consignments[].Container

One OK per OC. When a consignment has no container, send Container: null. Req applies whenever the object is sent.

OP — Truck pallet → Consignments[].Pallets[]

One element per pallet sequence. For each SSCC, PalletQuantity must add up to 1 across all consignments (see Before you start).

BT — Batch trailer → not in the API

The API has no trailer. Counts and totals come from the arrays themselves.

API-only properties

Not in the API

Old fields that have a newer replacement are not listed here; the Notes column gives the field to use.

• BH: indicator.
• OH: tk_date, tk_user, user_id, partner_id, mesg_no.
• OL: mesg_no.
• OC: inc_pallet, allow_code, allow_del, liner_bd, plas_cover, spoor_load, repack_flag, endorse1–endorse4, mix_cnt_pals, cons_count, pals_unstable, pals_damage, pals_sundry, mesg_no.
• OK: tk_user, in_user, in_partner.
• OP: cont_split, shift, shift_date, mesg_no, combo_pallet_id, Combo_sscc, Saftbin1, Saftbin2, Saftbin3. Mini-pallet (combo) links cannot be sent. The pallet's container and ship number have no pallet property; they come from Consignments[].Container.
• BT: the batch trailer is not in the API. No record counts or totals are sent.

PI — Intake

Cold-store intakes are submitted with POST /v2/SubmitIntake, with a PIFileDTO request body. Recipients get the same shape back from POST /v1/GetPayload. This section maps every field of the PI flat-file layout (v1.24, 17 November 2022) to its JSON property.

Shape

• The IS (summary) and EV (evaluation) records are not in the API. There is no summary or evaluation object in PIFileDTO.
• PM (pallet movement) records go in PalletMovements[] at file level, not under a document.
• Pallets sit directly under their document. The IS level between IC and IP falls away.
• Pallets[] has one element per pallet sequence (SSCC + SequenceNumber). Each element still carries DocumentNumber, Organisation, LocationCode and LoadId.
• TransferInDetails is a single object, not an array. Send null when there are no transport details.
• Send only real documents. The dummy IC records that some flat files carry before BT have no place in the API.

Before you start

• IS and EV records are not in the API. Anyone who needs fspec summaries works them out from Pallets[]. Evaluation results cannot be sent.
• Send every PM record as a PalletMovements[] element. HistoryType and SSCC are required on each. Put the SSCC after the movement in NewSSCC. Populate Organisation: movements are routed on their own fields, so a movement with a blank organisation does not reach recipients that receive by organisation.
• PIFileName is required and must follow the flat-file convention PIxxxyyy.zzz, where xxx is your network address. Paltrack uses the name to route the intake to recipients.
• Root LocationCode is required and must be a depot registered with Paltrack. LocationId is used to find the depot when LocationCode does not match directly. Send at least one document or one pallet movement. A file of movements only has an empty Documents.
• Populate Pallets[].Organisation on every pallet. Routing uses the pallet's organisation, not the document's. A pallet with a blank organisation does not reach recipients that receive by organisation. Use the same value as Documents[].Organisation.
• Pallets[].DocumentNumber must equal the parent Documents[].DocumentNumber. Pallets[].SequenceNumber is required on every pallet and must be 1 or more.
• No part pallets. Send SSCC and PalletQuantity on every pallet. For each SSCC, the sum of PalletQuantity over its sequences must be 1 (±0.001), or the payload is rejected with PART_PALLET.
• Documents[].DocumentDate and Documents[].RailDate are strings, not datetimes. Send them in ISO 8601, e.g. 2026-09-30T00:00:00. All other dates are datetime properties and also take ISO 8601; each layout date + time pair is one property. Documents[].InspectTemperature and Documents[].Batch are strings too. Always send Documents[].TransactionDate.

BH — Batch header → PIFileDTO (root)

IC — In consignment → Documents[] and Documents[].TransferInDetails

IS — In summary (fspec) → not in the API

The IS record is not in the API. There is no summary object, and none of its fields can be sent. Recipients get pallet lines only; summaries can be worked out from Documents[].Pallets[].

IP — In pallet → Documents[].Pallets[]

One element per pallet sequence, nested under its document.

EV — Evaluation → not in the API

The EV record is not in the API. Evaluation results cannot be sent.

PM — Pallet movement → PalletMovements[]

Pallet movements sit at file level, not under a document: one element per PM record. A movement is routed on its own fields, by the same split rules as pallets, so a recipient receives only the movements that match its rules. A payload can carry movements with no documents.

BT — Batch trailer → not in the API

The API has no trailer. Counts and totals come from the arrays themselves.

API-only properties

Not in the API

Old fields that have a newer replacement are not listed here; the Notes column gives the field to use.

• IS (summary): the whole record is not in the API. There is no summary object.
• EV (evaluation): the whole record is not in the API. Evaluation results cannot be sent.
• PM: Load Id, Orig Pallet id, Actual Grade, Transmission flag, Cartons Rejected, Cartons Discarded, Cartons Evaluation, Mox indicator, New Pallet ID, Pallet_id, Average temperature, Max temperature, Above hours, Mininum temperature, Below hours, Truck setting, the second Location code / Xmit flag / Tran user / Tran time / Tran date, Download, Protocol_exception_indicator.
• BT: the batch trailer is not in the API. No record counts or totals are sent.
• Dummy IC records: not applicable. Send only real documents.
• IC: load_id, location type, truck level, pro_no, full pallet, inc_pallet, endorse1–endorse4, Evaluation FROM number, Evaluation TO number, Message Number (Inspect Samples), Temperature2, Temperature3, Temperature4. The transport Pallet Quantity (pos 281) and Carton Quantity (pos 290) are sent once, at document level.
• IP: Agent, Actual Grade, Intake Point, Transmission flag, Message number, Cartons Rejected, Cartons Discarded, Cartons Evaluation, Mix indicator, Combo pallet id, Saftbin1, Saftbin2, Saftbin3, Combo_sscc, Expiry_code, Inner_pack, Inner_cartons, Protocol_exception_indicator. Mini-pallet (combo) links cannot be sent.

PS — Stock

Send a pallet-level stock file (PS) as JSON to POST /v2/SubmitStock. The request body is PSFileDTO: the BH fields sit on the root object, and each PS record is one element of StockRecords[]. GetPayload returns the same shape to recipients.

Shape

• There is no BatchHeader object. The BH fields are properties of the root object.
• StockRecords[] is a flat list with one element per pallet sequence (pallet × sequence), exactly like the PS records in the file. There is no pallet grouping or nesting.

Before you start

• PSFileName is required and must start with PS. Use the layout's naming convention, PSxxxyyy.zzz.
• Root LocationCode is required. It has no BH position: send your depot code, the same value as the PS records' Location Code. It must match a depot registered with Paltrack, otherwise the submission is rejected with UNKNOWN_DEPOT (unless LocationId is 000).
• Pallet quantity rule: for each SSCC, the sum of PalletQuantity across its sequences must not exceed 1 (±0.001), otherwise the submission is rejected with PART_PALLET. Unlike the other file types, a sum below 1 is accepted, because stock can include a pallet that has been broken down. Send SSCC on every row.
• Pallet ID (pos 3) is replaced by the SSCC (pos 289). Identify every pallet by StockRecords[].SSCC.
• TemperatureRule, Pool and StockType are not Tracing Temperature, Saftbin2 (perforation grape value) or Store_type, whatever older descriptions of these properties say. They are separate legacy stock properties with no PS layout field. Tracing Temperature, Saftbin2 and Store_type are not in the API.
• Dates are ISO 8601 datetimes. Where the layout splits a date and a time into two fields, the API carries one datetime. IntakeDate is not nullable: if you omit it, 0001-01-01T00:00:00 is forwarded.
• StockRecords[].BatchNumber is the PS Batch_no (pos 378). It is not the root BatchNumber, which is the BH batch number.

BH — Batch Header → root (PSFileDTO)