Invoices in Subotiz follow a defined invoice lifecycle that reflects how each invoice status is processed across billing, retry, and refund flows. Invoice statuses are updated automatically based on payment results, retry outcomes, refund completion, and subscription state changes. Each status represents a specific stage in the invoice lifecycle and indicates whether an invoice is completed or still in progress.
Status Mapping and Transitions
Invoice statuses update automatically based on payment, retry, and refund outcomes. The following statuses represent the current state of an invoice:
- Open: The invoice has been created, but payment has not yet started. This status may appear when a subscription is created, a trial is activated, or a billing event has not yet triggered a charge.
- Payment in progress: A payment attempt has been initiated and is awaiting confirmation from the payment gateway. Once the result is returned, the status updates automatically to Paid, Failed, or Retrying (if applicable).
- Retrying: This status applies only to subscription renewal charges. It indicates that the initial renewal payment attempt failed and the invoice is still within the system’s automatic retry period.
- Paid: Payment completed successfully. The invoice is finalized.
- Failed: Payment was not successful and is no longer in a payment or retry process. This is a terminal state, and the invoice is considered incomplete.
- Partially Refunded: A portion of the original invoice amount has been refunded. The remaining amount remains valid and is recorded on the invoice.
- Refunded: The full invoice amount has been refunded. The invoice status reflects the final outcome of the billing record.
Retrying Status Details
Retrying is an intermediate status introduced specifically for subscription renewal scenarios. It distinguishes an initial payment failure from a final failed outcome.
- When a subscription renewal charge fails for the first time and remains within the allowed retry window, the invoice status changes to Retrying.
- Subotiz applies a Smart Retry strategy and attempts to reprocess the payment up to four times. Retry timing is determined dynamically by the system, and no manual action is required from the merchant.
- If any retry attempt succeeds, the invoice status updates to Paid.
- After the maximum retry attempts are reached, whether the invoice transitions to Failed depends on the related subscription contract status.
Note: The Retrying status applies only to subscription renewal charges. It does not apply to one-time purchases or initial subscription charges.
Subscription Contract Impact on Invoice Status
Subscription contract status affects how invoice statuses are finalized after retry attempts:
- If the maximum number of retries is reached and the subscription contract remains active, the invoice status continues to remain Retrying.
- If the subscription contract is cancelled, any unresolved renewal invoice transitions to Failed.
This distinction separates payment failure from subscription termination.
0-Value Invoices
In certain scenarios, Subotiz may generate invoices with a total amount of 0. A zero-value invoice describes an amount characteristic and is not tied to a specific invoice type.
Whether a zero-value invoice is linked to a payment process depends on the billing context:
- First zero-value invoice in a subscription renewal scenario
- When a renewal cycle generates a zero-amount invoice for the first time, the system may initiate a payment flow to collect or verify a payment method. Once the gateway confirms the transaction (even at $0), the invoice status updates to Paid.
- One-time purchases or accounts with an existing payment method
- If no payment method verification is required, the invoice is generated and marked as Paid directly. No payment process is triggered, and no standalone payment record is created.
Refund Workflow and Invoice Updates
Refunds are not initiated directly from invoices. All refunds are processed through the corresponding Trade Orders.
Invoice statuses are synchronized automatically based on the refund result:
- Full refund completed → Invoice status updates to Refunded.
- Partial refund completed → Invoice status updates to Partially Refunded.
- Refund failed → Invoice status remains unchanged.
Invoice statuses reflect the refund results recorded in the related trade orders.
Lifecycle Perspective
Throughout the billing lifecycle, invoice statuses may change automatically as a result of the following events:
- Payment result confirmation
- Automatic retry outcomes
- Refund completion
- Subscription contract status changes (for example, cancellation)
Merchants do not need to manually update invoice statuses. The system synchronizes invoice status automatically based on actual processing results.
Subotiz uses a comprehensive invoice status framework to represent how each billing record progresses through payment, retry, and refund workflows. By combining invoice status and invoice type information, merchants can accurately determine the current stage of an invoice, support reconciliation, respond to customer inquiries, and make informed operational decisions.