Invoices are statements containing charges, adjustments and any discounts for a subscription specific to a term. For every subscription a draft invoice (upcoming invoice) is used to track all the charges, credits and adjustments for the current term.
Generally, an invoice is closed at start of the next term. However, cancellation and other such operations on subscription may trigger premature closing. While closing the invoice, in addition to recurring charges, credits and coupons are applied to calculate the final amount that is due.
When invoice is closed, an attempt to charge the credit card is made. If the payment succeeds, it is marked as paid. If the payment fails, the invoice is marked as payment_due and retry settings are taken into account. If no retry attempts are configured, the invoice is marked as not_paid. If the amount due is zero or negative, the invoice is immediately marked as paid and the balance if any is carried forward to the next term of the invoice.
Note: If consolidated invoicing is enabled, the attribute invoice.subscription_id should not be used (as it will not be present if the invoice has lines from multiple subscriptions). Instead to know the related subscriptions, their line_items subscription_id attribute should be referred.
Sample InvoiceJSON
API Index URL
Invoices attributes
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
The identifier of the subscription this invoice belongs to.
Note:
When consolidated invoicing is enabled, you have to refer to line_items
subscription_id
to identify the subscriptions associated with this invoice. However, it is important to avoid using this attribute if the invoice includes charges from multiple subscriptions, as it will be null in such cases.
Boolean indicating whether this invoice belongs to a subscription
Current status of this invoice.
Indicates a paid invoice.
Indicates the payment is not yet collected and is being retried as per retry settings.
Indicates the payment is not made and all attempts to collect is failed.
Indicates a voided invoice.
The invoice is yet to be closed (sent for payment collection). An invoice is generated with this status when it has line items that belong to items that are metered or when the subscription.create_pending_invoicesattribute is set to true.
The invoice is yet to be closed (sent for payment collection). All invoices are generated with this status when Metered Billing is enabled for the site.
The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. However, if the invoice is created as pending
, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date.
The price type of the invoice.
All amounts in the document are exclusive of tax.
All amounts in the document are inclusive of tax.
The sum of all the line item amounts minus the sum of all line item discounts. In other words, this is the sum of all line_items[].amount
- the sum of all
line_item_discounts[].discount_amount.
Invoiced amount displayed in cents; that is, a decimal point is not present between the whole number and the decimal part. For example, $499.99 is displayed as 49999, and so on.
The unpaid amount that is due on the invoice. This is calculated as: total
-
amount_paid - sum of
applied_credits.applied_amount - sum of
adjustment_credit_notes.cn_total - sum of
linked_taxes_withheld.amount.
Payments collected successfully for the invoice. This is the sum of linked_payments[].txn_amount
for all linked_payments[]
that have txn_status
as success.
Timestamp indicating the date & time this invoice got paid.
Current dunning status of the invoice.
Dunning is still in progress.
Maximum number of attempts have been made.
Dunning has stopped for this invoice.
Payment successfully collected during dunning process.
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
Boolean indicating the first invoice raised for the subscription. In the case of a non-recurring invoice, it indicates the first invoice raised for the customer.
The list of notes
that appear on the invoice PDF sent to the customer. Notes that come from a specific resource related to the invoice have entity_type
and entity_id
defined. There can be up to two notes in this array for which entity_type
and entity_id
are not defined:
- Invoice-specific note: It is the note provided via the
invoice_noteparameter for various endpoints in the API that also create invoices. For example, creating a subscription, creating an invoice, and closing a pending invoice. - General note: This note is added to all invoices of the Chargebee site. You can add/edit this note in the Chargebee admin console.