> 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/sample-webhook-event-payloads/reconciliation.md). # Reconciliation Sample payloads for reconciliation.flagged, reconciliation.billed and reconciliation.corrected. These events fire when a carrier reports a weight or charge that differs from what you were billed at booking. See [Reconciliation](/tship/reconciliation.md) for what the records mean and how the notice window works. {% hint style="info" %} The payload is a **single entry from the record's `shipment_data` array** — one shipment's discrepancy — not the whole reconciliation record. To read the record itself, including totals and billing state, call [Get Reconciliation by Shipment](/tship/reconciliation/get-reconciliation-by-shipment.md) with the `shipment_id` from the payload. {% endhint %} ### reconciliation.flagged A discrepancy has been raised. It has not been billed yet. ```javascript { "event": "reconciliation.flagged", "data": { "shipment_id": "SH-40208776515", "shipment_number": "7412089553", "carrierName": "DHL Express", "platform": "dhl", "declared_weight": 2, "actual_weight": 3.5, "old_shipment_cost": 42350, "new_shipment_cost": 51720, "exception_charge": 9370, "tracking_only": false, "reconciliation_stage": "delivery" } } ``` ### reconciliation.billed The discrepancy has been charged to your wallet. A `transaction.success` event fires for the charge itself. ```javascript { "event": "reconciliation.billed", "data": { "shipment_id": "SH-40208776515", "shipment_number": "7412089553", "carrierName": "DHL Express", "platform": "dhl", "declared_weight": 2, "actual_weight": 3.5, "old_shipment_cost": 42350, "new_shipment_cost": 51720, "exception_charge": 9370, "tracking_only": false, "reconciliation_stage": "invoice" } } ``` ### reconciliation.corrected A correction takes one of two shapes, and `correction_type` tells you which without a second API call: * `voided` — the charge was reversed in full and **nothing replaced it**. `replacement` is `null`. * `replaced` — the charge was reversed and a corrected one was billed in its place. `replacement` carries that new record, with its own `reconcilliation_id` and `transaction_id`. `correction_type` describes what happened to the **record**, not to the money. A discrepancy corrected before it was ever billed is voided without a refund, because nothing was taken — `was_charged` and `amount_refunded` are what tell you about the money. {% hint style="info" %} A `replaced` correction also emits a separate [`reconciliation.billed`](/tship/miscallaneous/webhook-events.md) for the replacement record. Use `reconciliation.corrected` as the authoritative signal: it is the only one that reports the reversal. {% endhint %} | Attribute | | Description | | ------------------------- | --------- | ------------------------------------------------------------------------------------------ | | amount\_refunded | *number* | What went back to your wallet. ***0*** when the original was never charged. | | corrected\_at | *string* | ISO 8601 timestamp of the correction. | | corrected\_charge | *number* | What you owe after the correction. ***0*** on a ***voided*** correction. | | correction\_type | *string* | ***voided*** or ***replaced***. | | currency | *string* | Always ***NGN***. | | original\_charge | *number* | What the reconciliation charged before the correction. | | rebill\_transaction\_id | *string* | Wallet transaction for the corrected charge. ***null*** on a ***voided*** correction. | | reconciliation | *object* | The corrected record, now voided. Same shape as the Reconciliation object. | | reconcilliation\_id | *string* | Unique id of the record that was corrected. | | replacement | *object* | The record billed in its place, or ***null*** on a ***voided*** correction. | | reversal\_transaction\_id | *string* | Wallet transaction that returned the original charge. ***null*** when nothing was charged. | | shipment\_id | *string* | Unique shipment id the correction applies to. | | was\_charged | *boolean* | Whether the original charge had actually been debited. | Note the double-l spelling in `reconcilliation_id`. That is the real field name and matches the rest of the docs. ### Sample: `voided` — reversed in full ```javascript { "event": "reconciliation.corrected", "data": { "shipment_id": "SH-40208776515", "reconcilliation_id": "RC-8TQK2M4XZP71VBDR", "correction_type": "voided", "currency": "NGN", "original_charge": 9370, "corrected_charge": 0, "amount_refunded": 9370, "was_charged": true, "reversal_transaction_id": "TRX-R4M8XP02", "rebill_transaction_id": null, "corrected_at": "2026-09-22T10:31:44.000Z", "reconciliation": { "reconcilliation_id": "RC-8TQK2M4XZP71VBDR", "shipment_id": "SH-40208776515", "platform": "dhl", "reconciliation_stage": "delivery", "total_old_shipment_cost": 42350, "total_new_shipment_cost": 51720, "total_exception_charge": 9370, "charge_type": "weight", "charge_after": "2026-09-10T00:00:00.000Z", "descripancy_challenged": true, "billing_skipped": true, "is_charged": true, "charged_at": "2026-09-10T09:00:00.000Z", "transaction_id": "TRX-9F2K10DQ", "reversal_transaction_id": "TRX-R4M8XP02", "voided": true, "voided_at": "2026-09-22T10:31:44.000Z", "created_at": "2026-09-03T08:00:00.000Z", "updated_at": "2026-09-22T10:31:44.000Z", "shipment_data": [ { "shipment_id": "SH-40208776515", "shipment_number": "7412089553", "carrierName": "DHL Express", "platform": "dhl", "declared_weight": 2, "actual_weight": 3.5, "old_shipment_cost": 42350, "new_shipment_cost": 51720, "exception_charge": 9370, "tracking_only": false, "reconciliation_stage": "delivery" } ] }, "replacement": null } } ``` ### Sample: `replaced` — reversed, then re-billed at a corrected amount ```javascript { "event": "reconciliation.corrected", "data": { "shipment_id": "SH-40208776515", "reconcilliation_id": "RC-8TQK2M4XZP71VBDR", "correction_type": "replaced", "currency": "NGN", "original_charge": 9370, "corrected_charge": 3120, "amount_refunded": 6250, "was_charged": true, "reversal_transaction_id": "TRX-R4M8XP02", "rebill_transaction_id": "TRX-B7QW31LM", "corrected_at": "2026-09-22T10:31:44.000Z", "reconciliation": { "reconcilliation_id": "RC-8TQK2M4XZP71VBDR", "shipment_id": "SH-40208776515", "platform": "dhl", "reconciliation_stage": "delivery", "total_old_shipment_cost": 42350, "total_new_shipment_cost": 51720, "total_exception_charge": 9370, "charge_type": "weight", "charge_after": "2026-09-10T00:00:00.000Z", "descripancy_challenged": true, "billing_skipped": true, "is_charged": true, "charged_at": "2026-09-10T09:00:00.000Z", "transaction_id": "TRX-9F2K10DQ", "reversal_transaction_id": "TRX-R4M8XP02", "voided": true, "voided_at": "2026-09-22T10:31:44.000Z", "created_at": "2026-09-03T08:00:00.000Z", "updated_at": "2026-09-22T10:31:44.000Z", "shipment_data": [ { "shipment_id": "SH-40208776515", "shipment_number": "7412089553", "carrierName": "DHL Express", "platform": "dhl", "declared_weight": 2, "actual_weight": 3.5, "old_shipment_cost": 42350, "new_shipment_cost": 51720, "exception_charge": 9370, "tracking_only": false, "reconciliation_stage": "delivery" } ] }, "replacement": { "reconcilliation_id": "RC-K91MDX2QW7ZA4TVB", "shipment_id": "SH-40208776515", "platform": "dhl", "reconciliation_stage": "delivery", "total_old_shipment_cost": 42350, "total_new_shipment_cost": 45470, "total_exception_charge": 3120, "charge_type": "weight", "charge_after": "2026-09-10T00:00:00.000Z", "descripancy_challenged": false, "billing_skipped": false, "is_charged": true, "charged_at": "2026-09-22T10:31:46.000Z", "transaction_id": "TRX-B7QW31LM", "reversal_transaction_id": "", "voided": false, "voided_at": null, "created_at": "2026-09-03T08:00:00.000Z", "updated_at": "2026-09-22T10:31:46.000Z", "shipment_data": [ { "shipment_id": "SH-40208776515", "shipment_number": "7412089553", "carrierName": "DHL Express", "platform": "dhl", "declared_weight": 2, "actual_weight": 2.4, "old_shipment_cost": 42350, "new_shipment_cost": 45470, "exception_charge": 3120, "tracking_only": false, "reconciliation_stage": "delivery" } ] } } } ``` {% hint style="info" %} You can trigger any of these events against one of your own shipments in staging with [Simulate Reconciliation Webhook](/tship/reconciliation/simulate-reconciliation-webhook.md). {% endhint %} --- # 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/sample-webhook-event-payloads/reconciliation.md?ask=&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.