Doc types — tax / proforma / credit / debit

The 5 doc types

Tax invoice — the default

Per Oman VAT Law (RD 121/2020), a compliant tax invoice must include:

• The phrase "Tax Invoice" prominently
• Sequential invoice number
• Issue date
• Supplier's name + address + VAT TRN (11-digit)
• Customer's name + address + VAT TRN (if applicable)
• Description of goods/services
• Unit price excluding VAT
• VAT rate + VAT amount per line
• Total excluding VAT, total VAT, total including VAT
• Currency (if not OMR)

The branded PDF template includes all 10 elements. Don't customise the template without re-validating compliance.

Proforma — pre-supply quote-shaped invoice

Used to request advance payment before delivering the service. Behaviour:

• Number prefix: PI/{YYYY}/{NNNN}
• VAT shown as informational only — not collected, not reported
• PDF carries a large "PROFORMA" watermark in orange
• Cannot be paid with a tax-receipt allocation (the linked payment becomes is_advance=1)
• Conversion path: when work is delivered, click Convert to tax invoice — clones lines, stamps both lineage columns, original proforma flips to converted

Worked proforma → tax invoice flow

1. Issue proforma PI/2026/0010

   OMR 5,250 (including informational VAT). Client receives PDF with "PROFORMA" watermark.

2. Client pays advance

   OMR 5,250 hits firm bank. Record payment, allocate to PI/2026/0010. Payment row marked is_advance=1.

3. Work delivered

   Job completed.

4. Convert proforma → tax invoice

   From PI/2026/0010 detail → Convert. Clones lines into new INV/2026/0042 draft. Stamps lineage:
   proforma.converted_to_invoice_id = 42 · tax_invoice.parent_invoice_id = 10.

5. Auto-allocate advance

   System detects client has OMR 5,250 advance from the proforma payment, applies it to the new tax invoice. Tax invoice flips draft → sent → paid in one shot. Both lineage columns stamped.

Credit note — refund / cancel

Reverses a previously-sent tax invoice. Used when:

• Service cancelled after invoicing — full credit
• Discount granted retroactively — partial credit
• Invoice cancelled in error — full credit (but prefer to cancel directly if not yet sent)
• Refund to client

Behaviour:

• Number prefix: CN/{YYYY}/{NNNN}
• Issued from a parent tax invoice (parent_invoice_id required)
• Lines clone from parent (full or partial)
• Negative amounts on the parent for reporting purposes
• VAT carries the same rate (negative effect)
• Goes through normal draft → sent workflow

Debit note — additional charge

Adds to a previously-sent tax invoice. Used when:

• Scope-creep top-up (extra fee for additional work)
• Late penalty
• Out-of-pocket recovery after the original invoice

Behaviour:

• Number prefix: DN/{YYYY}/{NNNN}
• Optional parent_invoice_id (can be standalone or linked)
• Standard line items + 5% VAT
• Goes through normal draft → sent workflow
• Counts as a separate AR row — can be paid independently

Lineage map across types