> For the complete documentation index, see [llms.txt](https://docs.terminal.africa/tship/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.terminal.africa/tship/miscallaneous/reconciliation-shipment-data.md).

# Reconciliation Shipment Data

Every reconciliation record carries a shipment\_data array describing the discrepancy per shipment. This section describes that object.

| Attribute             |           | Description                                                                                                                                             |
| --------------------- | --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| actual\_weight        | *number*  | Shipment-level comparison weight, in kg; it can be chargeable weight rather than scale weight. Equal to ***declared\_weight*** on an additional charge. |
| carrierName           | *string*  | Display name of the carrier that reported the discrepancy.                                                                                              |
| currency              | *string*  | Currency of `old_shipment_cost`, `new_shipment_cost` and `exception_charge`, for example `NGN` or `USD`. Older records without this field use `NGN`.    |
| declared\_weight      | *number*  | Shipment-level weight used for the booked comparison, in kg.                                                                                            |
| exception\_charge     | *number*  | The difference being recovered for this shipment.                                                                                                       |
| new\_shipment\_cost   | *number*  | What the shipment costs at the carrier's reported weight.                                                                                               |
| old\_shipment\_cost   | *number*  | What the shipment was originally charged.                                                                                                               |
| parcel\_measurements  | *object*  | Optional saved booked and carrier measurements. Available on delivery and invoice discrepancies; see below.                                             |
| platform              | *string*  | Carrier platform the discrepancy came from e.g. ***dhl***, ***ups***.                                                                                   |
| reconciliation\_stage | *enum*    | Point in the shipment's life the discrepancy was found. One of ***processing***, ***delivery***, ***invoice***.                                         |
| shipment\_id          | *string*  | Unique reference for the shipment the discrepancy was raised against.                                                                                   |
| shipment\_number      | *string*  | Carrier tracking number for the shipment.                                                                                                               |
| tracking\_only        | *boolean* | Indicates the discrepancy is recorded for tracking only and will not be billed.                                                                         |

## Parcel measurements

`parcel_measurements` preserves the booking measurements before reconciliation and the carrier tracking or invoice measurements used to explain the discrepancy. It is available on each reconciliation `shipment_data` entry, directly in `reconciliation.flagged` and `reconciliation.billed` webhook `data`, and on the records inside `reconciliation.corrected`. Connected-account discrepancy webhooks use the same object at `data.parcel_measurements`.

| Field            | Type   | Meaning                                                                                                              |
| ---------------- | ------ | -------------------------------------------------------------------------------------------------------------------- |
| `source`         | string | `delivery_tracking` or `carrier_invoice`.                                                                            |
| `observed_at`    | string | ISO 8601 timestamp when the measurement snapshot was captured.                                                       |
| `dimension_unit` | string | `cm`; all dimensions are normalized to centimetres.                                                                  |
| `weight_unit`    | string | `kg`; all weights are normalized to kilograms.                                                                       |
| `booked`         | array  | Original booked parcels. Each entry includes `parcel_number`, `parcel_id` and the measurement fields below.          |
| `carrier`        | array  | Carrier piece measurements. Each entry includes `parcel_number`, `tracking_number` and the measurement fields below. |

Each entry in `booked` and `carrier` contains:

| Field               | Type           | Meaning                                                                                                                                                                            |
| ------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `parcel_number`     | integer        | One-based position within this list. It does not identify a matching entry in the other list.                                                                                      |
| `parcel_id`         | string or null | Terminal parcel reference, present on booked entries.                                                                                                                              |
| `tracking_number`   | string or null | Carrier tracking or piece reference, present on carrier entries.                                                                                                                   |
| `dimensions`        | object or null | `length`, `width` and `height` in cm. The entire object is `null` when a complete valid dimension set is unavailable.                                                              |
| `physical_weight`   | number or null | Physical weight from the booking, carrier tracking, or invoice source, in kg.                                                                                                      |
| `volumetric_weight` | number or null | Volumetric weight in kg. Booked and FedEx tracking values use `length × width × height / 5000`; DHL uses its reported value.                                                       |
| `chargeable_weight` | number or null | Per-parcel comparison weight, normally the larger of physical and volumetric weight, with carrier packaging rules applied. It can differ from the rounded shipment billing weight. |

The two lists are independent. Do not match booked and carrier parcels by array index or `parcel_number`. Missing identifiers and measurements are `null`; the snapshot itself is optional. Invoice snapshots can have an empty `carrier` list when only invoice totals are available. Existing records are not automatically backfilled.

A `delivery_tracking` snapshot records a tracking observation; a `carrier_invoice` snapshot preserves invoice evidence and any tracking measurements used to fill gaps. A billed or corrected record can retain an earlier observation, so use `observed_at` and the record's current pricing fields for their respective purposes. The correction does not rewrite the earlier tracking measurements.

## Invoice discrepancies

When invoice reconciliation detects a billable weight discrepancy, it saves a `carrier_invoice` snapshot before creating the reconciliation or sending its notifications. The scheduled invoice runner, staff invoice runs, and manual invoice reconciliation share this enrichment. Existing review gates, pricing, billing, and duplicate detection still apply.

Printed invoice measurements take precedence. When measurements are incomplete, DHL and FedEx tracking are queried with the invoice waybill (or the shipment waybill for manual runs). The lookup has a ten-second deadline. An error, missing measurement, or unsupported carrier does not block reconciliation: unknown measurements remain `null`. A complete one-piece invoice needs no tracking lookup. Shippo reweigh adjustments preserve the booked measurements and invoice billed weight; their tracking enrichment is currently unsupported.

The invoice's billed weight remains the input to pricing. Tracking weights never replace it. The original booking is captured before pricing rewrites its working parcel weights.

```json
{
  "parcel_measurements": {
    "source": "carrier_invoice",
    "observed_at": "2026-11-11T10:39:48.155Z",
    "dimension_unit": "cm",
    "weight_unit": "kg",
    "booked": [{
      "parcel_number": 1,
      "parcel_id": "PC-EXAMPLE",
      "dimensions": { "length": 20, "width": 20, "height": 10 },
      "physical_weight": 1.5,
      "volumetric_weight": 0.8,
      "chargeable_weight": 1.5
    }],
    "carrier": [{
      "parcel_number": 1,
      "tracking_number": "CARRIER-PIECE-EXAMPLE",
      "dimensions": { "length": 19, "width": 28, "height": 13 },
      "physical_weight": 1.62,
      "volumetric_weight": 1.38,
      "chargeable_weight": 2,
      "sources": {
        "dimensions": "delivery_tracking",
        "physical_weight": "carrier_invoice",
        "volumetric_weight": "carrier_invoice",
        "chargeable_weight": "carrier_invoice"
      }
    }],
    "invoice": {
      "observed_at": "2026-11-11T07:00:00.000Z",
      "piece_count": 1,
      "dimensions": null,
      "physical_weight": 1.62,
      "volumetric_weight": 1.38,
      "chargeable_weight": 2
    },
    "tracking": {
      "status": "available",
      "observed_at": "2026-11-11T10:39:49.952Z"
    }
  }
}
```

`invoice` contains consignment totals from the invoice; its timestamp is when the invoice record was captured. Dimensions are exposed there only for an explicitly single-piece invoice. `tracking.observed_at` records when the lookup completed, and `tracking.status` is `available`, `unavailable`, `unsupported`, or `not_needed`. Availability means tracking supplied at least one usable measurement, not that all fields are complete. Each carrier field's `sources` entry identifies its evidence source, or is `null` when unavailable. These additions are specific to `carrier_invoice` snapshots; delivery snapshots retain their existing shape.

For a one-piece shipment, available invoice measurements and the billed weight appear in `carrier[0]`; tracking fills the gaps. For multiple pieces, invoice totals remain in `invoice` and are never distributed among the carrier pieces. `carrier` can be empty when no piece measurements are available. Emails show these invoice totals separately. No dimensions are inferred from volumetric weight, and invoice weights without explicit units remain unknown.

For complete webhook examples, see [Reconciliation payloads](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/reconciliation.md) and [Connected-account weight discrepancy detection](https://docs.terminal.africa/tship/miscallaneous/sample-webhook-event-payloads/shipment.md#connected-account-weight-discrepancy-detection).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

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

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.terminal.africa/tship/miscallaneous/reconciliation-shipment-data.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.
