Skip to main content
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.

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.