School and service fee collection with invoices
Environment: Live
Bill students, members or tenants with invoices, send links and reminders, track who has paid and reconcile.
# School and service fee collection with invoices
Bill students, members or tenants with invoices, send links and reminders, track who has paid and reconcile.
## The playbook in one page
Schools, estates, clubs, clinics and utilities-style services bill people for a known amount by a known date. Invoices fit: you create one per payer, send the link, and track who has paid. The same pattern covers school fees, rent, membership dues and service charges that you bill yourself.
| Order | Endpoint | Purpose |
| --- | --- | --- |
| 1 | Create invoice | One invoice per payer, with a due date and a reference |
| 2 | SMS or WhatsApp | Send the payment link and reminders yourself |
| 3 | List invoices / Invoice status | See who has paid |
| 4 | Cancel invoice | Withdraw an invoice that should not be paid |
| 5 | List Transactions | Reconcile with the ledger |
## Step by step
1. Build the billing list from your own records: payer name, phone, amount, due date and a reference that identifies the bill (for example FEES-T1-2026-STU0042).
2. Create each invoice with Create invoice and an Idempotency-Key equal to the reference. Use items for a breakdown (tuition, books, bus) and tax if it applies. Store invoiceid and payment_link against the bill.
3. Send the payer the link with SMS (Send SMS) or WhatsApp. Put the reference and the due date in the message. The API does not send messages for you.
4. Listen for the invoice.paid webhook (verify the signature, dedupe on event_id): it arrives once when an invoice created through the API is fully paid. Match data.reference to your bill, mark it paid once and send the receipt.
5. As a safety net run a job every few minutes (or hourly) with List invoices filtered by status pending, partially_paid and overdue. It finds part payments (no webhook is sent for them) and anything a webhook missed.
6. Remind before and after the due date with your own messages. overdue invoices can still be paid.
7. A payer who pays in two parts shows partially_paid: compare amount_paid and total and ask for the rest.
8. Cancel an invoice that is no longer due (a withdrawn student, a mistake) with Cancel invoice. If it has payments you get INV18: settle that outside the invoice.
9. At the end of the day reconcile paid invoices with the wallet statement.
```curl
curl https://api.moolre.com/open/invoice/create \
-H "Content-Type: application/json" \
-H "X-API-USER: $MOOLRE_USER" \
-H "X-API-KEY: $MOOLRE_KEY" \
-H "Idempotency-Key: FEES-T1-2026-STU0042" \
-d '{
"accountnumber": "1000000000001",
"currency": "GHS",
"invoice_name": "Term 1 fees",
"customer": {
"name": "Ama Mensah",
"phone": "0240000001"
},
"items": [
{
"description": "Tuition",
"quantity": 1,
"amount": "450.00"
},
{
"description": "Bus",
"quantity": 3,
"amount": "30.00"
}
],
"due_date": "2026-12-31",
"reference": "FEES-T1-2026-STU0042",
"metadata": {
"studentId": "STU0042"
}
}'
```
- [Invoices](https://docs.moolre.com/guides/invoices)
- [SMS and WhatsApp, step by step](https://docs.moolre.com/guides/sms-whatsapp-step-by-step)
## Edge cases
| Situation | What to do |
| --- | --- |
| Creating the same invoice twice | Use the same reference and Idempotency-Key. The second call returns INV02 with the original invoice |
| A parent pays after the due date | It still works: the invoice reads overdue until paid |
| Wrong amount on an invoice | Cancel it (if unpaid) and create a new one with a new reference |
| A parent pays the wrong invoice | Handle the correction in your own records; Moolre has no transfer-between-invoices feature |
| Part payments, expiry or dashboard-created invoices | No webhook is sent for them (invoice.paid fires only when an API-created invoice is fully paid, and invoice.expired is not sent yet). The polling job finds them |
| Many invoices | Create them in a queue with a small delay, store invoiceid for each, and page through List invoices with the cursor |
## Checklist
- [ ] Each bill has a unique reference and an invoice created with it.
- [ ] You send links and reminders yourself and keep a record of what was sent.
- [ ] The invoice.paid webhook marks bills paid once; a polling job handles part payments and missed events.
- [ ] You cancel invoices that should no longer be paid.
- [ ] Receipts and reconciliation follow the statement.