Custody is cash advanced to a person — typically a clearance representative — so they can pay port fees, customs charges and similar costs on the spot. It is a two-stage process: you advance an estimated amount, and afterwards you reconcile it against what was actually spent.
This is one of the few places in the system where money leaves the business before the cost is known, which is why the reconciliation step is not optional.
Raising a request
Expenses → Custody payment requests → Create.
| Field | Notes |
|---|---|
| Custody type | The kind of custody. This determines which other fields you see. |
| Representative | The person receiving the cash. |
| Currency | The currency being advanced. |
| Lines | The individual fees expected. |
| Custody total | The total advanced. |
Custody types shape the form
The custody type is chosen first because it configures the rest of the form. Different kinds of custody need different context — one might ask for shipping type, shipment type and shipment; another for a vessel, voyage, master bill of lading or container.
If a field you expect is missing, the custody type is wrong. Change it rather than working around it.
The custody type must be active: an inactive one is refused with "Custody type … not found or inactive".
Its configured fields are genuinely required, at two levels, and the message names the field and the type:
- Request level — "… is required for custody type …"
- Every line — "… is required on each line for custody type …"
The per-line requirement is the one that catches people on a long request: one line missing a container or voyage blocks the whole submission.
The lines must add up
The total of the lines must equal the custody total — "New lines total must be equal to custody total". You cannot advance a request whose parts do not sum to the whole.
Lines
Each line is one expected fee:
| Field | Notes |
|---|---|
| Fee name | What the payment is for. |
| Fee value | The estimated amount. |
| (type-specific fields) | Vessel, voyage, master B/L, container, master shipment — whichever the custody type asks for. |
Name fees the way the receipt will name them. The representative comes back with documents, and reconciliation is much faster when the line and the receipt say the same thing.
Status
| Status | Meaning |
|---|---|
| Pending | Raised, not yet processed. |
| Processed | Cash advanced. |
| Reconciled | Actual spend recorded against the estimate. |
| Submitted | Sent onward for approval. |
| Paid | Settled. |
| Rejected | Declined. |
Reconciliation
Once the representative reports back, open the request and Reconcile.
For each line you record the actual amount alongside the estimated fee value, and the system holds the difference. The reconciliation as a whole carries an actual total against the custody total.
Reconciliation line types
A reconciled line records what the spend actually turned into:
- Vendor invoice — the payment corresponds to a supplier invoice, and the line names the vendor and the vendor invoice. See Vendor invoices.
- Payment request — the payment corresponds to a payment request.
There is also an empty reconcile marker for a line where nothing was spent. This is not a convenience — it is the only alternative to naming an invoice:
Every line that is not marked empty-reconcile must name a vendor invoice — "Each line that is not empty reconcile must have vendorInvoiceId".
So a fee that did not arise must be explicitly marked as such. A silent zero is not accepted, which is exactly the right behaviour: it forces the distinction between "nothing was spent" and "we have not looked yet".
The three checks on a vendor invoice line
| Rule | Refusal |
|---|---|
| The actual amount must equal the vendor invoice total | Actual amount (…) must be equal to vendor invoice total amount (…) for invoice … |
| The invoice must not already be claimed elsewhere | Vendor invoice already used in another custody payment request line with id … |
| The invoice type must be eligible for this custody type | Vendor invoice … is not an eligible invoice type for this custody type |
The first is strict equality against the whole invoice. A custody line cannot reconcile against part of a vendor invoice — if a representative paid half of a supplier's bill in cash, the invoice needs splitting on the supplier side rather than partly reconciling here.
The second prevents the same supplier cost being recovered twice through two custody requests, which is the classic way cash reconciliation goes wrong.
Status guards
Actions check the current status, and the messages say so plainly: "Custody payment request is not pending" and "Custody payment request is not submitted". If an action is unavailable, look at the status before anything else.
Why the difference column matters
The gap between estimate and actual is the point of the whole exercise. Consistently under-estimating means representatives run short and jobs stall; consistently over-estimating means cash sits outside the business.
Review differences by fee name over time. A fee that is always out by the same margin is an estimate that should be corrected, not a surprise to be absorbed each month.
Practical advice
- Reconcile promptly. Receipts get lost, and a representative's recollection of a payment made three weeks ago is not evidence.
- Never advance further custody to a representative with an unreconciled request outstanding. That is how untracked cash accumulates.
- Attach the documentation. The reconciliation is a financial record and will be looked at again.
- Match the line to a vendor invoice where one exists. It closes the loop between cash out and cost recorded, and stops the same cost being recognised twice.
Last updated 9 September 2026