> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nyumbazetu.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Boma Yangu reports

> Allocation reports sent back to the Boma Yangu API after each TPS payment — what was delivered, how to read the queue, and how to retry a failure.

**Ownership plans → Boma Yangu Reports → `/tps/allocation-reports`**

Payments collected against a Boma Yangu tenant purchase scheme have to be reported back to the Boma
Yangu API: the scheme's own records need to know how each payment was split between principal,
interest and other components. That reporting is automatic — this console is where you confirm it
actually happened.

<Note>
  Only payments received into a **Boma Yangu collection account** generate an allocation report.
  Payments on other accounts are ordinary TPS payments and never appear here.
</Note>

## How a report is produced

<Steps>
  <Step title="A payment lands on a Boma Yangu account">
    The pay-to account identifies it as in scope.
  </Step>

  <Step title="Allocation runs">
    The payment is allocated across the contract's schedule — principal, interest, and any other
    component. See [Allocations](/guides/allocations).
  </Step>

  <Step title="A report is queued">
    The resulting split becomes an allocation report addressed to the Boma Yangu API.
  </Step>

  <Step title="The queue is drained">
    A background job submits queued reports and records the outcome against each one.
  </Step>
</Steps>

## Reading a report's status

| Status           | Meaning                                                           |
| ---------------- | ----------------------------------------------------------------- |
| **Queued**       | Created and waiting for the next submission pass.                 |
| **Processing**   | Currently being submitted.                                        |
| **Sent**         | Delivered to the API; no acknowledgement yet.                     |
| **Acknowledged** | The API confirmed receipt. This is the terminal success state.    |
| **Failed**       | Submission failed. Retryable.                                     |
| **Dead**         | Retries exhausted. Needs investigation before it will move again. |

Only **acknowledged** means the scheme's records agree with yours. **Sent** without an acknowledgement
for an extended period is worth chasing — it usually points at the far side, not at Nyumba Zetu.

## Working the queue

Filter by status and start from the failures.

<Steps>
  <Step title="Read the failure reason on the report">
    Open the report to see what the API returned. Most failures are data, not transport — a contract
    reference the scheme does not recognise, or an amount split it rejects.
  </Step>

  <Step title="Fix the cause, not the report">
    If the allocation itself was wrong, correct it in
    [Allocations](/guides/allocations) first — retrying an incorrect report just re-sends the same
    wrong figures.
  </Step>

  <Step title="Retry">
    Failed reports carry a **Retry** action. It resubmits the report as it stands.
  </Step>

  <Step title="Escalate dead reports">
    A dead report has exhausted its retries. Treat it as a data or integration problem, not a
    transient one.
  </Step>
</Steps>

<Note>
  Boma Yangu deduplicates on its side, so re-sending a report that may already have landed is safe.
  A retry cannot double-report a payment.
</Note>

## Shadow mode

The feature can run in shadow mode: reports are produced and recorded exactly as they would be, but
nothing is submitted. This is how the integration is validated against real payments before it is
switched on for an organisation. In shadow mode the console is still the right place to look — the
reports and their computed splits are real, only the delivery is withheld.

## Common problems

| Symptom                                | Cause                                                                                 |
| -------------------------------------- | ------------------------------------------------------------------------------------- |
| A payment has no report                | It was not received into a Boma Yangu collection account.                             |
| Reports stay queued                    | The submission job is not running — check [Scheduled tasks](/guides/scheduled-tasks). |
| Everything is queued and nothing sends | Shadow mode is still on for the organisation.                                         |
| Repeated failures on one contract      | A reference mismatch between the two systems, not a transport fault.                  |
| Report figures look wrong              | The underlying allocation is wrong. Fix the allocation, then retry.                   |
| Sent but never acknowledged            | Awaiting the far side; chase with the scheme rather than retrying repeatedly.         |

## Related

<Columns cols={2}>
  <Card title="TPS overview" icon="house" href="/guides/tps/overview">
    How ownership plans work end to end.
  </Card>

  <Card title="Contracts and billing" icon="file-invoice" href="/guides/tps/contracts-and-billing">
    Schedules, instalments and generation.
  </Card>

  <Card title="Allocations" icon="arrows-split-up-and-left" href="/guides/allocations">
    How a payment is split before it is reported.
  </Card>

  <Card title="Admin console" icon="shield-halved" href="/guides/admin-console">
    Platform-wide integration job queue.
  </Card>
</Columns>