DocsCore Features

Invoices & Estimates

Understand the strict document lifecycle, state machine, approval workflow, ZATCA routing, and how credit/debit notes work under Saudi tax law.

Prime Fatoora's invoicing engine is not a simple form that generates a PDF. It is a strict, stateful system that enforces legal document workflows, automates accounting entries, and integrates natively with ZATCA Phase 2. Every invoice flows through a strict set of states that can only transition in defined directions.

The Invoice State Machine

Every invoice has a Status and an Approval Status. These two states work together to control what actions are allowed at any given moment.

Status Transitions

The following transitions are the only ones permitted at the database level. Any attempt to skip a state is rejected with an error:

Current Status	Allowed Next States
DRAFT	SENT, CANCELLED
SENT	VIEWED, PARTIALLY_PAID, PAID, OVERDUE, CANCELLED
VIEWED	PARTIALLY_PAID, PAID, OVERDUE, CANCELLED
PARTIALLY_PAID	PAID, OVERDUE
PAID	— Terminal state. No further transitions allowed.
OVERDUE	PARTIALLY_PAID, PAID, CANCELLED

Approval Status

Separate from the document Status, every invoice also has an Approval Status. On enterprise plans (with more than one user), invoices must go through an approval workflow before they can be sent to the customer:

DRAFT → The default state when an invoice is first created. It can be freely edited.
PENDING → Submitted for approval. The invoice can no longer be edited.
APPROVED → The invoice has been approved and can now be sent to the customer.
REJECTED → Rejected by the approver. The creator must make changes and resubmit.

Four-Eyes Approval Principle

The backend enforces a strict four-eyes principle: an invoice must be approved by a different user than the one who created or submitted it. This is enforced at the database level and cannot be bypassed.

What Happens When You Create an Invoice

When a new invoice is saved, the backend performs strict calculations on every line item simultaneously:

Subtotal: Sum of (quantity × unitPrice) for every line, before any discounts.
Discount Total: The sum of all per-line discountAmount values.
Tax Amount per line: Calculated differently based on whether prices are tax-inclusive or exclusive:
- Tax-exclusive: tax = (gross - discount) × taxRate / 100
- Tax-inclusive: tax = gross - (gross / (1 + taxRate/100))
Shipping: Added to the grand total after line-level calculations. Cannot be negative.
Withholding Tax: Deducted from the grand total. Produces the final amountDue.

Standard vs Simplified Invoices

Invoices are categorized based on the buyer profile. Prime Fatoora routes this automatically.

Feature	Standard (B2B) — `tax_invoice`	Simplified (B2C) — `simplified_tax_invoice`
Buyer	Registered business with a valid TIN.	Individual consumer or unregistered business.
ZATCA Workflow	Clearance — must be cleared by ZATCA before the PDF can be shared with the buyer. The system blocks PDF download until cleared.	Reporting — PDF can be issued immediately. Reported to ZATCA within 24 hours by background queue workers.
PDF Lock	Blocked until ZATCA returns a valid clearance stamp.	Immediately available for download after creation.

Additional Invoice Flags

When creating an invoice, you can set several optional boolean flags for specialized scenarios:

isThirdParty — Invoice is issued on behalf of a third party.
isNominal — Nominal invoice (zero-value).
isExport — Marks the transaction as an export sale.
isSummary — Summary invoice covering multiple transactions.
isSelfBilled — Self-billed invoice (buyer-initiated).
isPrepayment — Prepayment invoice, optionally linked to a prepaymentReference.

Credit & Debit Notes

Once an invoice is ZATCA-cleared or reported, it cannot be edited. The only way to correct or adjust it is through a Credit Note or Debit Note, both of which must reference the original invoice's ID and undergo the same ZATCA submission process.

Credit Notes — Reducing Debt

Issued when you need to reduce the amount owed by a customer — for example, when a customer returns goods or you overcharged them. The credit note reverses the revenue and VAT liability recorded on the original invoice.

Debit Notes — Increasing Debt

Issued when you need to increase the amount owed — for example, you forgot to add a shipping charge to the original invoice. The debit note increases the revenue and VAT liability on the ledger.

Automatic Overdue Marking

Prime Fatoora runs a background cron job that automatically marks invoices as OVERDUE when their due date passes and they haven't been fully paid. Additionally, a separate cron job sends automatic payment reminder emails to customers on their behalf. These jobs run without any manual intervention.

Frequently Asked Questions

Can I edit an invoice after it has been sent to the customer?

No. Once an invoice is no longer in DRAFT status, its financial content cannot be changed. If the invoice has also been ZATCA-cleared or reported, you must issue a Credit Note or Debit Note to make any adjustments.

Can an invoice creator approve their own invoice?

Only on small plans (single-user accounts). On enterprise plans, the system enforces that the approver must be a different person from the creator and the submitter. This is hardcoded at the backend level.

Can I duplicate an existing invoice?

Yes. The Copy Invoice feature creates a new draft invoice with the same line items, customer, payment terms, and due date calculation as the original, with a new sequential invoice number and today's issue date.