Summary bills and multi-bill files

Summary bills

A summary bill covers many service points under one invoice. It is delivered as one parent statement followed by one child statement per metered service point. Each child carries parent_statement_id. The parent has statement.is_summary: true and a children block listing what it expects:

"children": {
  "expected_count": 2,
  "source": "derived",
  "delivered": [
    { "statement_id": "stt_b5e29c74-…", "account_number": "10-00001-00001",
      "service_address": "100 Example Ave, Springfield ST 00000",
      "meter_numbers": [], "current_charges": 2144.24 },
    { "statement_id": "stt_3f8c0a15-…", "account_number": "10-00002-00001",
      "service_address": "100 Example Ave, Springfield ST 00000",
      "meter_numbers": [], "current_charges": 576.68 }
  ]
}

Three rules matter when you consume one.

1. The parent can carry charges of its own. Invoice-level charges, such as an account fee, appear only on the parent. The parent's current charges are its own charges plus its children's: in the sample above, $8.50 + $2,144.24 + $576.68 = $2,729.42. Summing only the children comes up short by the parent's own charges. The parent's reconciliation.identity states the formula it was checked against.
2. Match children to your records by meter. Several children can share an account number and an address. meter_numbers is what tells them apart; it is empty for an unmetered child, such as a waste service. In children.delivered, account_number and meter_numbers are the values as printed. To key on them, normalize them the same way (letters and digits only, upper case), or use the normalized forms on the child's own statement.
3. A parent may balance only with its adjustments. Some bills print adjustments apart from the new charges and itemize them on one child. Then reconciliation.children_include_adjustments names the amount, and balanced is still true. The key appears only when it was needed.

We deliver a summary bill only when it is complete: every child the bill prints is present and the arithmetic holds. An incomplete extraction is held for review and answered with request.failed (extraction_failed), never sent in part. If a delivery fails partway through, compare expected_count with the children you hold to see what is still owed.

Several bills in one file

If a PDF holds several unrelated bills, each is delivered as its own statement: several statement.available events sharing one request_id, client_reference and document_id, none with a parent. The request is delivered only if every bill in it balances; otherwise none of it is sent and the request fails. If you can send one bill per file, do.