Moolre Documentation

Use Cases

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.

OrderEndpointPurpose
1Create invoiceOne invoice per payer, with a due date and a reference
2SMS or WhatsAppSend the payment link and reminders yourself
3List invoices / Invoice statusSee who has paid
4Cancel invoiceWithdraw an invoice that should not be paid
5List TransactionsReconcile 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 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"    }  }'

Edge cases

SituationWhat to do
Creating the same invoice twiceUse the same reference and Idempotency-Key. The second call returns INV02 with the original invoice
A parent pays after the due dateIt still works: the invoice reads overdue until paid
Wrong amount on an invoiceCancel it (if unpaid) and create a new one with a new reference
A parent pays the wrong invoiceHandle the correction in your own records; Moolre has no transfer-between-invoices feature
Part payments, expiry or dashboard-created invoicesNo 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 invoicesCreate 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.