An invoice is a commercial document representing a sale of products/services offered by you to a customer. It enumerates all the charges, adjustments, payments, discounts and taxes associated with the sale.
An invoice is said to be a recurring one when it is has at least one charge for a plan or an addon item price. It is a non-recurring one when it has charges for only charge-item prices or one-time charges.
The item prices for any given billing term of a subscription are billed via an invoice at the beginning of the term (unless the charges are left unbilled). However, item prices that belong to metered items are billed at the end of the term via a pending invoice that can close automatically or via an API call. Moreover, when there are no metered items in the subscription, the invoices can still be generated as pending while creating or updating a subscription.
Auto-collection
If auto-collection is enabled, then immediately on invoice generation (or, in case of subscriptions that have create_pending_invoices as true, on invoice closure), the payment method on file is charged:
- If the payment succeeds, the invoice is marked as
paid. - On payment failure, the invoice is marked as
payment_dueand dunning settings are taken into account for payment retries. - If no retry attempts are configured, or when retries are exhausted, the invoice is marked as
not_paid. - the amount due is zero or negative, the invoice is immediately marked as
paidand the balance, if any, is added to excess payments for the customer.
Note: If consolidated invoicing is enabled, the attribute subscription_id is unavailable when the invoice has line items from multiple subscriptions. The individual subscription ids are seen under line_items.subscription_id.
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 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 unique ID of the business entity of this invoice. Depending on whether the invoice was created directly for a customer or for a subscription, this is the business entity of the customer or the subscription respectively.
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.