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

# Bill-later lessons

> Read bill-later lesson billing items, change prices and settle lessons with credits through MCP.

Enable the `lesson_billing` module on a company or coach connection. It requires
the company's bill-later lesson feature and the coach's current finance
permissions. Select each write action the connection needs.

| Tool | Use |
| - | - |
| `list_booking_payment_attention` | List bookings across members by booking start and payment category. Use `bill_later` for outstanding bill-later bookings or `pending_credits` for credit deductions that are due. |
| `list_lesson_billing_items` | Find a client's items by `clientId` and inclusive service dates `dateFrom` and `dateTo` (YYYY-MM-DD, up to 92 days apart). The filter uses the stored billing service date. Filter by `status` and page through results. Requires company-wide finance visibility. |
| `get_lesson_billing_item` | Read one item by `itemId`. The result includes its price, status and any booking, invoice or credit-settlement links. |
| `list_lesson_billing_credit_options` | Preview eligible credit packs and memberships for one `Open` item by `itemId`. Returns the required credits and estimated remaining total across the source's active allocations. Page with `page` and `limit` (default 25, maximum 50) until `hasMore` is false. Requires lesson settlement permission. |
| `update_lesson_billing_item_price` | Set `unitPriceInclVat` for one `Open` item. The quantity and VAT rate are preserved. Requires price update permission. |
| `settle_lesson_billing_with_credits` | Deduct credits from the selected `clientProductId` and settle one `Open` item. Requires lesson settlement permission. |

## Review outstanding booking payments

Call `list_booking_payment_attention` with `kind` and either `bookingId`
for one booking or `dateFrom` and `dateTo` for a company-wide list.
The inclusive range can span up to 92 days. Send offset-aware timestamps to
match the company’s local dates. Each call lists one category and requires
company-wide access. The default page has 25 bookings and the maximum is 50.
Pass `nextCursor` as `cursor` with the same category, booking filter and
date range until `hasMore` is false. Start a fresh query if the filters change.
The cursor keeps the original due-date cutoff while each page reads current
booking and billing statuses.
If the tool reaches its query budget, retry the same cursor after the supplied
delay. For a query timeout, shorten the date range and start a fresh query.
The `nextAction` field suggests a check or identifies what the booking is
waiting for.

* `bill_later` includes scheduled and open lessons, invoicing in progress,
  failed billing and bookings with a missing billing item. Upcoming recurring
  bookings can be scheduled before a billing item exists. A `Missing` item
  needs review. Use the credit-options tool when `billingStatus` is
  `Open`. Invoiced, settled and voided items are outside this queue.
* `pending_credits` includes due after-lesson deductions. The result includes
  the recorded wait reason and attempt date when available.
  `blocked_by_older_booking` means the older deduction is handled first.

For example, ask “Which bookings this week are still marked bill later?” or
“Which credit deductions are due, and which are waiting behind older bookings?”

## Confirm a credit settlement

1. Read the item and preview its eligible credit sources.
2. Show the coach the lesson, the selected membership or credit pack, the
   credits to deduct and the estimated total balance after deduction. Ask the coach to confirm.
3. Call `settle_lesson_billing_with_credits` with `itemId`, the selected
   `clientProductId`, a `reason`, `userConfirmed: true` and a unique
   `idempotencyKey`.

Settlement checks the credit source and balance again before deducting credits.
The result shows the settled item and the linked credit mutation. If the item
has already been settled or its source is no longer eligible, refresh the item
and options.

Price changes also require the coach's explicit confirmation, a reason and an
idempotency key. Reuse the key when retrying the same confirmed request.
If the price change was already applied and its original response is
unavailable, the tool returns the current item with `recovered: true`.
If a price change returns `LESSON_BILLING_ITEM_CHANGED`, refresh the item
before confirming a new change.

## Generate invoices for selected lessons

Call `preview_lesson_billing_invoices` with 1–25 selected open item IDs.
Review the invoice groups, currencies, amounts, and blocking reasons.
After confirmation, pass the same item IDs and all four preview hashes
(`itemHash`, `totalsHash`, `paymentContextHash`, and `itemDetailsHash`) to
`generate_lesson_billing_invoices` with `userConfirmed: true` and a
unique idempotency key. If the preview changed, read it again and reconfirm.
This creates invoices without sending them or initiating collection.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.