1. Invoicing
  2. Invoices

Invoices

invoices
copy
Click to Copy

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.

Note: If consolidated invoicing is enabled, the field subscription_id is unavailable when the invoice has line items from multiple subscriptions. The individual subscription ids are seen under line_items.subscription_id.

Related Tables

Tables referencing invoices.id
invoice_linked_taxes_withheld invoice_line_item_discounts invoice_adjustment_credit_notes quotes credit_note_allocations invoice_applied_credits order_line_items invoice_discounts invoice_dunning_attempts invoice_line_items invoice_linked_payments invoice_issued_credit_notes orders invoice_notes invoice_line_item_tiers invoice_line_item_taxes

Columns

No match found
id string, not null
Primary Key
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
subscription_id string, null
Foreign Key subscriptions.id
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 field if the invoice includes charges from multiple subscriptions, as it will be null in such cases.
customer_id string, not null
Foreign Key customers.id
The identifier of the customer this invoice belongs to.
business_entity_id string, null
Foreign Key business_entities.id
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.
amount_adjusted long, null, default=0
Total adjustments made against this invoice.
amount_due long, null
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.
amount_paid long, null
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.
amount_to_collect long, null
Payments that are yet to be collected for the invoice. This is the same value as amount_due - the sum of linked_payments[].txn_amount for all linked_payments[] that have txn_status as in_progress.
billing_address_city string, null
The name of the city.
billing_address_company string, null
The company name.
billing_address_country string, null
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.
billing_address_email string, null
The email address.
billing_address_first_name string, null
The first name of the billing contact.
billing_address_last_name string, null
The last name of the billing contact.
billing_address_line1 string, null
Address line 1
billing_address_line2 string, null
Address line 2
billing_address_line3 string, null
Address line 3
billing_address_phone string, null
The phone number.
billing_address_state string, null
State or Province
billing_address_state_code string, null
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address_validation_status string, null, default=not_validated
The address verification status.
billing_address_zip string, null
Zip or postal code. The number of characters is validated according to the rules specified here.
channel string, null
The subscription channel this object originated from and is maintained in.
credits_applied long, null, default=0
Total credits applied against this invoice.
currency_code string, not null
The currency code (ISO 4217 format) for the invoice
date timestamp, null
The document date displayed on the invoice. By default, this matches the effective date of the action that created the invoice (e.g., subscription creation, update, or invoice creation). This date can be backdated for purposes such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. If the invoice is created as pending and the system is configured to set invoice dates to the closing date, this date changes to the invoice closing date upon closure.
due_date timestamp, null
Due date of the invoice.
dunning_status string, null
Current dunning status of the invoice. Possible values are:
  • in_progress: Dunning is still in progress.
  • exhausted: Maximum number of attempts have been made.
  • stopped: Dunning has stopped for this invoice.
  • success: Payment successfully collected during dunning process.
einvoice_id string, null
The unique id for the e-invoice. This is auto-generated by Chargebee.
einvoice_message string, null
Detailed information about the status of the e-invoice. When the status is skipped or failed, this field contains the reason or error details. Examples include:
  • Invoice successfully sent to customer via the e-invoicing network 9090:123456
  • Invoice successfully sent to customer via email id abc@acme.com
einvoice_reference_number string, null
This field is used to populate the unique reference number assigned to an invoice on the Invoice Registration Portal (IRP) network. It is essential for identifying and tracking invoices that are processed through the IRP network. In the future, this field may be used to store similar reference numbers for other networks.
einvoice_status string, null
The status of processing the e-invoice. For detailed information about the current status, refer to the message field.
expected_payment_date timestamp, null
Expected payment date recorded for this invoice.
first_invoice boolean, null
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.
generated_at timestamp, null
The date when the invoice is finalized. This is the point in the invoice lifecycle when its status changes to one of the following for the first time: payment_due, posted, or paid. For an invoice with status as pending, this occurs when it is closed.
is_gifted boolean, not null, default=false
Boolean indicating this invoice is gifted or not.
local_currency_code string, null
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.
local_currency_exchange_rate decimal, null
This field 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.
net_term_days null, default=0
Number of days within which the invoice has to be paid.
new_sales_amount long, null
The share of the invoice total due to new sales. When first_invoice is true, this field value 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.
payment_owner string, null
Payment owner of an invoice.
po_number string, null
Purchase Order Number for this invoice.
price_type string, not null, default=tax_exclusive
The price type of the invoice.
recurring boolean, not null, default=true
Boolean indicating whether this invoice belongs to a subscription.
resource_version long, null
The version number of this table. For every change made to the table, resource_version is updated with a new timestamp in milliseconds.
round_off_amount long, null
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.
shipping_address_city string, null
The name of the city.
shipping_address_company string, null
The company name.
shipping_address_country string, null
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

shipping_address_email string, null
The email address.
shipping_address_first_name string, null
The first name of the contact.
shipping_address_index null
The index number of the subscription to which the item price is added. Provide a unique number between 0 and 4 (inclusive) for each subscription that is to be created.
shipping_address_last_name string, null
The last name of the contact.
shipping_address_line1 string, null
Address line 1
shipping_address_line2 string, null
Address line 2
shipping_address_line3 string, null
Address line 3
shipping_address_phone string, null
The phone number.
shipping_address_state string, null
The state/province name.
shipping_address_state_code string, null
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address_validation_status string, null, default=not_validated
The address verification status.
shipping_address_zip string, null
Zip or postal code. The number of characters is validated according to the rules specified here.
site_details_at_creation_organization_address string, null
site_details_at_creation_timezone string, null
statement_descriptor_descriptor string, null
Payment descriptor text
statement_descriptor_id string, null
Uniquely identifies a statement_descriptor
status string, not null
The current status of the invoice.
sub_total long, not null
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.
sub_total_in_local_currency long, null
Invoice subtotal in the currency of the place of supply.
tax long, not null
Total tax amount for this invoice.
tax_category string, null
Specifies the customer's category for the Goods and Services Tax (GST).
tax_origin_country string, null
The country code in (ISO 3166-1 alpha-2 format) where the tax originated from.
tax_origin_registration_number string, null
It represents the tax registration number for the entity used to collect tax.
term_finalized boolean, not null, default=true
Boolean indicating this invoice line_items terms are finalized or not.
total long, null
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_in_local_currency long, null
Total invoice amount in the currency of the place of supply.
updated_at timestamp, null
Timestamp indicating when this invoice was last updated. This field will be present only if the table has been updated after 2016-09-28.
Note: This value does not change when the following fields are changed: next_retry_at, dunning_status, has_advance_charges
vat_number string, null
VAT/ Tax registration number of the customer. Learn more
vat_number_prefix string, null
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.
void_reason_code string, null
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.
voided_at timestamp, null
Timestamp indicating the date & time this invoice got voided.
write_off_amount long, null, default=0
Amount written off against this invoice.