Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

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 for what the records mean and how the notice window works.

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 with the shipment_id from the payload.

reconciliation.flagged

A discrepancy has been raised. It has not been billed yet.

{
    "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.

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.

A replaced correction also emits a separate reconciliation.billed for the replacement record. Use reconciliation.corrected as the authoritative signal: it is the only one that reports the reversal.

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

Sample: replaced — reversed, then re-billed at a corrected amount

You can trigger any of these events against one of your own shipments in staging with Simulate Reconciliation Webhook.

PreviousPackaging
NextRegulatory Document

Was this helpful?