Skip to navigation

GetInvoices

View as Markdown

Returns a list of invoices based on issue date, due date and status

Input variables

  1. json representation of an Invoicefilters object with properties
    1. issueDateFrom
    2. issueDateTo
    3. dueDateFrom
    4. dueDateTo
    5. status of Invoice (1 unpaid, 2 partially paid, 3 fully paid)

Only invoices of the school named by your schoolCode are returned. On an account with several schools, each school’s key lists its own invoices.

Students on an invoice

  • studentIds — every student the invoice bills, each listed once. An invoice made out to a guardian can bill several children, so this is always a list.
  • fees[].studentId — the student a fee line bills. Use it with GetStudent.
  • fees[].periodStudentId — the student’s enrollment in the school period the line bills for. It is the same id as id in GetPeriodStudents and schoolPeriods[].id in GetStudent and GetStudents.
  • fees[].schoolPeriodId — the school period the line bills for. Together with periodStudentId it fetches just that enrollment: GET /students/schoolperiod/{schoolPeriodId}/list?periodStudentId={periodStudentId}.

Payment object fields

  • status — whether the payment settled. 1 VALID (settled), 2 INVALID (failed), 3 PENDING (in flight), 4 REFUNDED. May be absent on payments predating the field; treat absent as settled.
  • paymentFees — the online processing fee taken on top of amount, which never includes it. Stripe collects amount + paymentFees as a single charge, so this is what reconciles a payment against a Stripe payout.
  • stripePaymentIntentId — the Stripe PaymentIntent behind the payment, or null for a manually recorded one.

All three are read-only: they report what the payment provider did and are never accepted in a request body.

Reconciling payments against paidAmount

An invoice’s payments are every attempt made against it, not only the money it received. A declined card records a payment row of its own, so the array can total more than paidAmount. Only status 1 rows move paidAmount, and only those sum to it.

status 3 is not a failure: bank debits (ACH) sit there for 3-5 business days while they clear. Count 1 as received, exclude 2, and report 3 separately as pending receipts.

A retried card charge is billed for the invoice’s remaining balance, so repeated attempts carry identical amounts. The amount alone cannot separate a failed retry from a genuine instalment — use status.

The example response below shows this: two settled payments of 5.25 summing to paidAmount 10.50, alongside a declined 10.50 card attempt that does not.

Headers

dreamclass-secret-keystringOptional

Your DreamClass API key. Required on every request. Find it in the DreamClass app under Settings > Integrations.

tenantstringOptional

Your tenant code: the DreamClass subdomain you sign in at (for https://myaccount.dreamclass.io it is “myaccount”), or your full white-labelled domain. Required on every request.

schoolCodestringOptional

Your school code. Required on every request. Find it in the DreamClass app under Settings > Integrations.

Request

This endpoint expects an object.
issueDateFromdateRequired
issueDateΤοdateRequired
dueDateFromdateRequired
dueDateΤοdateRequired
statusintegerRequired

Response

OK
idinteger
invoiceRefIdstring
amountdouble
paidAmountdouble
statusinteger
fullnamestring
addressstring
telephonestring
emailstringformat: "email"
createdAtdatetime
issueDatedate
dueDatedate
publicNotesstring
feeslist of objects
paymentslist of objects
studentIdslist of integers
privateNotesanyOptional