# Voyage Reference Numbering

1\. Purpose

The Voyage Reference Number is a human-readable identifier that operators use to label, search, and communicate about voyages. Because different operating companies have established their own reference conventions, Dataloy VMS supports a set of configurable numbering variants. Each variant is selected per company (or deployment) and determines how the reference string is constructed from the available voyage data.

***

### 2. Building Blocks

All variants are assembled from a small set of source fields. Understanding these fields is prerequisite to interpreting any variant formula.

| Field             | Source & Notes                                                                                                                                      |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VesselCode`      | Short alphanumeric code identifying the vessel in VMS master data.                                                                                  |
| `CompanyCode`     | Code identifying the operating company. May be numeric or alphanumeric depending on the variant.                                                    |
| `VoyageNo`        | Integer sequence number assigned to the voyage. Some variants reset this counter at the start of each calendar year; others increment continuously. |
| `VoyageStartYear` | The calendar year in which the voyage begins. Variants use either two digits (`YY`) or four digits (`YYYY`) of this value.                          |
| `ReferenceNo`     | Manually entered free-text reference. Used as a primary value in pass-through variants and as a fallback in several others.                         |
| `CpDate`          | Charter Party date. Used in Variant 16 to determine which era-specific formula applies and to extract the two-digit year component.                 |
| `ContractNo`      | COA (Contract of Affreightment) contract number. Used only in Variant 16 post-2016 logic.                                                           |
| `IsTc`            | Boolean flag indicating whether the voyage operates under a time-charter arrangement. Used only in Variant 2 to determine the TC/VC suffix.         |

**Padding notation:** Throughout this document, `VoyageNo(3)` means the voyage number zero-padded to a minimum width of 3 characters (e.g. voyage 7 becomes `007`). The width is given in parentheses.

***

### 3. Variant Summary

| Variant | Name                                         |
| ------- | -------------------------------------------- |
| 2       | Type-Year-Number with TC/VC Suffix           |
| 4       | Vessel-Dot-Year-Number                       |
| 5       | Vessel-Number (No Year)                      |
| 6       | Year-Vessel-Number                           |
| 8       | Numeric Company-Vessel-Year-Number           |
| 9       | Manual Reference (Pass-through)              |
| 11      | Vessel-Year-Number (3-digit)                 |
| 12      | Vessel-Year-Number (2-digit)                 |
| 13      | Manual Reference with Vessel-Number Fallback |
| 14      | Company-Vessel-Year-Number                   |
| 15      | Vessel-Number (Adaptive Width)               |
| 16      | COA Contract-Based (Date-Era Dependent)      |
| 17      | Vessel-Full Year-Number                      |
| 21      | Vessel-Year-Number (2-digit, Trimmed)        |
| 22      | Vessel-Year-Number (Continuous, No Reset)    |

***

### 4. Variant Reference

#### Variant 2 — Type-Year-Number with TC/VC Suffix

**Format:** `V + VesselCode + YY + VoyageNo(3) + [TC|VC]`\
**Example:** `VVESSEL25001TC`

Prefixes the reference with the letter `V`, appends a two-digit year and a zero-padded three-digit voyage number, and closes with a contract-type suffix: `TC` for time-charter voyages or `VC` for voyage-charter voyages.

| Field         | Description                                          |
| ------------- | ---------------------------------------------------- |
| `V`           | Literal prefix                                       |
| `VesselCode`  | Vessel master-data code                              |
| `YY`          | Last 2 digits of voyage start year                   |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits               |
| `TC` / `VC`   | Contract type suffix (Time Charter / Voyage Charter) |

***

#### Variant 4 — Vessel-Dot-Year-Number

**Format:** `VesselCode + '.' + YY + VoyageNo(3)`\
**Example:** `VESSEL.25001`

Combines the vessel code and voyage number with a period separator. The year component always uses two digits. The voyage number is zero-padded to three digits.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `.`           | Literal separator                      |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 5 — Vessel-Number (No Year)

**Format:** `VesselCode + VoyageNo(3)`\
**Example:** `VESSEL001`

The simplest format: vessel code immediately followed by a zero-padded three-digit voyage number, with no year component. Voyage numbering does not necessarily reset annually.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 6 — Year-Vessel-Number

**Format:** `YY + VesselCode + VoyageNo(3)`\
**Example:** `25VESSEL001`

Year-first variant: the two-digit year precedes the vessel code, followed by a zero-padded three-digit voyage number. No separator characters are used.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `YY`          | Last 2 digits of voyage start year     |
| `VesselCode`  | Vessel master-data code                |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 8 — Numeric Company-Vessel-Year-Number

**Format:** `CompanyCode(3) + VesselCode(4) + YY + VoyageNo(2)`\
**Example:** `00100012501`

All components are treated as integers and zero-padded to fixed widths. Falls back to the stored reference number if any component cannot be parsed as a number.

| Field            | Description                                              |
| ---------------- | -------------------------------------------------------- |
| `CompanyCode(3)` | Company code, parsed as integer, zero-padded to 3 digits |
| `VesselCode(4)`  | Vessel code, parsed as integer, zero-padded to 4 digits  |
| `YY`             | Last 2 digits of voyage start year                       |
| `VoyageNo(2)`    | Voyage number, zero-padded to 2 digits                   |

> ⚠ **Note:** Falls back to the manually entered reference number if vessel code or company code cannot be converted to an integer.

***

#### Variant 9 — Manual Reference (Pass-through)

**Format:** `ReferenceNo (verbatim)`\
**Example:** *(as entered)*

Returns the manually entered reference number exactly as stored, without any computed components. Used when the operator is responsible for maintaining reference uniqueness.

| Field         | Description                                           |
| ------------- | ----------------------------------------------------- |
| `ReferenceNo` | Manually entered reference number — returned verbatim |

***

#### Variant 11 — Vessel-Year-Number (3-digit)

**Format:** `VesselCode + YY + VoyageNo(3)`\
**Example:** `VESSEL25001`

Vessel code followed by a two-digit year and a zero-padded three-digit voyage number. Similar to Variant 22 but without the explicit continuous (non-resetting) voyage number sequence requirement.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

***

#### Variant 12 — Vessel-Year-Number (2-digit)

**Format:** `VesselCode + YY + VoyageNo(2)`\
**Example:** `VESSEL2501`

Identical in structure to Variant 11 but the voyage number is zero-padded to only two digits, suitable for operations where voyage counts per vessel per year are expected to remain below 100.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(2)` | Voyage number, zero-padded to 2 digits |

