# Invoices > For the complete machine-readable documentation index, see [llms.txt](https://apidocs.chargebee.com/llms.txt). 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](/docs/api/invoices/invoice-object#line_items) _subscription\_id_ attribute should be referred. ## Sample Invoice ```json { "amount": 200, "amount_adjusted": 0, "amount_due": 0, "amount_paid": 200, "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__3Nl7obaRNQyaXr1S", "end_date": 1517492040, "first_invoice": true, "id": "__demo_inv__13", "line_items": [ { "amount": 200, "date_from": 1517492040, "date_to": 1517492040, "description": "non_recurring_addon", "entity_id": "non_recurring_addon", "entity_type": "addon", "is_taxed": false, "object": "line_item", "quantity": 2, "tax": 0, "type": "charge", "unit_amount": 100 }, {..} ], "linked_orders": {}, "linked_transactions": [ { "applied_amount": 200, "applied_at": 1517492041, "txn_amount": 200, "txn_date": 1517492041, "txn_id": "txn___test__3Nl7obaRNQyacB1a", "txn_status": "success", "txn_type": "payment" }, {..} ], "object": "invoice", "paid_on": 1517492041, "price_type": "tax_exclusive", "recurring": false, "start_date": 1517492040, "status": "paid", "sub_total": 200, "tax": 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. - `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\_items](/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. - `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. - `start_date` (required, timestamp(UTC) in seconds) Start date of the invoice. - `end_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. - `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. - `currency_code` (required, string, max chars=3) The currency code (ISO 4217 format) for the invoice - `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[].discount_amount](/docs/api/invoices/invoice-object#line_item_discounts)`. - `amount` (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. - `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_on` (optional, timestamp(UTC) in seconds) Timestamp indicating the date & time this invoice got paid. - `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` (optional, timestamp(UTC) in seconds) Timestamp indicating when will the next attempt to collect payment for this invoice occur. - `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. - `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. - `type` (required, enumerated string) Type of this Discount lineitem Possible enum values: - `coupon` Represents the coupon discount items in invoice. Further the 'entity\_id' attribute specifies the [coupon](/docs/api/coupons/coupon-object) id this discount is based on - `credit_adjustment` Represents the Prorated Credits items in invoice. The 'entity\_id' attribute will be null in this case - `account_credits` Represents the Promotional Credits item in invoice. The 'entity\_id' attribute will be null in this case - `entity_id` (optional, string, max chars=100) When the deduction is due to a `coupon` , then this is the `id` of the coupon. - `taxes` (optional, list of tax) The list of taxes applied for this invoice - `amount` (required, in cents, min=0) The tax amount. - `description` (optional, string, max chars=250) Description of the tax item. - `linked_transactions` (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_type` (required, enumerated string) Type of the transaction. Possible enum values: - `authorization` The transaction represents an authorization for capturing the `[amount](/docs/api/transactions/transaction-object#amount)` from the customer's `[payment_source](/docs/api/payment_sources)` . - `payment` The transaction represents capture of `[amount](/docs/api/transactions/transaction-object#amount)` from the customer's `[payment_source](/docs/api/payment_sources)` . - `refund` The transaction represents a refund of `[amount](/docs/api/transactions/transaction-object#amount)` to the customer's `[payment_source](/docs/api/payment_sources)` . - `payment_reversal` Indicates a reversal transaction. - `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` Connection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually - `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 - `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 - `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 - `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: - `plan` Entity that represents a plan. - `addon` Entity that represents an addon. - `coupon` Entity that represents a coupon. - `subscription` Entity that represents a subscription of customer. - `customer` Entity that represents a customer. - `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) . - `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) .