Everyone

Invoice Lifecycle & Statuses

A complete reference for every invoice status in Commerce and how invoices move between them automatically and manually.

Last updated 1776211200
  • Status Badge Colours
  • Manual Status Changes
  • Related Topics

    • Status Overview

    Every invoice in Commerce carries one of six statuses at any point in time:

    Status Meaning
    draft Created but not yet sent. The client cannot pay it.
    unpaid Sent to the client. Payment is expected by the due date.
    overdue Past the due date without full payment. An automated reminder has been sent.
    paid Full payment received. The invoice is closed.
    cancelled Voided. No payment is expected or possible.
    refunded A full refund was issued. The invoice is closed.

    Status Flow Diagram

    draft
  └─► unpaid ──────────────────────────► paid
            │                              ▲
            └─► overdue ──────────────────┘
                        │
                        └─► cancelled

paid ──► refunded

    A partial refund does not change the invoice status to refunded. Only a full refund does. The invoice remains paid with a separate credit note for partial amounts.

    What Each Status Means

    draft

    The invoice has been created (either as a manual draft or by the system) but has not been sent. Clients cannot see draft invoices in their portal. No payment link is active.

    Use draft to prepare an invoice before review, then publish it when ready.

    unpaid

    The invoice is visible to the client and payment is expected. This is the normal state for:

    • Invoices generated on new orders
    • Renewal invoices created by the scheduler
    • Manual invoices published by an admin

    overdue

    The commerce:mark-overdue-invoices command runs daily at 00:30 and automatically transitions unpaid invoices whose due_date is in the past to overdue. This command:

    1. Finds all unpaid invoices where due_date < today
    2. Sets status to overdue
    3. Sends the overdue reminder email (only once — guarded by the notified_at timestamp so re-runs on the same invoice do not double-send)

    [!IMPORTANT] If your cron job is not running, invoices will never move to overdue automatically. Verify with php artisan schedule:list.

    paid

    The invoice is fully settled. This status is set:

    • Automatically when a payment gateway confirms full payment (webhook received)
    • Automatically when a manual payment recorded by an admin equals the invoice total
    • Automatically when account credit covers the full remaining balance

    When an invoice moves to paid:

    • For order invoices: service provisioning is triggered
    • For renewal invoices: the service's next_due_date is advanced by the billing cycle
    • A payment receipt email is sent to the client

    cancelled

    A cancelled invoice is voided — it will never be paid. Cancelling does not issue a refund. Use this for:

    • Test orders
    • Invoices created by mistake
    • Orders abandoned before payment

    [!WARNING] Cancelling an invoice linked to an active service does not automatically suspend or cancel that service. Handle the service separately if needed.

    refunded

    Set automatically when a full refund is processed through any gateway. Partial refunds generate a credit note but leave the invoice as paid. See Credit Notes & Refunds.

    Status Badge Colours

    Status Admin badge Client portal badge
    draft Grey — (not shown)
    unpaid Yellow Yellow
    overdue Red Red
    paid Green Green
    cancelled Grey/strikethrough Grey
    refunded Purple Purple

    Manual Status Changes

    Admins can change invoice status from the invoice detail view:

    • Publish draft — moves draft → unpaid, sends the invoice email
    • Mark paid — shortcut to record a full payment without entering gateway details
    • Cancel — moves any non-paid invoice to cancelled

    [!TIP] Use "Mark paid" for offline payments where you want to skip the Record Payment form. The system records a payment of the full invoice amount with the gateway set to manual.

    Related Topics

    Previous
    ← Invoices Overview
    Next
    Invoice Numbering Scheme →