***

#### Variant 13 — Manual Reference with Vessel-Number Fallback

**Format:** `ReferenceNo → VesselCode + VoyageNo(3)`\
**Example:** `VESSEL001`

Prefers the manually entered reference number. Falls back to concatenating the vessel code with a zero-padded three-digit voyage number only when no manual reference exists.

| Field         | Description                                      |
| ------------- | ------------------------------------------------ |
| `ReferenceNo` | Manually entered reference (preferred, if set)   |
| `VesselCode`  | Fallback: vessel master-data code                |
| `VoyageNo(3)` | Fallback: voyage number, zero-padded to 3 digits |

> ⚠ **Note:** Fallback is used only when `ReferenceNo` is null.

***

#### Variant 14 — Company-Vessel-Year-Number

**Format:** `CompanyCode + VesselCode + YY + VoyageNo(2)`\
**Example:** `COMPVESSEL2501`

Extends Variant 12 by prepending the company code, making the reference globally unique across multiple operating companies sharing the same vessel codes.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `CompanyCode` | Company master-data code               |
| `VesselCode`  | Vessel master-data code                |
| `YY`          | Last 2 digits of voyage start year     |
| `VoyageNo(2)` | Voyage number, zero-padded to 2 digits |

***

#### Variant 15 — Vessel-Number (Adaptive Width)

