Invoices Overview

5 min

Invoices Overview

In the Nue API, an Invoice serves as the primary financial document used to request and track customer payments for products delivered or services rendered. Invoices are created based on active subscriptions, assets, entitlements, or usage data, consolidating all charges, adjustments, and payment obligations for a specific billing period. Invoice management enables businesses to automate the entire payment lifecycle—from invoice creation, delivery, and payment collection through reconciliation and post-processing—supporting one-time, recurring, usage-based, and hybrid billing models within the Nue ecosystem.

What Is Invoice Lifecycle

The invoice lifecycle in the context of the Nue API describes the sequence of states and processes an invoice undergoes from its initial creation to final closure. This lifecycle automates and manages all financial activities associated with charging customers, collecting payments, handling exceptions, and ensuring financial reconciliation.

Stages of the Invoice Lifecycle in Nue

Draft The invoice is generated, usually triggered by a billing schedule or upon order activation. In this stage, the invoice is not yet visible to the customer or payable.

Pending Activation The invoice awaits approval or additional conditions (such as review or final amount calculation). No payment collection is initiated at this stage.

Active The invoice is now officially issued and payable via a connected collection system or an email notification containing a secure payment link.

Transfer: If a collection system is connected, the invoice will be transferred to the system upon activation, and the payment status of the invoice is updated from "Open" to "Transferred".

Pay: If a payment is initiated, the payment status (“Paid” or “Partially Paid”) of the invoice is updated.

Apply Credit Memo: Credit memos can be applied to reduce the outstanding balance of an invoice, and the payment status (“Applied” or “Partially Applied”) is updated.

Refund: If a refund is initiated, the corresponding payment status (“Refunded” or “Partially Refunded”) is updated.

Write Off: If amounts are deemed uncollectible, the invoice is marked as “Write Off”, and the payment status (“Written Off” or “Partially Written Off”) is updated.

Canceled The invoice has been officially voided and will be removed from the billing and payment process, ensuring that no further payment activity or post-processing actions are performed on the document.

Reversed The active invoice has been reversed and remains historically visible as a terminated record. Available actions: none by default. Delete is allowed only when the Allow deleting reversed invoices setting is enabled.

For more information about invoice lifecycle, please refer to this article.

All invoice activities are synchronized with external financial systems (like ERP or accounting software) to ensure records match. The invoice’s lifecycle ends when its balance is zero—either through payment, credits, write-off, or a combination of adjustments—and its final state is logged.

Invoice Statuses

Invoices can have one of the following statuses, and the actions available for that invoice depend on its current status.

STATUS	DESCRIPTION	AVAILABLE ACTIONS
Draft	The invoice is generated but not yet payable.	- Update certain fields - Activate - Cancel
PendingActivation	The invoice awaits approval or additional adjustments.	- Update certain fields - Activate - Cancel
Active	The invoice is finalized and awaiting payment.	- Update certain fields - Cancel - Process payment
Canceled	The invoice is voided.	- Delete
Reversed	The invoice is reversed.	- None
E-Invoicing	The invoice is in the process of the electronic invoicing	- Update certain fields - Activate after the process completes - Cancel

Invoice Payment Statuses

The payment status of an active invoice is set based on the payment and collection actions performed. Invoices can have one of the following payment statuses.

PAYMENT STATUS	DESCRIPTION	AVAILABLE PAYMENT ACTIONS
NotTransferred	The invoice is "Open" and has not been transferred to a payment system.	- Send to the collection system - Process payment and collection
Transferred	The invoice has been successfully transferred to the payment system and is awaiting payment.	- Process payment and collection
TransferError	The invoice failed to be transferred to the payment system due to an error.	- Resend to the collection system
Paid	The invoice has been paid in full.	- Refund
PartialPaid	The invoice has received partial payment and the balance remains outstanding.	- Pay - Refund
Canceled	The invoice was reversed or canceled before any payment occurred.	- No Payment Actions Available
CreditBack	The transaction was created as part of the refund process to offset invoices.	- Refund
Applied	(For credit memos) The full amount of a credit memo has been applied to invoices.	- Unapply
PartiallyApplied	(For credit memos) A portion of the credit memo has been applied to invoices.	- Unapply
Refunded	The invoice has been fully refunded to the customer.	- No Payment Actions Available
PartialRefunded	The invoice has been partially refunded, and part of the original payment has been returned.	- No Payment Actions Available
WrittenOff	The invoice is considered uncollectible and has been written off as bad debt.	- No Payment Actions Available
PartiallyWrittenOff	A portion of the invoice is considered uncollectible and has been written off as bad debt.	- No Payment Actions Available
Processing	The invoice is currently in the process of being paid	- No Payment Actions Available

Next Steps

Explore the invoice implementation guides:

Generate InvoicesGenerate Invoices - How Nue invoices are generated

Manage InvoicesManage Invoices - Learn core invoice retrieval and updating operations

Process PaymentProcess Payment - Process payment and collection for an invoice

Preview InvoicesPreview Invoices - Preview invoices for a customer or an order

Each guide serves as a quick start for different stages, offering comprehensive coverage of invoice and payment features in the Nue API.