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
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_item`s
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 will be in this state till the due date to indicate the due period
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.
Exchange rate used for base currency conversion.Note that when converting foreign currency invoices to local currency for VAT purposes, the exchange rates used differ from the base currency exchange rate provided in this field. This is due to regulations set by tax authorities, which require the use of official sources such as European Central Bank rates for local currency conversion.
This parameter represents the exchange rate as a relative price of the base currency that appears as local currency in invoices and credit notes. The local currency exchange rate specifically refers to the exchange rate of a country's currency when converting it to another currency.
For example, if you want to convert US dollars to euros, the local currency exchange rate would be the rate at which you can convert US dollars to euros.
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.
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.
Invoice subtotal in the currency of the place of supply.
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.
Total invoice amount in the currency of the place of supply.
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.
Timestamp indicating the date & time this invoice got voided.
The version number of this resource. For every change made to the resource, resource_version
is updated with a new timestamp in milliseconds.
Timestamp indicating when this invoice was last updated. This attribute will be present only if the resource has been updated after 2016-09-28. Note: This value does not change when the following attributes are changed: next_retry_at, dunning_status, has_advance_charges
This attribute is returned only if additional resources are available. Use this value as the input parameter for line_items_offset to retrieve the next set of resources.
Note:
- Applicable only when Enterprise-scale Invoicing is enabled.
- Enterprise-scale Invoicing is currently in Private Beta. Please reach out to Chargebee Support to enable this feature.
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 share of the invoice total due to new sales. When first_invoice
is true
, this attribute is the same as total. However, when the invoice is a consolidated
one, then it is the sum of all line_items.amount
belonging to a new.
Boolean indicating any advance charge is present in this invoice.
Boolean indicating this invoice line_items terms are finalized or not.
The date when the invoice is finalized. This is the date in the invoice lifecycle when its status
becomes any one of the following for the first time: payment_due
, posted
, or paid.
For an invoice with status
as pending
, this happens when it gets closed.
The date and time at which dunning should resume automatically for the invoice. This attribute is present only if dunning is currently paused for the invoice. See also: Dunning resumption process.
Payments that are yet to be collected for the invoice. This is the same value as amount_due
- the sum of
linked_payments[].txn_amountfor alllinked_payments[]that havetxn_statusasin_progress.
Indicates the rounded-off amount. For example, if your invoice amount is $99.99, and the amount is rounded off to $100.00, in this case, $100.00 is your invoice amount, $0.01 is the round_off_amount.
If there is no round-off amount
, it will display 0
.
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive
Specifies the customer's category for the Goods and Services Tax (GST). This field is returned only if you've configured GST for the India region.
An overridden value for the first two characters of the full VAT number.
Only applicable specifically for customers with billing_address
country
as XI
(which is United Kingdom - Northern Ireland
).
When you have enabled EU VAT
in 2021 or have manually enabled
the Brexit configuration, you have the option of setting billing_address
country
as XI.
That's the code for United Kingdom - Northern Ireland.
The first two characters of the VAT number in such a case is
XI
by default. However, if the VAT number was registered in UK, the value should be GB.
Set
vat_number_prefix
to GB
for such cases.
The subscription channel this object originated from and is maintained in.
The object was created (and is maintained) for the web channel directly in Chargebee via API or UI.
The object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.
The object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.
In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.
The ID of the business entity created for the site. For Product Catalog 1.0, all the site data is tied to this business entity.
Note
Multiple Business Entities is a feature available only on Product Catalog 2.0.
It represents information about the tax details that are applied to an invoice. Additionally, it specifies the country from which the tax is applied, as well as the relevant tax registration number.
Details of tax_withheld
against this invoice.
A list of up to 20 transactions for this invoice. The list can contain authorizations and payments. Transactions are sorted by creation date in ascending order.
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.
An e-invoice or electronic invoice is a structured representation of an invoice that is interoperable between computerized invoicing systems. Depending on the country, e-invoicing can be necessary to meet financial/taxation authority regulations.