**Format:** `VesselCode + VoyageNo(3 or 4)`\
**Example:** `VESSEL0023` / `VESSEL1000`

Similar to Variant 5 but dynamically adjusts the voyage number padding width: 4-digit padding is used if the voyage number itself is 4 digits long, otherwise 3-digit padding is applied.

| Field            | Description                                                        |
| ---------------- | ------------------------------------------------------------------ |
| `VesselCode`     | Vessel master-data code                                            |
| `VoyageNo(3\|4)` | Voyage number; padded to 4 digits if ≥ 1000, otherwise to 3 digits |

> ⚠ **Note:** For unallocated budget estimates (where voyage number is null), the stored reference number is returned instead.

***

#### Variant 16 — COA Contract-Based (Date-Era Dependent)

**Format:** *(Era-dependent — see below)*\
**Example:** `25000001` / `250000123456000001`

A complex variant with era-specific logic based on CP date. The CP date is sourced from TC-in data if available; otherwise from the first cargo with a non-null CP date.

| Era / Condition                     | Formula                                                    |
| ----------------------------------- | ---------------------------------------------------------- |
| Pre-2016                            | `VesselCode + VoyageNo(3)`                                 |
| Post-2016, no contract or reference | `YY + VoyageNo(5)`                                         |
| Post-2016, contract number only     | `YY + VoyageNo(5) + ContractNo + VoyageNo(5)`              |
| Post-2016, reference + contract     | `ReferenceNo[0..5] + '-' + ContractNo + '-' + VoyageNo(5)` |

> ⚠ **Note:** The year used in post-2016 references is the two-digit year of the **CP date**, not the voyage start year.

***

#### Variant 17 — Vessel-Full Year-Number

**Format:** `VesselCode + YYYY + VoyageNo(3)`\
**Example:** `VESSEL2025001`

Uses the full four-digit year rather than the two-digit abbreviation, providing unambiguous century identification.

| Field         | Description                            |
| ------------- | -------------------------------------- |
| `VesselCode`  | Vessel master-data code                |
| `YYYY`        | Full 4-digit voyage start year         |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits |

> ⚠ **Note:** Returns the stored reference number if vessel code is null.

***

#### Variant 21 — Vessel-Year-Number (2-digit, Trimmed)

**Format:** `VesselCode + YY + VoyageNo(2)`\
**Example:** `VESSEL2501`

Vessel code with two-digit year and a two-digit voyage number. Trailing whitespace from the voyage number segment is trimmed. Structurally identical to Variant 12.

| Field         | Description                                     |
| ------------- | ----------------------------------------------- |
| `VesselCode`  | Vessel master-data code                         |
| `YY`          | Last 2 digits of voyage start year              |
| `VoyageNo(2)` | Voyage number, zero-padded to 2 digits, trimmed |

***

#### Variant 22 — Vessel-Year-Number (Continuous, No Reset)

**Format:** `VesselCode + YY + VoyageNo(3)`\
**Example:** `VESSEL25001`

Structurally identical to Variant 11, but voyage numbers are **not reset at year boundaries** — they continue incrementing across years. This is the key operational distinction and must be configured correctly in the voyage numbering sequence setup.

| Field         | Description                                                                 |
| ------------- | --------------------------------------------------------------------------- |
| `VesselCode`  | Vessel master-data code                                                     |
| `YY`          | Last 2 digits of voyage start year                                          |
| `VoyageNo(3)` | Voyage number, zero-padded to 3 digits — **continuous, not reset annually** |

> ⚠ **Note:** Voyage number sequence must be configured as continuous (no annual reset) for this variant to produce correct results.

***


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dataloy.com/release-8.24/voyage-management-system/step-by-step-guides/voyages/voyage-reference-numbering.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.