# Invoices > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). 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](/docs/api/items). It is a non-recurring one when it has charges for only charge-item prices or [one-time charges](https://www.chargebee.com/docs/2.0/charges.html). 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](https://www.chargebee.com/docs/billing/2.0/usage-based-billing/metered_billing#configuring-metered-billing) or via [an API call](/docs/api/invoices/close-a-pending-invoice). Moreover, when there are no `metered` items in the subscription, the invoices can still be generated as `pending` while [creating](/docs/api/subscriptions/create-subscription-for-items) or [updating](/docs/api/subscriptions/update-subscription-for-items) a subscription. #### Auto-collection[](#auto-collection) If [auto-collection](https://www.chargebee.com/docs/2.0/customers.html#auto-collection-status) is enabled, then immediately on invoice generation (or, in case of subscriptions that have `create_pending_invoices` as `true`, on [invoice closure](/docs/api/invoices/close-a-pending-invoice)), the [payment method](/docs/api/customers/customer-object#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_due` and [dunning settings](https://www.chargebee.com/docs/2.0/dunning-v2.html) 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 `paid` and the balance, if any, is added to [excess payments](https://www.chargebee.com/docs/2.0/customers.html#excess-payments) for the customer. **Note:** If [consolidated invoicing](https://www.chargebee.com/docs/2.0/consolidated-invoicing.html) 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`. #### Recurring and non-recurring invoices[](#recurring-and-non-recurring-invoices) A recurring invoice contains at least one line item that is billed on a recurring basis. Specifically, it has at least one [`line_items[]`](/docs/api/invoices/invoice-object#line_items) with `entity_type` set to `plan_item_price` or `addon_item_price`. A non-recurring invoice contains no recurring line items. #### Refundable amount for an invoice[](#refundable-amount-for-an-invoice) The refundable amount for an invoice is the (amount paid on the invoice + refundable credit applied on the invoice + taxes withheld on the invoice) minus (amount issued as refundable credit notes from the invoice). Each of these amounts is obtained from the invoice resource as follows: - Amount paid on the invoice: [`amount_paid`](/docs/api/invoices/invoice-object#invoice_amount_paid) - Refundable credit applied on the invoice: [`credits_applied`](/docs/api/invoices/invoice-object#invoice_credits_applied) - Taxes withheld on the invoice: Sum of [`linked_taxes_withheld[].amount`](/docs/api/invoices/invoice-object#invoice_linked_taxes_withheld) - Amount issued as refundable credit notes from the invoice: Sum of [`issued_credit_notes[i].cn_total`](/docs/api/invoices/invoice-object#invoice_issued_credit_notes) where `issued_credit_notes[i].cn_status` is `refunded` or `refund_due`. ## Sample Invoice ```json { "adjustment_credit_notes": {}, "amount_adjusted": 0, "amount_due": 0, "amount_paid": 2000, "amount_to_collect": 0, "applied_credits": {}, "base_currency_code": "USD", "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address", "validation_status": "not_validated" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__KyVkkWS1xLskm8", "date": 1517463749, "deleted": false, "due_date": 1517463749, "dunning_attempts": {}, "exchange_rate": 1, "exchange_rates": [ { "currency_code": "EUR", "rate": 1.154 }, {..} ], "first_invoice": true, "has_advance_charges": false, "id": "__demo_inv__1", "is_gifted": false, "issued_credit_notes": {}, "line_items": [ { "amount": 2000, "customer_id": "__test__KyVkkWS1xLskm8", "date_from": 1517463749, "date_to": 1517463749, "description": "SSL Charge USD Monthly", "discount_amount": 0, "entity_id": "ssl-charge-USD", "entity_type": "charge_item_price", "id": "li___test__KyVkkWS1xLt9LF", "is_taxed": false, "item_level_discount_amount": 0, "object": "line_item", "pricing_model": "flat_fee", "quantity": 1, "tax_amount": 0, "tax_exempt_reason": "tax_not_configured", "unit_amount": 2000 }, {..} ], "linked_orders": {}, "linked_payments": [ { "applied_amount": 2000, "applied_at": 1517463750, "txn_amount": 2000, "txn_date": 1517463750, "txn_id": "txn___test__KyVkkWS1xLtFiG", "txn_status": "success" }, {..} ], "net_term_days": 0, "new_sales_amount": 2000, "object": "invoice", "paid_at": 1517463750, "price_type": "tax_exclusive", "recurring": false, "resource_version": 1517463750000, "round_off_amount": 0, "shipping_address": { "city": "Walnut", "country": "US", "first_name": "John", "last_name": "Mathew", "object": "shipping_address", "state": "California", "state_code": "CA", "validation_status": "not_validated", "zip": "91789" }, "status": "paid", "sub_total": 2000, "tax": 0, "term_finalized": true, "total": 2000, "updated_at": 1517463750, "write_off_amount": 0 } ``` ## Invoices attributes ## Input Parameters - `id` (required, string, max chars=50) The invoice number. Acts as a identifier for invoice and typically generated sequentially. - `customer_id` (required, string, max chars=50) The identifier of the customer this invoice belongs to. - `payment_owner` (optional, string, max chars=50) Payment owner of an invoice - `subscription_id` (optional, string, max chars=50) The identifier of the subscription this invoice belongs to. **Note**: When consolidated invoicing is enabled, you have to refer to [line\_item\`s](/docs/api/invoices/invoice-object#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. - `recurring` (required, boolean, default=true) Boolean indicating whether this invoice belongs to a subscription - `status` (required, enumerated string) Current status of this invoice. Possible enum values: - `paid` Indicates a paid invoice. - `posted` Indicates the payment is not yet collected and will be in this state till the due date to indicate the due period - `payment_due` Indicates the payment is not yet collected and is being retried as per retry settings. - `not_paid` Indicates the payment is not made and all attempts to collect is failed. - `voided` Indicates a voided invoice. - `pending` The [invoice](/docs/api/invoices/invoice-object#status) 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_invoices`attribute is set to `true`. The [invoice](/docs/api/v2/pcv-1/invoices/invoice-object#status) is yet to be closed (sent for payment collection). All invoices are generated with this `status` when [Metered Billing](https://www.chargebee.com/docs/1.0/metered_billing.html) is enabled for the site. - `date` (optional, timestamp(UTC) in seconds) 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. - `due_date` (optional, timestamp(UTC) in seconds) Due date of the invoice - `net_term_days` (optional, integer, default=0) The number of days from [`invoice.date`](/docs/api/invoices/invoice-object#date) until payment for the invoice is due. - `po_number` (optional, string, max chars=100) Purchase Order Number for this invoice - `vat_number` (optional, string, max chars=20) VAT/ Tax registration number of the customer. [Learn more](https://www.chargebee.com/docs/tax.html#capture-tax-registration-number) - `price_type` (required, enumerated string, default=tax_exclusive) The price type of the invoice. Possible enum values: - `tax_exclusive` All amounts in the document are exclusive of tax. - `tax_inclusive` All amounts in the document are inclusive of tax. - `exchange_rate` (optional, bigdecimal, min=1E-9, max=999999999.999999999) 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. - `local_currency_exchange_rate` (optional, bigdecimal, min=1E-9, max=999999999.999999999) 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. - `currency_code` (required, string, max chars=3) The currency code (ISO 4217 format) for the invoice - `local_currency_code` (optional, string, max chars=3) The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. - `tax` (required, in cents, min=0) Total tax amount for this invoice - `sub_total` (required, in cents, min=0) 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[]](/docs/api/invoices/invoice-object#line_items).amount` - the sum of all `[line_item_discounts[]](/docs/api/invoices/invoice-object#line_item_discounts).discount_amount`. - `sub_total_in_local_currency` (optional, in cents, min=0) Invoice subtotal in the currency of the place of supply. - `total` (optional, in cents, min=0) 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` (optional, in cents, min=0) Total invoice amount in the currency of the place of supply. - `amount_due` (optional, in cents, min=0) The unpaid amount that is due on the invoice. This is calculated as: `[total](/docs/api/invoices/invoice-object#total)` - `[amount_paid](/docs/api/invoices/invoice-object#amount_paid)` - sum of `[applied_credits](/docs/api/invoices/invoice-object#applied_credits).applied_amount` - sum of `[adjustment_credit_notes](/docs/api/invoices/invoice-object#adjustment_credit_notes).cn_total` - sum of `[linked_taxes_withheld](/docs/api/invoices/invoice-object#linked_taxes_withheld).amount`. - `amount_adjusted` (optional, in cents, default=0, min=0) Total adjustments made against this invoice. - `amount_paid` (optional, in cents, min=0) Payments collected successfully for the invoice. This is the sum of `[linked_payments[].txn_amount](/docs/api/invoices/invoice-object#linked_payments)` for all `linked_payments[]` that have `txn_status` as `success`. - `paid_at` (optional, timestamp(UTC) in seconds) Timestamp indicating the date & time this invoice got paid. - `write_off_amount` (optional, in cents, default=0, min=0) Amount written off against this invoice. - `credits_applied` (optional, in cents, default=0, min=0) Total credits applied against this invoice. - `dunning_status` (optional, enumerated string) Current dunning status of the invoice. Possible enum values: - `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. - `next_retry_at` (optional, timestamp(UTC) in seconds) Timestamp indicating when will the next attempt to collect payment for this invoice occur. - `voided_at` (optional, timestamp(UTC) in seconds) Timestamp indicating the date & time this invoice got voided. - `resource_version` (optional, long) The version number of this resource. For every change made to the resource, `resource_version` is updated with a new timestamp in milliseconds. - `updated_at` (optional, timestamp(UTC) in seconds) 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_ - `line_items_next_offset` (optional, string, max chars=1000) 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](https://www.chargebee.com/docs/billing/2.0/kb/getting-started/how-to-contact-chargebees-support-team?utm_source=docs_api&utm_medium=content&utm_campaign=support) to enable this feature. - `first_invoice` (optional, boolean) 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. - `new_sales_amount` (optional, in cents, min=0) 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](https://www.chargebee.com/docs/2.0/consolidated-invoicing.html ) one, then it is the sum of all `line_items.amount` belonging to a new. - `has_advance_charges` (optional, boolean) Indicates whether an [advance charge](https://www.chargebee.com/docs/billing/2.0/invoices-credit-notes-and-quotes/advance-invoices) is present in this invoice. - `term_finalized` (required, boolean, default=true) Boolean indicating this invoice line\_items terms are finalized or not. - `is_gifted` (required, boolean, default=false) Boolean indicating this invoice is gifted or not. - `generated_at` (optional, timestamp(UTC) in seconds) 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. - `expected_payment_date` (optional, timestamp(UTC) in seconds) The date and time at which [dunning](https://www.chargebee.com/docs/payments/2.0/dunning-v2.html) should resume automatically for the invoice. This attribute is present only if dunning is currently [paused](/docs/api/invoices/pause-dunning-for-invoice) for the invoice. **See also**: [Dunning resumption process](/docs/api/invoices/resume-dunning-for-invoice). - `amount_to_collect` (optional, in cents, min=0) Payments that are yet to be collected for the invoice. This is determined as [`amount_due`](/docs/api/invoices/invoice-object#amount_due) - the sum of all [`linked_payments[txn_amount][i]`](/docs/api/invoices/invoice-object#linked_payments) where [`linked_payments[txn_status][i]`](/docs/api/invoices/invoice-object#linked_payments) is `in_progress`. - `round_off_amount` (optional, in cents, min=0) 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` . - `void_reason_code` (optional, string, max chars=100) 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 - `deleted` (required, boolean) Indicates that this resource has been deleted. - `tax_category` (optional, string) 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. - `vat_number_prefix` (optional, string, max chars=10) An overridden value for the first two characters of the [full VAT number](https://en.wikipedia.org/wiki/VAT_identification_number). Only applicable specifically for customers with `[billing_address](/docs/api/customers/customer-object#billing_address)` `country` as `XI` (which is **United Kingdom - Northern Ireland** ). When you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or have [manually enabled](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, you have the option of setting `[billing_address](/docs/api/customers/customer-object#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. - `channel` (optional, enumerated string) The subscription channel this object originated from and is maintained in. Possible enum values: - `web` The object was created (and is maintained) for the web channel directly in Chargebee via API or UI. - `app_store` The object data is synchronized with data from [in-app subscription(s)](/docs/api/in_app_subscriptions) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed. - `play_store` The object data is synchronized with data from [in-app subscription(s)](/docs/api/in_app_subscriptions) 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](mailto:eap@chargebee.com) for more information. - `business_entity_id` (optional, string, max chars=50) The unique ID of the [business entity](/docs/api/advanced-features) 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](/docs/api/invoices/invoice-object#customer_id) or the [subscription](/docs/api/invoices/invoice-object#subscription_id) respectively. - `brand_id` (optional, string, max chars=50) The unique ID of the [brand](/docs/api/brands) this invoice belongs to. Depending on whether the invoice was created directly for a customer or for a subscription, this is the brand of the customer or the subscription respectively. It is always inherited and cannot be set on the invoice itself. - `exchange_rates` (optional, list of exchange_rate) List of exchange rates applied when converting invoice amounts to other currencies (such as VAT local currency and organization local currency). Each entry contains [`currency_code`](/docs/api/invoices/invoice-object#exchange_rates_currency_code) and [`rate`](/docs/api/invoices/invoice-object#exchange_rates_rate). The invoice currency is the base currency. When multiple rates target the same currency, only one entry is returned. This array is different from [`exchange_rate`](/docs/api/invoices/invoice-object#exchange_rate) in the response. An entry whose `currency_code` matches [`local_currency_code`](/docs/api/invoices/invoice-object#local_currency_code) uses the same rate as [`local_currency_exchange_rate`](/docs/api/invoices/invoice-object#local_currency_exchange_rate). This array is returned in the response only when the corresponding features are enabled. - `currency_code` (required, string, max chars=3) Target currency for the conversion (ISO 4217). The invoice currency is the base currency. - `rate` (required, bigdecimal, min=1E-9, max=999999999.999999999) Exchange rate applied as: 1 `currency_code` = `rate` invoice currency. For example, when the invoice currency is `USD`, `currency_code` is `INR`, and `rate` is `0.010448403`, then 1 INR = 0.010448403 USD. - `discounts` (optional, list of discount) The list of all deductions applied to the invoice. - `amount` (required, in cents, min=0) The amount deducted. The format of this value depends on the [kind of currency](/docs/api/currencies) . - `description` (optional, string, max chars=250) Description for this deduction. - `line_item_id` (optional, string, max chars=40) The unique id of the line item that this deduction is for. Is required when `discounts[entity_type]` is `item_level_coupon` or `document_level_coupon` . - `entity_type` (required, enumerated string) The type of deduction and the amount to which it is applied. Possible enum values: - `item_level_coupon` The deduction is due to a coupon applied to line item. The coupon `id` is passed as `entity_id` . - `document_level_coupon` The deduction is due to a coupon applied to the invoice `sub_total`. The coupon id is passed as `entity_id` . - `promotional_credits` The deduction is due to a [promotional credit](/docs/api/promotional_credits) applied to the invoice. - `prorated_credits` The deduction is due to a legacy adjustment credit applied to the invoice. The `entity_id` is `null` in this case. The legacy credits feature is superseded by `[adjustment_credit_notes](/docs/api/invoices/invoice-object#adjustment_credit_notes)` . - `item_level_discount` The deduction is due to a [discount](/docs/api/discounts) applied to a line item of the invoice. The discount `id` is available as the `entity_id`. - `document_level_discount` The deduction is due to a [discount](/docs/api/discounts) applied to the invoice `sub_total`. The discount `id` is available as the `entity_id`. - `discount_type` (optional, enumerated string) The type of discount that is applied to the line item. Relevant only when `discounts[entity_type]` is one of `item_level_discount` , `item_level_coupon` , `document_level_discount` , or `document_level_coupon` Possible enum values: - `fixed_amount` when amount is applied as discount - `percentage` when percentage is applied as discount - `entity_id` (optional, string, max chars=100) When the deduction is due to a `coupon` or a `[discount](/docs/api/discounts)` , then this is the `id` of the coupon or discount. - `coupon_set_code` (optional, string, max chars=50) The [coupon code](/docs/api/coupon_codes/coupon_code-object#code) , if applicable, used to provide the discount. The [coupon.id](/docs/api/coupons/coupon-object#id) is available in `entity_id` . - `taxes` (optional, list of tax) The list of taxes applied for this invoice - `name` (required, string, max chars=100) The name of the tax applied. E.g. GST. - `amount` (required, in cents, min=0) The tax amount. - `description` (optional, string, max chars=250) Description of the tax item. - `tax_origin` (optional, tax_origin) 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. - `country` (optional, string, max chars=50) The country code in ([ISO 3166-1 alpha-2 format](https://www.iso.org/iso-3166-country-codes.html) ) where the tax originated from. - `registration_number` (optional, string, max chars=100) It represents the tax registration number for the entity used to collect tax. - `linked_taxes_withheld` (optional, list of linked_tax_withheld) Details of `tax_withheld` against this invoice. - `id` (required, string, max chars=40) An auto-generated unique identifier for the tax withheld. The value starts with the prefix `tax_wh_`. For example, `tax_wh_16BdDXSlbu4uV1Ee6` . - `amount` (optional, in cents, min=1) The amount withheld by the customer as tax from the invoice. The unit depends on the [type of currency](/docs/api/getting-started) . - `description` (optional, string, max chars=65k) The description for this tax withheld. - `date` (optional, timestamp(UTC) in seconds) Date or time associated with the tax withheld. - `reference_number` (optional, string, max chars=100) A unique external reference number for the tax withheld. Typically, this is the reference number used by the system you are integrating the API with. Depending on your integration, this could be the reference number issued by the taxation authority to identify the customer or the specific tax transaction. - `linked_payments` (optional, list of invoice_transaction) The list of transactions for this invoice - `txn_id` (required, string, max chars=40) Uniquely identifies the transaction. - `applied_amount` (required, in cents, min=0) The transaction amount applied to this invoice - `applied_at` (required, timestamp(UTC) in seconds) Timestamp at which the transaction is applied. - `txn_status` (optional, enumerated string) The status of this transaction. Possible enum values: - `in_progress` Transaction is being processed by the gateway. This typically happens for [direct debit transactions](https://www.chargebee.com/docs/direct-debit-payments.html) or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method. - `success` The transaction is successful. - `voided` The transaction got voided or authorization expired at gateway. - `failure` Transaction failed. Refer the 'error\_code' and 'error\_text' fields to know the reason for failure - `timeout` Transaction failed because of Gateway not accepting the connection. - `needs_attention` When connection with the Gateway gets terminated abruptly. For `needs_attention` status Chargebee automatically reconcile the transaction for few gateways, for rest of the gateways you have to use the [Reconcile transaction API](/docs/api/transactions/reconcile-transaction). You can use this API to update the `id_at_gateway` (Gateway Transaction ID) and `status` for a [`needs_attention`](/docs/api/transactions/transaction-object#status) transaction to be reconciled at par with the gateway. [Learn more](https://www.chargebee.com/docs/payments/2.0/needs-attention-transactions.html) about `needs_attention` transaction status - `late_failure` Indicates that a successful payment transaction has failed now due to a late failure notification from the payment gateway, typically caused by issues like insufficient funds or a closed bank account. - `txn_date` (optional, timestamp(UTC) in seconds) Indicates when this transaction occurred. - `txn_amount` (optional, in cents, min=0) Total amount of the transaction - `reference_transactions` (optional, list of reference_transaction) 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. - `applied_amount` (required, in cents, min=0) The amount from the transaction that was applied to the invoice. - `applied_at` (required, timestamp(UTC) in seconds) The time when the transaction was applied to the invoice, in seconds since the Unix epoch. - `txn_id` (required, string, max chars=40) The unique identifier for the transaction. - `txn_status` (optional, enumerated string) The status of the transaction. Possible enum values: - `in_progress` The transaction is being processed by the gateway. This typically occurs for [direct debit transactions](https://www.chargebee.com/docs/direct-debit-payments.html) or, for cards, refund transactions. Processing can take 2-7 days, depending on the gateway and payment method. - `success` The transaction was successful. - `voided` The transaction was voided, or the authorization expired at the gateway. - `failure` The transaction failed. Refer to the `error_code` and `error_text` fields for details about the failure. - `timeout` The transaction failed because the gateway did not accept the connection. - `needs_attention` The transaction could not be completed because the connection with the gateway was terminated unexpectedly. For some gateways, Chargebee automatically reconciles such transactions. For others, you must manually reconcile them by using the [Reconcile transaction API](/docs/api/transactions/reconcile-transaction). Use this API to update the `id_at_gateway` (gateway transaction ID) and `status`. [Learn more](https://www.chargebee.com/docs/payments/2.0/needs-attention-transactions.html) about `needs_attention` transactions. - `late_failure` A payment that was previously marked as successful has failed due to a late failure notification from the gateway. This can happen if the account had insufficient funds or was closed after the initial authorization. - `txn_date` (optional, timestamp(UTC) in seconds) The time when the transaction occurred, in seconds since the Unix epoch. - `txn_amount` (optional, in cents, min=0) The total amount of the transaction. - `txn_type` (required, enumerated string) The type of transaction. Possible enum values: - `authorization` The transaction is an authorization to capture the `[amount](/docs/api/transactions/transaction-object#amount)` from the customer's `[payment_source](/docs/api/payment_sources)` . - `payment` The transaction is a payment that captures the `[amount](/docs/api/transactions/transaction-object#amount)` from the customer's `[payment_source](/docs/api/payment_sources)` . - `refund` The transaction is a refund that returns the `[amount](/docs/api/transactions/transaction-object#amount)` to the customer's `[payment_source](/docs/api/payment_sources)` . - `payment_reversal` The transaction is a reversal of a previously captured payment. - `amount_capturable` (optional, in cents, default=0, min=0) This is the part of the authorized `amount` that is yet to be captured. The payment capture is recorded as a transaction of `type` = `payment`. Applicable only for a transaction of `type` = `authorization` . - `authorization_reason` (optional, enumerated string) Type of reason for the authorization transaction. Possible enum values: - `verification` The transaction was created to verify the payment method. - `blocking_funds` The transaction was created to block funds from the payment method. - `scheduled_capture` The transaction was authorized in advance for capture at a later time by a scheduled system job. The capture may succeed or fail, and its outcome is recorded as a linked transaction under `linked_payments` . - `dunning_attempts` (optional, list of dunning_attempt) The list of dunning\_attempts for this invoice - `attempt` (required, integer) Dunning attempt number. - `transaction_id` (optional, string, max chars=40) Transaction associated with attempt. - `dunning_type` (required, enumerated string, default=auto_collect) Types of dunning Possible enum values: - `auto_collect` Dunning type is auto collection. - `offline` Dunning type is offline. - `direct_debit` Dunning type is direct debit. - `real_time_payments` - `created_at` (optional, timestamp(UTC) in seconds) Timestamp at which the attempt was made. - `txn_status` (optional, enumerated string) The status of this transaction. Possible enum values: - `in_progress` Transaction is being processed by the gateway. This typically happens for [direct debit transactions](https://www.chargebee.com/docs/direct-debit-payments.html) or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method. - `success` The transaction is successful. - `voided` The transaction got voided or authorization expired at gateway. - `failure` Transaction failed. Refer the 'error\_code' and 'error\_text' fields to know the reason for failure - `timeout` Transaction failed because of Gateway not accepting the connection. - `needs_attention` When connection with the Gateway gets terminated abruptly. For `needs_attention` status Chargebee automatically reconcile the transaction for few gateways, for rest of the gateways you have to use the [Reconcile transaction API](/docs/api/transactions/reconcile-transaction). You can use this API to update the `id_at_gateway` (Gateway Transaction ID) and `status` for a [`needs_attention`](/docs/api/transactions/transaction-object#status) transaction to be reconciled at par with the gateway. [Learn more](https://www.chargebee.com/docs/payments/2.0/needs-attention-transactions.html) about `needs_attention` transaction status - `late_failure` Indicates that a successful payment transaction has failed now due to a late failure notification from the payment gateway, typically caused by issues like insufficient funds or a closed bank account. - `txn_amount` (optional, in cents, min=0) Total amount of the transaction - `retry_engine` (optional, enumerated string, default=chargebee) The payment retry system used for this dunning attempt. Possible enum values: - `chargebee` The attempt was processed by Chargebee Recovery. - `flexpay` The attempt was processed by FlexPay Recovery. - `successplus` GoCardless Success Plus. - `applied_credits` (optional, list of applied_credit) Refundable Credits applied on this invoice. - `cn_id` (required, string, max chars=50) Credit applied on the credit note ID. - `applied_amount` (required, in cents, min=0) Total credit amount applied to this invoice. - `applied_at` (required, timestamp(UTC) in seconds) Timestamp when the credit amount was applied to this invoice. - `cn_reason_code` (optional, enumerated string) Credit note reason code. Deprecated; use the cn\_create\_reason\_code parameter instead Possible enum values: - `write_off` This reason will be set automatically for the Credit Notes created during invoice [Write Off](https://www.chargebee.com/docs/invoice-operations.html#write-off) operation. - `subscription_change` This reason will be set automatically for Credit Notes created during Change Subscription operation when [proration](https://www.chargebee.com/docs/proration.html) is enabled - `subscription_cancellation` This reason will be set automatically for Credit Notes created during cancel subscription operation - `subscription_pause` This reason will be automatically set to credit notes created during pause/resume subscription operation. - `chargeback` Can be set when you are recording your customer Chargebacks - `product_unsatisfactory` Product Unsatisfactory - `service_unsatisfactory` Service Unsatisfactory - `order_change` Order Change - `order_cancellation` Order Cancellation - `waiver` Waiver - `other` Can be set when none of the above reason codes are applicable - `fraudulent` FRAUDULENT - `cn_create_reason_code` (optional, string, max chars=100) Credit note reason code - `cn_date` (optional, timestamp(UTC) in seconds) Indicates the date at which this credit note is created - `cn_status` (required, enumerated string) Credit note status. Possible enum values: - `adjusted` When the Credit Note has been adjusted against an invoice. - `refunded` When the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded). - `refund_due` When the credits are yet to be used, or have been partially used. - `voided` When the Credit Note has been cancelled. - `tax_application` (optional, enumerated string) Specifies how tax is handled for credits applied to this invoice. Possible enum values: - `pre_tax` Credits are applied before tax calculation. - `post_tax` Credits are applied after tax calculation. - `adjustment_credit_notes` (optional, list of created_credit_note) Adjustments created for this invoice - `cn_id` (required, string, max chars=50) Credit-note id - `cn_reason_code` (optional, enumerated string) Credit note reason code. Deprecated; use the cn\_create\_reason\_code parameter instead Possible enum values: - `write_off` This reason will be set automatically for the Credit Notes created during invoice [Write Off](https://www.chargebee.com/docs/invoice-operations.html#write-off) operation. - `subscription_change` This reason will be set automatically for Credit Notes created during Change Subscription operation when [proration](https://www.chargebee.com/docs/proration.html) is enabled - `subscription_cancellation` This reason will be set automatically for Credit Notes created during cancel subscription operation - `subscription_pause` This reason will be automatically set to credit notes created during pause/resume subscription operation. - `chargeback` Can be set when you are recording your customer Chargebacks - `product_unsatisfactory` Product Unsatisfactory - `service_unsatisfactory` Service Unsatisfactory - `order_change` Order Change - `order_cancellation` Order Cancellation - `waiver` Waiver - `other` Can be set when none of the above reason codes are applicable - `fraudulent` FRAUDULENT - `cn_create_reason_code` (optional, string, max chars=100) Credit note reason code - `cn_date` (optional, timestamp(UTC) in seconds) Indicates the date at which this credit note is created - `cn_total` (optional, in cents, default=0, min=0) Total amount of the credit note. - `cn_status` (required, enumerated string) Credit note status. Possible enum values: - `adjusted` When the Credit Note has been adjusted against an invoice. - `refunded` When the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded). - `refund_due` When the credits are yet to be used, or have been partially used. - `voided` When the Credit Note has been cancelled. - `issued_credit_notes` (optional, list of created_credit_note) Credit notes issued for this invoice - `cn_id` (required, string, max chars=50) Credit-note id - `cn_reason_code` (optional, enumerated string) Credit note reason code. Deprecated; use the cn\_create\_reason\_code parameter instead Possible enum values: - `write_off` This reason will be set automatically for the Credit Notes created during invoice [Write Off](https://www.chargebee.com/docs/invoice-operations.html#write-off) operation. - `subscription_change` This reason will be set automatically for Credit Notes created during Change Subscription operation when [proration](https://www.chargebee.com/docs/proration.html) is enabled - `subscription_cancellation` This reason will be set automatically for Credit Notes created during cancel subscription operation - `subscription_pause` This reason will be automatically set to credit notes created during pause/resume subscription operation. - `chargeback` Can be set when you are recording your customer Chargebacks - `product_unsatisfactory` Product Unsatisfactory - `service_unsatisfactory` Service Unsatisfactory - `order_change` Order Change - `order_cancellation` Order Cancellation - `waiver` Waiver - `other` Can be set when none of the above reason codes are applicable - `fraudulent` FRAUDULENT - `cn_create_reason_code` (optional, string, max chars=100) Credit note reason code - `cn_date` (optional, timestamp(UTC) in seconds) Indicates the date at which this credit note is created - `cn_total` (optional, in cents, default=0, min=0) Total amount of the credit note. - `cn_status` (required, enumerated string) Credit note status. Possible enum values: - `adjusted` When the Credit Note has been adjusted against an invoice. - `refunded` When the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded). - `refund_due` When the credits are yet to be used, or have been partially used. - `voided` When the Credit Note has been cancelled. - `linked_orders` (optional, list of linked_order) The list of orders for this invoice - `id` (required, string, max chars=40) Uniquely identifies the order. It is the api identifier for the order - `document_number` (optional, string, max chars=50) The order's serial number - `status` (optional, enumerated string, default=new) The status of this order. Possible enum values: - `new` Order has been created. Applicable only if you are using Chargebee's legacy order management system. - `processing` Order is being processed. Applicable only if you are using Chargebee's legacy order management system - `complete` Order has been processed successfully. Applicable only if you are using Chargebee's legacy order management system - `cancelled` Order has been cancelled. Applicable only if you are using Chargebee's legacy order management system - `voided` Order has been voided. Applicable only if you are using Chargebee's legacy order management system - `queued` Order is yet to be processed by any system, these are scheduled orders created by Chargebee - `awaiting_shipment` The order has been picked up by an integration system, and synced to a shipping management platform - `on_hold` The order is paused from being processed. - `delivered` The order has been delivered to the customer. - `shipped` The order has moved from order management system to a shipping system. - `partially_delivered` The order has been partially delivered to the customer. - `returned` The order has been returned after delivery. - `order_type` (optional, enumerated string) Order type Possible enum values: - `manual` The order has been created by the user using Chargebee's legacy order management system. - `system_generated` The order has been created by Chargebee automatically based on the preferences set by the user. - `reference_id` (optional, string, max chars=50) Reference id can be used to map the orders in the shipping/order management application to the orders in ChargeBee. The reference\_id generally is same as the order id in the third party application. - `fulfillment_status` (optional, string, max chars=50) The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc; - `batch_id` (optional, string, max chars=50) Unique id to identify a group of orders. - `created_at` (required, timestamp(UTC) in seconds) The time at which the order was created - `notes` (optional, list of note) The list of [notes](https://www.chargebee.com/docs/2.0/invoice_notes.html) 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_note` parameter for various endpoints in the API that also create invoices. For example, [creating a subscription](/docs/api/subscriptions/create-subscription-for-items#invoice_notes), [creating an invoice](/docs/api/invoices/create-invoice-for-items-and-one-time-charges), and [closing a pending invoice](/docs/api/invoices/close-a-pending-invoice#invoice_note). - **General note:** This note is added to all invoices of the Chargebee site. You can [add/edit](https://www.chargebee.com/docs/invoice_notes.html#adding-general-notes) this note in the Chargebee admin console. - `note` (required, string, max chars=65k) Actual note. - `entity_id` (optional, string, max chars=100) Unique identifier of the entity. - `entity_type` (optional, enumerated string) Type of entity to which the note belongs. Possible enum values: - `coupon` Entity that represents a coupon. - `subscription` Entity that represents a subscription of customer. - `customer` Entity that represents a customer. - `plan_item_price` Indicates that this line item is based on plan Item Price - `addon_item_price` Indicates that this line item is based on addon Item Price - `charge_item_price` Indicates that this line item is based on charge Item Price - `tax` The note is configured as part of the [tax configuration](https://www.chargebee.com/docs/tax.html) in Chargebee Billing. - `shipping_address` (optional, shipping_address) Shipping address for the invoice. - `first_name` (optional, string, max chars=150) The first name of the contact. - `last_name` (optional, string, max chars=150) The last name of the contact. - `email` (optional, string, max chars=70) The email address. - `company` (optional, string, max chars=250) The company name. - `phone` (optional, string, max chars=50) The phone number. - `line1` (optional, string, max chars=150) Address line 1 - `line2` (optional, string, max chars=150) Address line 2 - `line3` (optional, string, max chars=150) Address line 3 - `city` (optional, string, max chars=50) The name of the city. - `state_code` (optional, string, max chars=50) The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search) without the country prefix. Currently supported for USA, Canada, India and UAE. 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` ). For Dubai (UAE), set as `DU` (not `AE-DU` ). - `state` (optional, string, max chars=50) The state/province name. - `country` (optional, string, max chars=50) The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) . **Note**: If you enter an invalid country code, the system will return an error. **Brexit** If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option. - `zip` (optional, string, max chars=20) Zip or postal code. The number of characters is validated according to the rules [specified here](https://chromium-i18n.appspot.com/ssl-address) . - `validation_status` (optional, enumerated string, default=not_validated) The address verification status. Possible enum values: - `not_validated` Address is not yet validated. - `valid` Address was validated successfully. - `partially_valid` The address is valid for taxability but has not been validated for shipping. - `invalid` Address is invalid. - `billing_address` (optional, billing_address) Billing address for the invoice. - `first_name` (optional, string, max chars=150) The first name of the billing contact. - `last_name` (optional, string, max chars=150) The last name of the billing contact. - `email` (optional, string, max chars=70) The email address. - `company` (optional, string, max chars=250) The company name. - `phone` (optional, string, max chars=50) The phone number. - `line1` (optional, string, max chars=150) Address line 1 - `line2` (optional, string, max chars=150) Address line 2 - `line3` (optional, string, max chars=150) Address line 3 - `city` (optional, string, max chars=50) The name of the city. - `state_code` (optional, string, max chars=50) The [ISO 3166-2 state/province code](https://www.iso.org/obp/ui/#search) without the country prefix. Currently supported for USA, Canada, India and UAE. 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` ). For Dubai (UAE), set as `DU` (not `AE-DU` ). - `state` (optional, string, max chars=50) State or Province - `country` (optional, string, max chars=50) The billing address country of the customer. Must be one of [ISO 3166 alpha-2 country code](https://www.iso.org/iso-3166-country-codes.html) . **Note**: If you enter an invalid country code, the system will return an error. **Brexit** If you have enabled [EU VAT](https://www.chargebee.com/docs/eu-vat.html) in 2021 or later, or have [manually enable](https://www.chargebee.com/docs/brexit.html#what-needs-to-be-done-in-chargebee) the Brexit configuration, then `XI` (the code for **United Kingdom - Northern Ireland**) is available as an option. - `zip` (optional, string, max chars=20) Zip or postal code. The number of characters is validated according to the rules [specified here](https://chromium-i18n.appspot.com/ssl-address) . - `validation_status` (optional, enumerated string, default=not_validated) The address verification status. Possible enum values: - `not_validated` Address is not yet validated. - `valid` Address was validated successfully. - `partially_valid` The address is valid for taxability but has not been validated for shipping. - `invalid` Address is invalid. - `statement_descriptor` (optional, statement_descriptor) Statement descriptor for the invoice. - `id` (required, string, max chars=40) Uniquely identifies a statement\_descriptor - `descriptor` (optional, string, max chars=65k) Payment descriptor text - `einvoice` (optional, einvoice) 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. - `id` (required, string, max chars=50) The unique `id` for the e-invoice. This is auto-generated by Chargebee. - `reference_id` (optional, string, max chars=50) Identifier returned by the connected e-invoicing provider for this submission (for example, a document submission id). Chargebee uses this value when communicating with the provider to retrieve submission status and related artifacts. - `reference_number` (optional, string, max chars=100) This attribute 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. - `status` (required, enumerated string) The status of processing the e-invoice. To obtain detailed information about the current `status` , see `message` . Possible enum values: - `scheduled` Sending the e-invoice to the customer has been scheduled. - `skipped` The e-invoice was not sent. This could be due to missing information or because the `entity_identifier` is not registered on the e-invoicing network. - `in_progress` The e-invoice has been sent and Chargebee is waiting for confirmation from the receiving entity. - `success` The e-invoice has been successfully delivered to the customer. - `failed` The e-invoice was sent and there was an error due to which it was not delivered. - `registered` The e-invoice was sent and there was an error due to which it was not delivered but got cleared in the IRP. - `accepted` The e-invoice was sent and it was accepted by the receiving entity. The sending entity shall also accept the e-invoice. - `rejected` The e-invoice was sent and it was rejected by the receiving entity due to some reason. The sending entity shall also reject the e-invoice. - `message_acknowledgement` An acknowledgment confirming that the application response was successfully received by the receiving entity. - `in_process` The e-invoice is currently being processed by the receiving entity. - `under_query` The receiving entity has raised a query regarding the e-invoice. Additional information or clarification is required before proceeding. - `conditionally_accepted` The e-invoice has been accepted with conditions. - `paid` The receiving entity has confirmed that the e-invoice has been paid. - `message` (optional, string, max chars=3000) Detailed information about the status of the e-invoice. When `status` is `skipped` or `failed` , this contains the reason or error details. The following are some valid examples: - Invoice successfully sent to customer via the e-invoicing network 9090:123456 - Invoice successfully sent to customer via email id abc@acme.com - `provider_references` (optional) List of key-value pairs from the e-invoicing provider (e.g. Receipt Message ID). - `site_details_at_creation` (optional, site_details_at_creation) It contains site-specific information, including timezone and organisational address. - `timezone` (optional, string, max chars=50) It represents the timezone of the site at the time of entity creation. - `organization_address` (optional, jsonobject) It represents the address configured for the site during entity creation. Includes `currency_code` (ISO 4217): the currency of the organisation address country at creation time.