FluxDevelopers OpenAPI & schemasOpenAPI

Core concepts

Invoice lifecycle

An invoice moves through review and approval before it reaches the customer. Your system raises it; people in Flux approve it; webhooks tell you each step.

The lifecycle#

Invoice lifecycle An invoice is raised as awaiting_approval. The accountant approves it, or returns it to the raiser, who resubmits it. Above the organization's threshold it goes to awaiting_final_approval before approved; final approval can also return it. Approved invoices become paid. Any invoice can be voided before it's paid. raised by the API or the app awaiting_approval approved paid returned awaiting_final_approval voided from any state before paid accountant approves paid return resubmit above threshold final approval return
The invoice lifecycle. Each step sends a webhook: see the table below.

Statuses#

statusMeaning
awaiting_approvalRaised, and waiting for the accountant's review.
awaiting_final_approvalThe accountant approved it; a final approver must too.
returnedSent back to the raiser to fix. It goes through review again when resubmitted.
approvedFully approved and emailed to the customer. Payable.
paidPaid. A receipt exists.
voidedCancelled before payment. Can't be paid.

Final approval is set per organization: never, always, or above an NGN amount. A return at final approval goes back to the raiser, then through the accountant's review again.

Steps and webhooks#

StepStatus afterWebhooks
Raised, through the API or in the appawaiting_approvalinvoice.created
Edited in the appunchangedinvoice.updated
Returned by a reviewerreturnedinvoice.returned
Resubmitted by the raiserawaiting_approvalinvoice.submitted
Approved by the accountant, above the final-approval thresholdawaiting_final_approvalinvoice.awaiting_final_approval
Fully approvedapprovedinvoice.approved and invoice.issued
Paid online, or payment confirmed in the apppaidinvoice.paid and receipt.issued (online payments also send payment.succeeded)
Voidedvoidedinvoice.voided

Webhooks can arrive out of order or more than once. When order matters, re-read the invoice. See Receiving webhooks.

When the customer hears about it#

  • The invoice is emailed to the customer's billing contacts only when it becomes approved.
  • Raising an invoice through the API notifies the organization's reviewers, not the customer.
  • Who gets it: the primary billing contact (or the customer's email if there isn't one), plus every contact with ccOnInvoices.

Overdue#

overdue isn't a status. It's true when the invoice is approved, unpaid, not voided and past its dueDate. Filter with GET /invoices?overdue=true.

paymentStatus#

A free-text note set by payment processing, such as successful, amount_mismatch: paid NGN 858,500.00, invoice requires NGN 860,000.00 or refunded: NGN 1,000.00. Show it to people; don't branch on it. Use status and the payment events instead.

What the API can't do#

The API can't update, approve, return or void an invoice. People with the right roles do that in the Flux app; approval is a deliberate human control. You learn about each step by webhook.