API Version
Product Catalog
Library

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_due and 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 paid and 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 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, "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 }

API Index URL GET

https://{site}.chargebee.com/api/v2/invoices

Model Class

id
string, max chars=50
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
po_number
optional, string, max chars=100
Purchase Order Number for this invoice
customer_id
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_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.

recurring
boolean, default=true
Boolean indicating whether this invoice belongs to a subscription
status
enumerated string
Current status of this invoice.
Possible values are
paidIndicates a paid invoice.postedIndicates the payment is not yet collected and will be in this state till the due date to indicate the due periodpayment_dueIndicates the payment is not yet collected and is being retried as per retry settings.not_paidIndicates the payment is not made and all attempts to collect is failed.
Show all values[+]
vat_number
optional, string, max chars=20
VAT/ Tax registration number of the customer. Learn more
price_type
enumerated string, default=tax_exclusive
The price type of the invoice.
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
Show all values[+]
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
Number of days within which the invoice has to be paid
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. To calculate the exchange rate utilized for VAT in local currency, you may use the following formula.
Exchange rate = tax_amount_in_local_currency / tax_amount


currency_code
string, max chars=3
The currency code (ISO 4217 format) for the invoice
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.
amount_paid
optional, in cents, min=0
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_adjusted
optional, in cents, default=0, min=0
Total adjustments made against this invoice.
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.
amount_due
optional, in cents, min=0
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.
paid_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got paid.
dunning_status
optional, enumerated string
Current dunning status of the invoice.
Possible values are
in_progressDunning is still in progress.exhaustedMaximum number of attempts have been made.stoppedDunning has stopped for this invoice.successPayment successfully collected during dunning process.
Show all values[+]
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

sub_total
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[].amount - the sum of all 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_in_local_currency
optional, in cents, min=0
Total invoice amount in the currency of the place of supply.
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
in cents, min=0
Total tax amount for this invoice
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.
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 one, then it is the sum of all line_items.amount belonging to a new.
has_advance_charges
optional, boolean
Boolean indicating any advance charge is present in this invoice.
term_finalized
boolean, default=true
Boolean indicating this invoice line_items terms are finalized or not.
is_gifted
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
Expected payment date recorded for this invoice.
amount_to_collect
optional, in cents, min=0
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.
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.
payment_owner
optional, string, max chars=50
Payment owner of an invoice
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
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. 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.

channel
optional, enumerated string
The subscription channel this object originated from and is maintained in.
Possible values are
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe 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.play_storeThe 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.
Show all values[+]
business_entity_id
optional, string, max chars=50
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.
optional, list of line_item
The list of line items for this invoice
optional, list of discount
The list of all deductions applied to the invoice.
line_item_discounts
Show attributes [+]
optional, list of line_item_discount
The list of deduction(s) applied for each line item of this invoice
optional, list of tax
The list of taxes applied for this invoice
line_item_taxes
Show attributes [+]
optional, list of line_item_tax
The list of taxes applied on line items
line_item_tiers
Show attributes [+]
optional, list of line_item_tier
The list of tiers applicable for this line item
linked_payments
Show attributes [+]
optional, list of invoice_transaction
The list of transactions for this invoice
dunning_attempts
Show attributes [+]
optional, list of dunning_attempt
The list of dunning_attempts for this invoice
applied_credits
Show attributes [+]
optional, list of applied_credit
Refundable Credits applied on this invoice.
adjustment_credit_notes
Show attributes [+]
optional, list of created_credit_note
Adjustments created for this invoice
issued_credit_notes
Show attributes [+]
optional, list of created_credit_note
Credit notes issued for this invoice
linked_orders
Show attributes [+]
optional, list of linked_order
The list of orders for this invoice
optional, list of note
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:
shipping_address
Show attributes [+]
optional, shipping_address
Shipping address for the invoice.
statement_descriptor
Show attributes [+]
optional, statement_descriptor
Statement descriptor for the invoice.
billing_address
Show attributes [+]
optional, billing_address
Billing address for the invoice.
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.
linked_taxes_withheld
Show attributes [+]
optional, list of linked_tax_withheld
Details of tax_withheld against this invoice.
id id
string, max chars=50
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
po_number po_number
optional, string, max chars=100
Purchase Order Number for this invoice
customer_id customer_id
string, max chars=50
The identifier of the customer this invoice belongs to.
subscription_id 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 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 recurring
boolean, default=true
Boolean indicating whether this invoice belongs to a subscription
status status
enumerated string
Current status of this invoice.
vat_number vat_number
optional, string, max chars=20
VAT/ Tax registration number of the customer. Learn more
price_type price_type
enumerated string, default=tax_exclusive
The price type of the invoice.
date 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 due_date
optional, timestamp(UTC) in seconds
Due date of the invoice
net_term_days net_term_days
optional, integer, default=0
Number of days within which the invoice has to be paid
exchange_rate 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. To calculate the exchange rate utilized for VAT in local currency, you may use the following formula.
Exchange rate = tax_amount_in_local_currency / tax_amount


currency_code currency_code
string, max chars=3
The currency code (ISO 4217 format) for the invoice
total 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.
amount_paid amount_paid
optional, in cents, min=0
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_adjusted amount_adjusted
optional, in cents, default=0, min=0
Total adjustments made against this invoice.
write_off_amount write_off_amount
optional, in cents, default=0, min=0
Amount written off against this invoice.
credits_applied credits_applied
optional, in cents, default=0, min=0
Total credits applied against this invoice.
amount_due amount_due
optional, in cents, min=0
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.
paid_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got paid.
dunning_status dunning_status
optional, enumerated string
Current dunning status of the invoice.
next_retry_at next_retry_at
optional, timestamp(UTC) in seconds
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
voided_at voided_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got voided.
resource_version 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 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

sub_total sub_total
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[].amount - the sum of all line_item_discounts[].discount_amount.
sub_total_in_local_currency sub_total_in_local_currency
optional, in cents, min=0
Invoice subtotal in the currency of the place of supply.
total_in_local_currency total_in_local_currency
optional, in cents, min=0
Total invoice amount in the currency of the place of supply.
local_currency_code 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 tax
in cents, min=0
Total tax amount for this invoice
local_currency_exchange_rate 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.
first_invoice 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 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 one, then it is the sum of all line_items.amount belonging to a new.
has_advance_charges has_advance_charges
optional, boolean
Boolean indicating any advance charge is present in this invoice.
term_finalized term_finalized
boolean, default=true
Boolean indicating this invoice line_items terms are finalized or not.
is_gifted is_gifted
boolean, default=false
Boolean indicating this invoice is gifted or not.
generated_at 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 expected_payment_date
optional, timestamp(UTC) in seconds
Expected payment date recorded for this invoice.
amount_to_collect amount_to_collect
optional, in cents, min=0
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.
round_off_amount 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.
payment_owner payment_owner
optional, string, max chars=50
Payment owner of an invoice
void_reason_code 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 deleted
boolean
Indicates that this resource has been deleted.
tax_category 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 vat_number_prefix
optional, string, max chars=10
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.

channel channel
optional, enumerated string
The subscription channel this object originated from and is maintained in.
business_entity_id business_entity_id
optional, string, max chars=50
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.
line_items
optional, list of line_item
The list of line items for this invoice
discounts
optional, list of discount
The list of all deductions applied to the invoice.
line_item_discounts
optional, list of line_item_discount
The list of deduction(s) applied for each line item of this invoice
taxes
optional, list of tax
The list of taxes applied for this invoice
line_item_taxes
optional, list of line_item_tax
The list of taxes applied on line items
line_item_tiers
optional, list of line_item_tier
The list of tiers applicable for this line item
linked_payments
optional, list of invoice_transaction
The list of transactions for this invoice
dunning_attempts
optional, list of dunning_attempt
The list of dunning_attempts for this invoice
applied_credits
optional, list of applied_credit
Refundable Credits applied on this invoice.
adjustment_credit_notes
optional, list of created_credit_note
Adjustments created for this invoice
issued_credit_notes
optional, list of created_credit_note
Credit notes issued for this invoice
linked_orders
optional, list of linked_order
The list of orders for this invoice
notes
optional, list of note
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:
shipping_address
optional, shipping_address
Shipping address for the invoice.
statement_descriptor
optional, statement_descriptor
Statement descriptor for the invoice.
billing_address
optional, billing_address
Billing address for the invoice.
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.
linked_taxes_withheld
optional, list of linked_tax_withheld
Details of tax_withheld against this invoice.

Creates an invoice for charge-items and one-time charges. The item prices must belong to items of type charge.

Notes

One-time charges are represented in an invoice as line_items with entity_type adhoc.

Sample Request
# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges \
     -u {site_api_key}:\
     -d customer_id="__test__KyVkkWS1xLskm8" \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US" 
     -d item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "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,
        "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
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges

Method

customer_id[]
optional, string, max chars=50

Unique ID of the customer this invoice should be created for. Either this or subscription_id must be provided.

Note

The invoice is linked to the same business entity as this customer.

.
subscription_id[]
optional, string, max chars=50

Unique ID of the subscription this invoice should be created for. Either this or customer_id must be provided.

Note

The invoice is linked to the same business entity as this subscription.

.
currency_code[]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the invoice amount.
invoice_note[]
optional, string, max chars=2000
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
remove_general_note[]
optional, boolean, default=false
Set as true to remove the general note from this invoice.
po_number[]
optional, string, max chars=100
Purchase Order Number for this invoice.
coupon_ids[[0..n]][0..n]
optional, list of string
List of Coupons to be added.
authorization_transaction_id[]
optional, string, max chars=40
Authorization transaction to be captured.
payment_source_id[]
optional, string, max chars=40
Payment source to be used for this payment.
auto_collection[]
optional, enumerated string
If specified, the customer level auto collection will be overridden.
Possible values are
onWhenever an invoice is created, an automatic attempt will be made to charge.offWhenever an invoice is created as payment due.
Show all values[+]
invoice_date[]
optional, timestamp(UTC) in seconds
The document date displayed on the invoice PDF. By default, it is the date of creation of the invoice or, when Metered Billing is enabled, it can be the date of closing the invoice. Provide this value to backdate the invoice (set the invoice date to a value in the past). Backdating an invoice is done for reasons such as booking revenue for a previous date or when the non-recurring charge is effective as of a past date. taxes and line_item_taxes are computed based on the tax configuration as of this date. The date should not be more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
token_id[]
optional, string, max chars=40
Token generated by Chargebee JS representing payment method details.
replace_primary_payment_source[]
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
retain_payment_source[]
optional, boolean, default=true
Indicates whether the payment source should be retained for the customer.
payment_initiator[]
optional, enumerated string
The type of initiator to be used for the payment request triggered by this operation.
Possible values are
customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
Show all values[+]
shipping_address[first_name]
optional, string, max chars=150
shipping_address[last_name]
optional, string, max chars=150
shipping_address[email]
optional, string, max chars=70
shipping_address[company]
optional, string, max chars=250
shipping_address[phone]
optional, string, max chars=50
shipping_address[line1]
optional, string, max chars=150
shipping_address[line2]
optional, string, max chars=150
shipping_address[line3]
optional, string, max chars=150
shipping_address[city]
optional, string, max chars=50
shipping_address[state_code]
optional, string, max chars=50
shipping_address[state]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
shipping_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
statement_descriptor[descriptor]
optional, string, max chars=65k
statement_descriptor[additional_info]
optional, string, max chars=65k
card[gateway_account_id]
optional, string, max chars=50
card[first_name]
optional, string, max chars=50
card[last_name]
optional, string, max chars=50
card[number]
required if card provided, string, max chars=1500
card[expiry_month]
required if card provided, integer, min=1, max=12
card[expiry_year]
required if card provided, integer
card[cvv]
optional, string, max chars=520
card[billing_addr1]
optional, string, max chars=150
card[billing_addr2]
optional, string, max chars=150
card[billing_city]
optional, string, max chars=50
card[billing_state_code]
optional, string, max chars=50
card[billing_state]
optional, string, max chars=50
card[billing_zip]
optional, string, max chars=20
card[billing_country]
optional, string, max chars=50
card[additional_information]
optional, jsonobject
bank_account[gateway_account_id]
optional, string, max chars=50
bank_account[iban]
optional, string, min chars=10, max chars=50
bank_account[first_name]
optional, string, max chars=150
bank_account[last_name]
optional, string, max chars=150
bank_account[company]
optional, string, max chars=250
bank_account[email]
optional, string, max chars=70
bank_account[phone]
optional, string, max chars=50
bank_account[bank_name]
optional, string, max chars=100
bank_account[account_number]
optional, string, min chars=4, max chars=17
bank_account[routing_number]
optional, string, min chars=3, max chars=9
bank_account[bank_code]
optional, string, max chars=20
bank_account[account_type]
optional, enumerated string
Possible values are
checkingChecking AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent Account
Show all values[+]
bank_account[account_holder_type]
optional, enumerated string
Possible values are
individualIndividual Account.companyCompany Account.
Show all values[+]
bank_account[echeck_type]
optional, enumerated string
Possible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
Show all values[+]
bank_account[issuing_country]
optional, string, max chars=50
bank_account[swedish_identity_number]
optional, string, min chars=10, max chars=12
bank_account[billing_address]
optional, jsonobject
payment_method[type]
optional, enumerated string
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
payment_method[reference_id]
optional, string, max chars=200
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
payment_method[issuing_country]
optional, string, max chars=50
payment_method[additional_information]
optional, jsonobject
payment_intent[id]
optional, string, max chars=150
payment_intent[gateway_account_id]
required if payment intent token provided, string, max chars=50
payment_intent[gw_token]
optional, string, max chars=65k
payment_intent[payment_method_type]
optional, enumerated string
Possible values are
cardcardidealidealsofortsofortbancontactbancontact
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
payment_intent[additional_information]
optional, jsonobject
item_prices[item_price_id][0..n]
optional, string, max chars=100
item_prices[quantity][0..n]
optional, integer, min=1
item_prices[quantity_in_decimal][0..n]
optional, string, max chars=33
item_prices[unit_price][0..n]
optional, in cents, min=0
item_prices[unit_price_in_decimal][0..n]
optional, string, max chars=39
item_prices[date_from][0..n]
optional, timestamp(UTC) in seconds
item_prices[date_to][0..n]
optional, timestamp(UTC) in seconds
item_tiers[item_price_id][0..n]
optional, string, max chars=100
item_tiers[starting_unit][0..n]
optional, integer, min=1
item_tiers[ending_unit][0..n]
optional, integer
item_tiers[price][0..n]
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
optional, string, max chars=39
charges[amount][0..n]
optional, in cents, min=1
charges[amount_in_decimal][0..n]
optional, string, max chars=39
charges[description][0..n]
optional, string, max chars=250
charges[taxable][0..n]
optional, boolean, default=true
charges[tax_profile_id][0..n]
optional, string, max chars=50
charges[avalara_tax_code][0..n]
optional, string, max chars=50
charges[hsn_code][0..n]
optional, string, max chars=50
charges[taxjar_product_code][0..n]
optional, string, max chars=50
charges[avalara_sale_type][0..n]
optional, enumerated string
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
Show all values[+]
charges[avalara_transaction_type][0..n]
optional, integer
charges[avalara_service_type][0..n]
optional, integer
charges[date_from][0..n]
optional, timestamp(UTC) in seconds
charges[date_to][0..n]
optional, timestamp(UTC) in seconds
charges[discount_amount][0..n]
optional, in cents, min=0
charges[discount_percentage][0..n]
optional, double, min=0.01, max=100.0
notes_to_remove[entity_type][0..n]
optional, enumerated string
Possible values are
customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Price
Show all values[+]
notes_to_remove[entity_id][0..n]
optional, string, max chars=100
discounts[percentage][0..n]
optional, double, min=0.01, max=100.0
discounts[amount][0..n]
optional, in cents, min=0
discounts[apply_on][0..n]
required, enumerated string
Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
Show all values[+]
discounts[item_price_id][0..n]
optional, string, max chars=100
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API is used to stop dunning for "Payment Due" invoices that have been enabled for Auto Collection. When dunning is stopped, the status of the invoice will be changed to "Not Paid".

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/stop_dunning \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1000,
        "amount_paid": 0,
        "amount_to_collect": 1000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aspTSOcUcz72s",
        "date": 1612796988,
        "deleted": false,
        "due_date": 1612796988,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796989,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8aspTSOcUezv3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aspTSOcUcz72s",
                "date_from": 1612796988,
                "date_to": 1612883388,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8aspTSOcUex03u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8aspTSOcUcz72s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612796989,
                "txn_amount": 1000,
                "txn_date": 1612796989,
                "txn_id": "txn___test__8aspTSOcUezv3v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490593188,
        "round_off_amount": 0,
        "status": "not_paid",
        "sub_total": 1000,
        "subscription_id": "__test__8aspTSOcUcz72s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490593,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/stop_dunning

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Imports an invoice into Chargebee Billing. This endpoint allows you to import an invoice from external systems, such as accounting software, into Chargebee.

Caution: Importing Current-Term Invoices

To ensure accurate proration for any changes to the subscription in the current term, only import one current term invoice. Chargebee considers only the first imported invoice for the current term when calculating proration. If there are multiple invoices for the current term in the source system, consolidate them into a single invoice before importing it into Chargebee.

This API is not enabled for live sites by default. Please contact support to get this enabled.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}:\
     -d id="old_inv_001" \
     -d customer_id="__test__8asyKSOcTJGo2N" \
     -d subscription_id="__test__8asyKSOcTJMw2U" \
     -d date=1517490271 \
     -d total=4900 \
     -d status="PAYMENT_DUE" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" 
     -d line_items[date_from][1]=1517490271 \
     -d line_items[date_to][1]=1519909471 \
     -d line_items[description][1]="Standard" \
     -d line_items[unit_amount][1]=4900 \
     -d line_items[quantity][1]=1 \
     -d line_items[entity_type][1]="PLAN_ITEM_PRICE" \
     -d line_items[entity_id][1]="standard-USD" 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 4900,
        "amount_paid": 0,
        "amount_to_collect": 4900,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "validation_status": "not_validated",
            "zip": "91789"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTJGo2N",
        "date": 1517490271,
        "deleted": false,
        "due_date": 1517490271,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "old_inv_001",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 4900,
                "customer_id": "__test__8asyKSOcTJGo2N",
                "date_from": 1517490271,
                "date_to": 1519909471,
                "description": "Standard",
                "discount_amount": 0,
                "entity_id": "standard-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asyKSOcTJYG2e",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asyKSOcTJMw2U",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 4900
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490271788,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 4900,
        "subscription_id": "__test__8asyKSOcTJMw2U",
        "tax": 0,
        "term_finalized": true,
        "total": 4900,
        "updated_at": 1517490271,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/import_invoice

Method

id[]
required, string, max chars=50
Invoice Number.
currency_code[]
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for the invoice.
customer_id[]
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created.
subscription_id[]
optional, string, max chars=50
If recurring items are present in line items then subscription id is required.
po_number[]
optional, string, max chars=100
Purchase Order Number for this invoice.
price_type[]
optional, enumerated string, default=tax_exclusive
The price type of the invoice.
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
Show all values[+]
tax_override_reason[]
optional, enumerated string
The reason for exempting the invoice from tax. (Applicable only for exempted invoices.).
Possible values are
id_exemptThe customer is from a different country than your business and they have a valid VAT number or, the customer is a business entity. (This reason is only applicable when EU VAT or UK VAT is enabled.)customer_exemptThe customer is exempted from tax.exportThe customer is from a non-taxable region or the billing address and shipping address are unavailable.
Show all values[+]
vat_number[]
optional, string, max chars=20
Vat Number. Required if this invoice is VAT exempted.
vat_number_prefix[]
optional, string, max chars=10
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.
date[]
required, timestamp(UTC) in seconds
Date when invoice raised.
total[]
required, in cents, min=0
Invoice total amount.
round_off[]
optional, in cents, min=-99, max=99
Round off amount.
status[]
optional, enumerated string
Current status of this invoice.
Possible values are
paidIndicates a paid invoice.postedIndicates the payment is not yet collected and will be in this state till the due date to indicate the due periodpayment_dueIndicates the payment is not yet collected and is being retried as per retry settings.not_paidIndicates the payment is not made and all attempts to collect is failed.
Show all values[+]
voided_at[]
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got voided.
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.
is_written_off[]
optional, boolean, default=false
If is_written_off is true then the invoice is written off.
write_off_amount[]
optional, in cents, default=0, min=0
Amount written off against this invoice. If this value is not present then the due amount of the invoice will be written off.
write_off_date[]
optional, timestamp(UTC) in seconds
The date on which the write_off invoice has occurred. This is a mandatory field if is_written_off is true. The same date reflects on the created credit note.
due_date[]
optional, timestamp(UTC) in seconds
Invoice Due Date.
net_term_days[]
optional, integer, default=0
Invoice net term days.
has_advance_charges[]
optional, boolean, default=false
Boolean indicating any advance charge is present in this invoice.
use_for_proration[]
optional, boolean, default=false
If the invoice falls within the subscription current term will be used for proration.
credit_note[id]
optional, string, max chars=50
billing_address[first_name]
optional, string, max chars=150
billing_address[last_name]
optional, string, max chars=150
billing_address[email]
optional, string, max chars=70
billing_address[company]
optional, string, max chars=250
billing_address[phone]
optional, string, max chars=50
billing_address[line1]
optional, string, max chars=150
billing_address[line2]
optional, string, max chars=150
billing_address[line3]
optional, string, max chars=150
billing_address[city]
optional, string, max chars=50
billing_address[state_code]
optional, string, max chars=50
billing_address[state]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
billing_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
shipping_address[first_name]
optional, string, max chars=150
shipping_address[last_name]
optional, string, max chars=150
shipping_address[email]
optional, string, max chars=70
shipping_address[company]
optional, string, max chars=250
shipping_address[phone]
optional, string, max chars=50
shipping_address[line1]
optional, string, max chars=150
shipping_address[line2]
optional, string, max chars=150
shipping_address[line3]
optional, string, max chars=150
shipping_address[city]
optional, string, max chars=50
shipping_address[state_code]
optional, string, max chars=50
shipping_address[state]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
shipping_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
line_items[id][0..n]
optional, string, max chars=40
line_items[date_from][0..n]
optional, timestamp(UTC) in seconds
line_items[date_to][0..n]
optional, timestamp(UTC) in seconds
line_items[subscription_id][0..n]
optional, string, max chars=50
line_items[description][0..n]
required, string, max chars=250
line_items[unit_amount][0..n]
optional, in cents
line_items[quantity][0..n]
optional, integer, default=1
line_items[amount][0..n]
optional, in cents
line_items[unit_amount_in_decimal][0..n]
optional, string, max chars=39
line_items[quantity_in_decimal][0..n]
optional, string, max chars=33
line_items[amount_in_decimal][0..n]
optional, string, max chars=39
line_items[entity_type][0..n]
optional, enumerated string
Possible values are
adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this caseplan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
Show all values[+]
line_items[entity_id][0..n]
optional, string, max chars=100
line_items[item_level_discount1_entity_id][0..n]
optional, string, max chars=100
line_items[item_level_discount1_amount][0..n]
optional, in cents, min=0
line_items[item_level_discount2_entity_id][0..n]
optional, string, max chars=100
line_items[item_level_discount2_amount][0..n]
optional, in cents, min=0
line_items[tax1_name][0..n]
optional, string, max chars=50
line_items[tax1_amount][0..n]
optional, in cents, min=0
line_items[tax2_name][0..n]
optional, string, max chars=50
line_items[tax2_amount][0..n]
optional, in cents, min=0
line_items[tax3_name][0..n]
optional, string, max chars=50
line_items[tax3_amount][0..n]
optional, in cents, min=0
line_items[tax4_name][0..n]
optional, string, max chars=50
line_items[tax4_amount][0..n]
optional, in cents, min=0
line_items[tax5_name][0..n]
optional, string, max chars=50
line_items[tax5_amount][0..n]
optional, in cents, min=0
line_items[tax6_name][0..n]
optional, string, max chars=50
line_items[tax6_amount][0..n]
optional, in cents, min=0
line_items[tax7_name][0..n]
optional, string, max chars=50
line_items[tax7_amount][0..n]
optional, in cents, min=0
line_items[tax8_name][0..n]
optional, string, max chars=50
line_items[tax8_amount][0..n]
optional, in cents, min=0
line_items[tax9_name][0..n]
optional, string, max chars=50
line_items[tax9_amount][0..n]
optional, in cents, min=0
line_items[tax10_name][0..n]
optional, string, max chars=50
line_items[tax10_amount][0..n]
optional, in cents, min=0
payment_reference_numbers[id][0..n]
optional, string, max chars=40
payment_reference_numbers[type][0..n]
required, enumerated string
Possible values are
kidThe KID number (kundeidentifikasjon) in Norway is an abbreviation for "Customer identification". It is used to associate payments with the customer and invoice.ocrA OCR-based payment, contains an OCR reference, which is used to identify the vendor and the purchase document in connection with a payment. Swedish reference number can contain customer ID and/or invoice number to identify customer and invoice.frnThe reference number printed on invoices in Finland is utilized by buyers for payment via bank transfer, facilitating the association of payments with invoices.fikDenmark based number calculated using recursive MOD 10 algorithm.
Show all values[+]
payment_reference_numbers[number][0..n]
required, string, max chars=100
line_item_tiers[line_item_id][0..n]
required, string, max chars=40
line_item_tiers[starting_unit][0..n]
optional, integer, min=0
line_item_tiers[ending_unit][0..n]
optional, integer
line_item_tiers[quantity_used][0..n]
optional, integer, min=0
line_item_tiers[unit_amount][0..n]
optional, in cents, min=0
line_item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
line_item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
line_item_tiers[quantity_used_in_decimal][0..n]
optional, string, max chars=33
line_item_tiers[unit_amount_in_decimal][0..n]
optional, string, max chars=40
discounts[line_item_id][0..n]
optional, string, max chars=40
discounts[entity_type][0..n]
required, enumerated string
Possible values are
item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice.item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id.
Show all values[+]
discounts[entity_id][0..n]
optional, string, max chars=100
discounts[description][0..n]
optional, string, max chars=250
discounts[amount][0..n]
required, in cents, min=0
taxes[name][0..n]
required, string, max chars=100
taxes[rate][0..n]
required, double, default=0.0, min=0.0, max=100.0
taxes[amount][0..n]
optional, in cents, min=0
taxes[description][0..n]
optional, string, max chars=50
taxes[juris_type][0..n]
optional, enumerated string, default=other
Possible values are
countryThe tax jurisdiction is a countryfederalThe tax jurisdiction is a federalstateThe tax jurisdiction is a statecountyThe tax jurisdiction is a county
Show all values[+]
taxes[juris_name][0..n]
optional, string, max chars=250
taxes[juris_code][0..n]
optional, string, max chars=250
payments[amount][0..n]
required, in cents, min=1
payments[payment_method][0..n]
required, enumerated string
Possible values are
cashCashcheckCheckbank_transferBank TransferotherPayment Methods other than the above types
Show all values[+]
payments[date][0..n]
optional, timestamp(UTC) in seconds
payments[reference_number][0..n]
optional, string, min chars=1, max chars=100
notes[entity_type][0..n]
optional, enumerated string
Possible values are
couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
Show all values[+]
notes[entity_id][0..n]
optional, string, max chars=50
notes[note][0..n]
optional, string, max chars=2000
invoice invoice
always returned
Resource object representing invoice
credit_note credit_note
optional
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

The API applies excess payments to an invoice. Once an excess payment is applied, the invoice.amount_due is recalculated. The invoice status changes to either paid or payment_due depending on how much excess payment is applied to the invoice amount.

For example, if you have an excess payment of $25.00, and the invoice to which you want to apply this excess payment has a balance of $50. Once you apply this excess payment, the invoice status changes to paid, and invoice.amount_due is adjusted to $25.00.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_payments \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aspaSOcTFAl2s",
        "date": 1612796659,
        "deleted": false,
        "due_date": 1612796659,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796660,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8aspaSOcTHUJ3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__6",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aspaSOcTFAl2s",
                "date_from": 1612796659,
                "date_to": 1612883059,
                "description": "basic USD 3",
                "discount_amount": 0,
                "entity_id": "basic-USD3",
                "entity_type": "plan_item_price",
                "id": "li___test__8aspaSOcTHQC3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8aspaSOcTFAl2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517490265,
                "txn_amount": 1000,
                "txn_date": 1517490265,
                "txn_id": "txn___test__8asyKSOcTHpM1H",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517490265,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490265366,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "subscription_id": "__test__8aspaSOcTFAl2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490265,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/apply_payments

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
transactions[id][0..n]
optional, string, max chars=40
transactions[amount][0..n]
optional, in cents, min=1
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Updates the quantity for metered line_items of an invoice to reflect the latest usage data.

Note: This operation is done automatically while closing the invoice. 

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/draft_inv_AwSNuHT1ebuqgOu/sync_usages \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "id": "draft_inv_AwSNuHT1ebuqgOu",
        "customer_id": "AwSNuHT1eblJbOe",
        "subscription_id": "AwSNuHT1ebupIOr",
        "recurring": true,
        "status": "pending",
        "price_type": "tax_exclusive",
        "date": 1630866600,
        "net_term_days": 0,
        "exchange_rate": 1,
        "total": 10000,
        "amount_paid": 0,
        "amount_adjusted": 0,
        "write_off_amount": 0,
        "credits_applied": 0,
        "amount_due": 10000,
        "updated_at": 1630919754,
        "resource_version": 1630919754875,
        "deleted": false,
        "object": "invoice",
        "first_invoice": false,
        "amount_to_collect": 10000,
        "round_off_amount": 0,
        "has_advance_charges": false,
        "currency_code": "USD",
        "base_currency_code": "USD",
        "generated_at": 1630866600,
        "is_gifted": false,
        "term_finalized": true,
        "channel": "web",
        "tax": 0,
        "line_items": [
            {
                "id": "li_AwSNuHT1ebuq3Ot",
                "date_from": 1628188200,
                "date_to": 1630866599,
                "unit_amount": 10000,
                "quantity": 1,
                "amount": 10000,
                "pricing_model": "per_unit",
                "is_taxed": false,
                "tax_amount": 0,
                "object": "line_item",
                "subscription_id": "AwSNuHT1ebupIOr",
                "customer_id": "AwSNuHT1eblJbOe",
                "description": "metered-plan",
                "entity_type": "plan_item_price",
                "entity_id": "metered-plan-USD-Monthly",
                "metered": true,
                "tax_exempt_reason": "export",
                "discount_amount": 0,
                "item_level_discount_amount": 0
            },
            {..}
        ],
        "sub_total": 10000,
        "linked_payments": [],
        "applied_credits": [],
        "adjustment_credit_notes": [],
        "issued_credit_notes": [],
        "linked_orders": [],
        "dunning_attempts": []
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/sync_usages

Method

invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This endpoint is used to delete line items from "Pending" invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/delete_line_items \
     -X POST  \
     -u {site_api_key}:\
     -d line_items[id][0]="test" 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 56774,
        "amount_paid": 0,
        "amount_to_collect": 56774,
        "applied_credits": [],
        "base_currency_code": "USD",
        "channel": "web",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__rHsvTLolqNb3G",
        "date": 1517464655,
        "deleted": false,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "generated_at": 1517464655,
        "has_advance_charges": false,
        "id": "__demo_inv__2",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 56774,
                "customer_id": "__test__rHsvTLolqNb3G",
                "date_from": 1517464655,
                "date_to": 1669528644,
                "description": "Basic - Prorated Charges",
                "discount_amount": 0,
                "entity_id": "basic",
                "entity_type": "plan",
                "id": "li___test__8asrcTLolu83T",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__rHsvTLolqNb3G",
                "tax_amount": 0,
                "unit_amount": 56774
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517464656901,
        "round_off_amount": 0,
        "status": "pending",
        "sub_total": 56774,
        "subscription_id": "__test__rHsvTLolqNb3G",
        "tax": 0,
        "term_finalized": true,
        "total": 56774,
        "updated_at": 1517464656,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/delete_line_items

Method

line_items[id][0..n]
optional, string, max chars=40
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

This API applies available credits to an invoice. After credits are applied, invoice.amount_due is recalculated. The invoice status changes to either paid or payment_due depending on how much credit is applied to the invoice amount.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/apply_credits \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 0,
        "amount_to_collect": 0,
        "applied_credits": [
            {
                "applied_amount": 2000,
                "applied_at": 1612962254,
                "cn_create_reason_code": "Service Unsatisfactory",
                "cn_date": 1612962254,
                "cn_id": "__demo_cn__1",
                "cn_reason_code": "service_unsatisfactory",
                "cn_status": "refund_due"
            },
            {..}
        ],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Mathew",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 2000,
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTDt4N",
        "date": 1612962253,
        "deleted": false,
        "due_date": 1612962253,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__2",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asyKSOcTDt4N",
                "date_from": 1612962253,
                "date_to": 1615381453,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asyKSOcTErGh",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asyKSOcTEo4f",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "new_sales_amount": 2000,
        "object": "invoice",
        "paid_at": 1612962254,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612962254000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 2000,
        "subscription_id": "__test__8asyKSOcTEo4f",
        "tax": 0,
        "term_finalized": true,
        "total": 2000,
        "updated_at": 1612962254,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/apply_credits

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
credit_notes[id][0..n]
optional, string, max chars=50
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Lists all the Invoices.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode status[in]=["paid","payment_due"] \
     --data-urlencode sort_by[asc]=date
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "invoice": {
                "adjustment_credit_notes": [],
                "amount_adjusted": 0,
                "amount_due": 0,
                "amount_paid": 1000,
                "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__8asyKSOcTHxf1V",
                "date": 1517490266,
                "deleted": false,
                "due_date": 1517490266,
                "dunning_attempts": [],
                "exchange_rate": 1,
                "first_invoice": true,
                "has_advance_charges": false,
                "id": "__demo_inv__7",
                "is_gifted": false,
                "issued_credit_notes": [
                    {
                        "cn_create_reason_code": "Subscription Change",
                        "cn_date": 1517490267,
                        "cn_id": "__demo_cn__2",
                        "cn_reason_code": "subscription_change",
                        "cn_status": "refunded",
                        "cn_total": 1000
                    },
                    {..}
                ],
                "line_items": [
                    {
                        "amount": 1000,
                        "customer_id": "__test__8asyKSOcTHxf1V",
                        "date_from": 1517490266,
                        "date_to": 1519909466,
                        "description": "basic USD",
                        "discount_amount": 0,
                        "entity_id": "basic-USD",
                        "entity_type": "plan_item_price",
                        "id": "li___test__8asyKSOcTI6v1e",
                        "is_taxed": false,
                        "item_level_discount_amount": 0,
                        "object": "line_item",
                        "pricing_model": "per_unit",
                        "quantity": 1,
                        "subscription_id": "__test__8asyKSOcTI3k1c",
                        "tax_amount": 0,
                        "tax_exempt_reason": "tax_not_configured",
                        "unit_amount": 1000
                    },
                    {..}
                ],
                "linked_orders": [],
                "linked_payments": [
                    {
                        "applied_amount": 1000,
                        "applied_at": 1517490266,
                        "txn_amount": 1000,
                        "txn_date": 1517490266,
                        "txn_id": "txn___test__8asyKSOcTIAy1f",
                        "txn_status": "success"
                    },
                    {..}
                ],
                "net_term_days": 0,
                "new_sales_amount": 1000,
                "object": "invoice",
                "paid_at": 1517490266,
                "price_type": "tax_exclusive",
                "recurring": true,
                "resource_version": 1517490268022,
                "round_off_amount": 0,
                "status": "paid",
                "sub_total": 1000,
                "subscription_id": "__test__8asyKSOcTI3k1c",
                "tax": 0,
                "term_finalized": true,
                "total": 1000,
                "updated_at": 1517490268,
                "write_off_amount": 0
            }
        },
        {..}
    ],
    "next_offset": "[\"1517490271000\",\"243000000410\"]"
}

URL Format GET

https://{site}.chargebee.com/api/v2/invoices

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
include_deleted[]
optional, boolean, default=false
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
sort_by[<sort-order>]
optional, string filter
Sorts based on the specified attribute.
Supported attributes : date, updated_at
Supported sort-orders : asc, desc

Example sort_by[asc] = "date"
This will sort the result based on the 'date' attribute in ascending(earliest first) order.
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
optional, string filter
The invoice number. Acts as a identifier for invoice and typically generated sequentially. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in

Example id[is] = "INVOICE_654"
id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
id[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
subscription_id[<operator>]
optional, string filter
To filter based on subscription_id.
NOTE: Not to be used if consolidated invoicing is enabled.
Possible values are :
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example subscription_id[is] = "3bdjnDnsdQn"
subscription_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
subscription_id[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
subscription_id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
subscription_id[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
customer_id[<operator>]
optional, string filter
The identifier of the customer this invoice belongs to. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in

Example customer_id[is] = "3bdjnDnsdQn"
customer_id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
customer_id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
customer_id[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
recurring[<operator>]
optional, enumerated string filter
Boolean indicating whether this invoice belongs to a subscription. Possible values are : true, false
Supported operators : is

Example recurring[is] = "true"
recurring[is][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
status[<operator>]
optional, enumerated string filter
Current status of this invoice. Possible values are : paid, posted, payment_due, not_paid, voided, pending
Supported operators : is, is_not, in, not_in

Example status[is] = "paid"
status[is][operator]
optional, enumerated string filter
Possible values are : paid, posted, payment_due, not_paid, voided, pending
Supported operators :

Example
status[is_not][operator]
optional, enumerated string filter
Possible values are : paid, posted, payment_due, not_paid, voided, pending
Supported operators :

Example
status[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
status[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
price_type[<operator>]
optional, enumerated string filter
The price type of the invoice. Possible values are : tax_exclusive, tax_inclusive
Supported operators : is, is_not, in, not_in

Example price_type[is] = "tax_exclusive"
price_type[is][operator]
optional, enumerated string filter
Possible values are : tax_exclusive, tax_inclusive
Supported operators :

Example
price_type[is_not][operator]
optional, enumerated string filter
Possible values are : tax_exclusive, tax_inclusive
Supported operators :

Example
price_type[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
price_type[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
date[<operator>]
optional, timestamp(UTC) in seconds filter
The document date displayed on the invoice PDF. Possible values are :
Supported operators : after, before, on, between

Example date[after] = "1394532759"
date[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
date[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
date[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
date[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
paid_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating the date & time this invoice got paid. Possible values are :
Supported operators : after, before, on, between

Example paid_at[after] = "1394532759"
paid_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
paid_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
paid_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
paid_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
total[<operator>]
optional, number filter
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. Possible values are :
Supported operators : is, is_not, lt, lte, gt, gte, between

Example total[is] = "1000"
total[is][operator]
optional, number filter
Possible values are :
Supported operators :

Example
total[is_not][operator]
optional, number filter
Possible values are :
Supported operators :

Example
total[lt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
total[lte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
total[gt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
total[gte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
total[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
amount_paid[<operator>]
optional, number filter
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. Possible values are :
Supported operators : is, is_not, lt, lte, gt, gte, between

Example amount_paid[is] = "800"
amount_paid[is][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_paid[is_not][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_paid[lt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_paid[lte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_paid[gt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_paid[gte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_paid[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
amount_adjusted[<operator>]
optional, number filter
Total adjustments made against this invoice. Possible values are :
Supported operators : is, is_not, lt, lte, gt, gte, between

Example amount_adjusted[is] = "100"
amount_adjusted[is][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_adjusted[is_not][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_adjusted[lt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_adjusted[lte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_adjusted[gt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_adjusted[gte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_adjusted[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
credits_applied[<operator>]
optional, number filter
Total credits applied against this invoice. Possible values are :
Supported operators : is, is_not, lt, lte, gt, gte, between

Example credits_applied[is] = "100"
credits_applied[is][operator]
optional, number filter
Possible values are :
Supported operators :

Example
credits_applied[is_not][operator]
optional, number filter
Possible values are :
Supported operators :

Example
credits_applied[lt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
credits_applied[lte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
credits_applied[gt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
credits_applied[gte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
credits_applied[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
amount_due[<operator>]
optional, number filter
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. Possible values are :
Supported operators : is, is_not, lt, lte, gt, gte, between

Example amount_due[is] = "200"
amount_due[is][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_due[is_not][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_due[lt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_due[lte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_due[gt][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_due[gte][operator]
optional, number filter
Possible values are :
Supported operators :

Example
amount_due[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
dunning_status[<operator>]
optional, enumerated string filter
Current dunning status of the invoice. Possible values are : in_progress, exhausted, stopped, success
Supported operators : is, is_not, in, not_in, is_present

Example dunning_status[is] = "in_progress"
dunning_status[is][operator]
optional, enumerated string filter
Possible values are : in_progress, exhausted, stopped, success
Supported operators :

Example
dunning_status[is_not][operator]
optional, enumerated string filter
Possible values are : in_progress, exhausted, stopped, success
Supported operators :

Example
dunning_status[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
dunning_status[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
dunning_status[is_present][operator]
optional, enumerated string filter
Possible values are : true, false
Supported operators :

Example
payment_owner[<operator>]
optional, string filter
Payment owner of an invoice. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in

Example payment_owner[is] = "payment_customer"
payment_owner[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
payment_owner[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
payment_owner[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
payment_owner[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
payment_owner[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
updated_at[<operator>]
optional, timestamp(UTC) in seconds filter
To filter based on updated_at. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by input parameter as updated_at for a faster response. Possible values are :
Supported operators : after, before, on, between

Example updated_at[after] = "1243545465"
updated_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
updated_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
channel[<operator>]
optional, enumerated string filter
The subscription channel this object originated from and is maintained in. Possible values are : web, app_store, play_store
Supported operators : is, is_not, in, not_in

Example channel[is] = "APP STORE"
channel[is][operator]
optional, enumerated string filter
Possible values are : web, app_store, play_store
Supported operators :

Example
channel[is_not][operator]
optional, enumerated string filter
Possible values are : web, app_store, play_store
Supported operators :

Example
channel[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
channel[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
voided_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating the date & time this invoice got voided. Possible values are :
Supported operators : after, before, on, between

Example voided_at[after] = "1394532759"
voided_at[after][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
voided_at[before][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
voided_at[on][operator]
optional, timestamp(UTC) in seconds filter
Possible values are :
Supported operators :

Example
voided_at[between][operator]
optional, string filter
Possible values are :
Supported operators :

Example
void_reason_code[<operator>]
optional, string filter
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. Possible values are :
Supported operators : is, is_not, starts_with, in, not_in

Example void_reason_code[is] = "Other"
void_reason_code[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
void_reason_code[is_not][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
void_reason_code[starts_with][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
void_reason_code[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
void_reason_code[not_in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
einvoice[<operator>]
optional, enumerated string filter
Parameters for einvoice Possible values are :
Supported operators : status

Example einvoice[status] = "undefined"
einvoice[status][operator]
optional, enumerated string filter
The status of processing the e-invoice. To obtain detailed information about the current status, see message. Possible values are : scheduled, skipped, in_progress, success, failed, registered
Supported operators : is, is_not, in, not_in

Example einvoice[status][is] = "failed"
invoice invoice
always returned
Resource object representing invoice
next_offset next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
Retrieve the invoice for the specified invoice id.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__17 \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 500,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Duncan",
            "last_name": "Walpole",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTKve4P",
        "date": 1517490277,
        "deleted": false,
        "due_date": 1517490277,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__17",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__8asyKSOcTKve4P",
                "date_from": 1517490277,
                "date_to": 1517490277,
                "description": "SSL Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "ssl-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTL0N4X",
                "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": 500
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 500,
                "applied_at": 1517490277,
                "txn_amount": 500,
                "txn_date": 1517490277,
                "txn_id": "txn___test__8asyKSOcTL3o4Y",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 500,
        "object": "invoice",
        "paid_at": 1517490277,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517490277579,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 500,
        "tax": 0,
        "term_finalized": true,
        "total": 500,
        "updated_at": 1517490277,
        "write_off_amount": 0
    }
}

URL Format GET

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}

Method

invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Gets the invoice as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.

Related Tutorial

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__18/pdf \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "download": {
        "download_url": "https://cb-local-downloads.s3.amazonaws.com/yourapp/invoice/__test__8asyKSOcTMNf4r.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Finvoice%2F__test__8asyKSOcTMNf4r.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210210T130447Z&X-Amz-SignedHeaders=host&X-Amz-Expires=599&X-Amz-Credential=AKIAJI4SN7ONHAOGLOGA%2F20210210%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=dcf3b55c68ba695edded4a3d6305cb3822415601c590ad6293cfb858514078e6",
        "object": "download",
        "valid_till": 1612962887
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/pdf

Method

disposition_type[]
optional, enumerated string, default=attachment
Determines the pdf should be rendered as inline or attachment in the browser.
Possible values are
attachmentPDF is rendered as attachment in the browserinlinePDF is rendered as inline in the browser
Show all values[+]
download download
always returned
Resource object representing download

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Download the e-invoice in both XML and PDF formats. The response consists of a download object for each format. The XML format follows the structure as per Peppol BIS Billing v3.0.

Note

  • You can only download e-invoices when their status is success.
  • There are some cases in which the PDF is not available for download. In such cases, you can obtain it from the XML by decoding the value for cbc:EmbeddedDocumentBinaryObject, which is the Base64-encoded version of the PDF.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/download_einvoice \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "downloads": [
        {
            "download_url": "https://dj-temp.s3.eu-west-1.amazonaws.com/f8a8ecffb9c0a52661948dd317c0fbb0e6b00dcdeb84d208df6a7f101527f023a071270188473bb1bfe8bccfe50217bb25098852979eccadcadafa54effcfcc6?X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Credential=AKIAI5G5MTYS7SBP4ZEQ%2F20211123%2Feu-west-1%2Fs3%2Faws4_request&X-Amz-Date=20211123T072152Z&X-Amz-Expires=604800&X-Amz-SignedHeaders=host&X-Amz-Signature=cff0a369049dea8a16da3b92131d477bdde8445069ae5cadb3681c7d3afe8650",
            "mime_type": "application/xml",
            "object": "download",
            "valid_till": 1517429503
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/download_einvoice

Method

downloads downloads
always returned
Resource object representing downloads

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API endpoint allows users to retrieve the payment reference numbers (PRNs) associated with an invoice. Only one PRN is allowed per payment type. You can use the invoice_id or the payment_reference_number[number] to retrieve the PRN.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/payment_reference_numbers \
     -G  \
     -u {site_api_key}:\
     --data-urlencode id[is]="__demo_inv__2"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "payment_reference_number": {
                "id": "prn___test__8aszZTexzRqs4A",
                "invoice_id": "__demo_inv__2",
                "number": "0000202317",
                "object": "payment_reference_number",
                "type": "kid"
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v2/invoices/payment_reference_numbers

Method

limit[]
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset[]
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
optional, string filter
An unique identifier for the invoice serves that links the invoice to the corresponding payment reference number (PRN).
Note: To retrieve the PRN, the API requires either the invoice ID or the payment reference number to be provided by the user. If both values are missing, an error will be returned by the API.
Possible values are :
Supported operators : in, is

Example id[in] = "old_inv_001"
id[in][operator]
optional, string filter
Possible values are :
Supported operators :

Example
id[is][operator]
optional, string, min chars=1 filter
Possible values are :
Supported operators :

Example
payment_reference_number[<operator>]
optional, string filter
Parameters for payment_reference_number Possible values are :
Supported operators : number

Example payment_reference_number[number] = "undefined"
payment_reference_number[number][operator]
optional, string filter
This parameter is used to identify the PRN in the system and retrieve its corresponding payment information.
Note: To retrieve the PRN, the API requires either the invoice ID or the payment reference number to be provided by the user. If both values are missing, an error will be returned by the API.
Possible values are :
Supported operators : in, is

Example payment_reference_number[number][in] = "001234"
payment_reference_number payment_reference_number
always returned
Resource object representing payment_reference_number
next_offset next_offset
optional, string, max chars=1000
This attribute is returned only if more resources are present. To fetch the next set of resources use this value for the input parameter `offset`.

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Adds a one-time charge to a pending invoice. A one-time charge is a charge that is added ad hoc to the invoice and does not represent a predefined item price. It appears in the invoice as a line_item of entity_type adhoc.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \
     -u {site_api_key}:\
     -d amount=150 \
     -d description="$0.05 each for 30 messages"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 29731,
        "amount_paid": 0,
        "amount_to_collect": 29731,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__XpbBxViS4HCzob2f",
        "date": 1517429423,
        "deleted": false,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 29581,
                "customer_id": "__test__XpbBxViS4HCzob2f",
                "date_from": 1517429423,
                "date_to": 1596658222,
                "description": "Basic - Prorated Charges",
                "discount_amount": 0,
                "entity_id": "basic",
                "entity_type": "plan",
                "id": "li___test__XpbBxQiS4HCztAVi",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__XpbBxViS4HCzob2f",
                "tax_amount": 0,
                "unit_amount": 29581
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517429423000,
        "round_off_amount": 0,
        "status": "pending",
        "sub_total": 29731,
        "subscription_id": "__test__XpbBxViS4HCzob2f",
        "tax": 0,
        "term_finalized": true,
        "total": 29731,
        "updated_at": 1517429423,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/add_charge

Method

amount[]
required, in cents, min=1
The amount to be charged. The unit depends on the type of currency.
description[]
required, string, max chars=250
Detailed description about this lineitem.
avalara_sale_type[]
optional, enumerated string
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
Show all values[+]
avalara_transaction_type[]
optional, integer
Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
avalara_service_type[]
optional, integer
Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
avalara_tax_code[]
optional, string, max chars=50
This represents the Avalara tax code to which the one-time charge is mapped. Applicable only if you use Chargebee's AvaTax for Sales integration.
hsn_code[]
optional, string, max chars=50
The HSN code to which the one-time charge is mapped for calculating the customer’s tax in India. Applicable when both the conditions are true: .
taxjar_product_code[]
optional, string, max chars=50
This represents the TaxJar product code to which the one-time charge is mapped. Applicable only if you use Chargebee's TaxJar integration.
comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this charge needs to be created. Applicable for consolidated invoice.
line_item[date_from]
optional, timestamp(UTC) in seconds
line_item[date_to]
optional, timestamp(UTC) in seconds
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

This endpoint is used when metered billing is enabled and it adds a charge-item price to a pending invoice. To collect the accumulated charges by closing the invoice, call Close a pending invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_charge_item \
     -u {site_api_key}:\
     -d item_price[item_price_id]="ssl-charge-USD" \
     -d item_price[unit_price]=495
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1001,
        "amount_paid": 0,
        "amount_to_collect": 1001,
        "applied_credits": [],
        "base_currency_code": "USD",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__KyVk7hRy2QAqMx",
        "date": 1517502930,
        "deleted": false,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__2",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__KyVk7hRy2QAqMx",
                "date_from": 1517502930,
                "date_to": 1519922130,
                "description": "basic USD",
                "discount_amount": 0,
                "entity_id": "basic-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__KyVkDeRy2QDX18",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVk7hRy2QAqMx",
                "tax_amount": 0,
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517502935000,
        "round_off_amount": 0,
        "status": "pending",
        "sub_total": 1001,
        "subscription_id": "__test__KyVk7hRy2QAqMx",
        "tax": 0,
        "term_finalized": true,
        "total": 1001,
        "updated_at": 1517502935,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/add_charge_item

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this addon needs to be created. Applicable for consolidated invoice.
item_price[item_price_id]
required, string, max chars=100
item_price[quantity]
optional, integer, min=1
item_price[quantity_in_decimal]
optional, string, max chars=33
item_price[unit_price]
optional, in cents, min=0
item_price[unit_price_in_decimal]
optional, string, max chars=39
item_price[date_from]
optional, timestamp(UTC) in seconds
item_price[date_to]
optional, timestamp(UTC) in seconds
item_tiers[starting_unit][0..n]
optional, integer, min=1
item_tiers[ending_unit][0..n]
optional, integer
item_tiers[price][0..n]
optional, in cents, default=0, min=0
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
item_tiers[price_in_decimal][0..n]
optional, string, max chars=39
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Invoices for a subscription are created with a pending status when the subscription has create_pending_invoices attribute set to true. This API call finalizes a pending invoice. Any refundable_credits and excess_payments for the customer are applied to the invoice, and any payment due is collected automatically if auto_collection is on for the customer.

Automation

This operation can be automated by using a site setting. Moreover, the automation can be overridden at the customer and subscription level.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__8/close \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 500,
        "amount_paid": 0,
        "amount_to_collect": 500,
        "applied_credits": [
            {
                "applied_amount": 1000,
                "applied_at": 1517490267,
                "cn_create_reason_code": "Subscription Change",
                "cn_date": 1517490267,
                "cn_id": "__demo_cn__2",
                "cn_reason_code": "subscription_change",
                "cn_status": "refunded"
            },
            {..}
        ],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "John",
            "last_name": "Mathew",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 1000,
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTHxf1V",
        "date": 1517490267,
        "deleted": false,
        "due_date": 1517490268,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__8",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1500,
                "customer_id": "__test__8asyKSOcTHxf1V",
                "date_from": 1517490267,
                "date_to": 1519909466,
                "description": "Standard USD - Prorated Charges",
                "discount_amount": 0,
                "entity_id": "standard-USD",
                "entity_type": "plan_item_price",
                "id": "li___test__8asyKSOcTIRM1m",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asyKSOcTI3k1c",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1500
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "next_retry_at": 1517490273,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490267583,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1500,
        "subscription_id": "__test__8asyKSOcTI3k1c",
        "tax": 0,
        "term_finalized": true,
        "total": 1500,
        "updated_at": 1517490267,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/close

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
invoice_note[]
optional, string, max chars=2000
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
remove_general_note[]
optional, boolean, default=false
Set as true to remove the general note from this invoice.
invoice_date[]
optional, timestamp(UTC) in seconds
Set the invoice date. Must lie between the date when the invoice was generated and current date. Can only be passed when the site setting to allow overriding is enabled. If not passed, then the default value set at the site level is used.
notes_to_remove[entity_type][0..n]
optional, enumerated string
Possible values are
customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Price
Show all values[+]
notes_to_remove[entity_id][0..n]
optional, string, max chars=100
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
Important:
  • Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
  • This endpoint returns an error if a payment is initiated for an invoice with a status of payment_due associated with the app_store and play_store channels.

This API is used to collect payments for payment_due and not_paid invoices. If no payment methods are present for the customer or if the payment is unsuccessful, the corresponding error will be thrown.

Pass authorization_transaction_id to capture the already blocked funds to collect payments. Note that if the invoice due amount is greater than the authorized amount, the invoice status is returned as payment_due.

Notes

The authorization transaction will not be captured if the fraud status is found as suspicious. This api will result in invalid_state_for_request error. Read more on fraud management using Stripe Radar.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/collect_payment \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__8asyKSOcU2Zm5P"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asxfSOcTzpo2s",
        "date": 1612796839,
        "deleted": false,
        "due_date": 1612796839,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796840,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8asxfSOcU2Ku3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asxfSOcTzpo2s",
                "date_from": 1612796839,
                "date_to": 1612883239,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8asxfSOcU2D83u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asxfSOcTzpo2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517490444,
                "txn_amount": 1000,
                "txn_date": 1517490444,
                "txn_id": "txn___test__8asyKSOcU2bm5W",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517490444,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490444979,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "subscription_id": "__test__8asxfSOcTzpo2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490444,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 1000,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__8asxfSOcTzpo2s",
        "date": 1517490444,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__8asxfSOcTyhc1y",
        "id": "txn___test__8asyKSOcU2bm5W",
        "id_at_gateway": "cb___test__8asyKSOcU2bq5X",
        "linked_invoices": [
            {
                "applied_amount": 1000,
                "applied_at": 1517490444,
                "invoice_date": 1612796839,
                "invoice_id": "__demo_inv__4",
                "invoice_status": "paid",
                "invoice_total": 1000
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__8asyKSOcU2Zm5P",
        "resource_version": 1517490444979,
        "status": "success",
        "subscription_id": "__test__8asxfSOcTzpo2s",
        "type": "payment",
        "updated_at": 1517490444
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/collect_payment

Method

amount[]
optional, in cents, min=1
Amount to be collected. If this parameter is not passed then the entire amount due will be collected.
authorization_transaction_id[]
optional, string, max chars=40
Authorization transaction to be captured.
payment_source_id[]
optional, string, max chars=40
Payment source to be used for this payment.
comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
payment_initiator[]
optional, enumerated string
The type of initiator to be used for the payment request triggered by this operation.
Possible values are
customerPass this value to indicate that the request is initiated by the customermerchantPass this value to indicate that the request is initiated by the merchant
Show all values[+]
invoice invoice
always returned
Resource object representing invoice
transaction transaction
always returned
Resource object representing transaction

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

To record a offline payment for an invoice.

The invoice status will be marked as 'paid' if its amount due becomes 0 because of this recorded payment.

Note: If the payment transaction amount is more than the invoice due amount, the remaining transaction amount will be added to the customer's Excess Payments balance to be used against other invoices.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_payment \
     -u {site_api_key}:\
     -d comment="Payment received" \
     -d transaction[amount]=200 \
     -d transaction[payment_method]="BANK_TRANSFER" \
     -d transaction[date]=1612800517
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 800,
        "amount_paid": 200,
        "amount_to_collect": 800,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aswoSOcUJgJ2s",
        "date": 1612796914,
        "deleted": false,
        "due_date": 1612796914,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796915,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8aswoSOcUM0M3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "in_progress",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aswoSOcUJgJ2s",
                "date_from": 1612796914,
                "date_to": 1612883314,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8aswoSOcULwP3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8aswoSOcUJgJ2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612796915,
                "txn_amount": 1000,
                "txn_date": 1612796915,
                "txn_id": "txn___test__8aswoSOcUM0M3v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "next_retry_at": 1612883315,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490520418,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1000,
        "subscription_id": "__test__8aswoSOcUJgJ2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490520,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 200,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__8aswoSOcUJgJ2s",
        "date": 1612800517,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__8asyKSOcUMEY6O",
        "linked_invoices": [
            {
                "applied_amount": 200,
                "applied_at": 1517490520,
                "invoice_date": 1612796914,
                "invoice_id": "__demo_inv__4",
                "invoice_status": "payment_due",
                "invoice_total": 1000
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "resource_version": 1517490520417,
        "status": "success",
        "subscription_id": "__test__8aswoSOcUJgJ2s",
        "type": "payment",
        "updated_at": 1517490520
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/record_payment

Method

comment[]
optional, string, max chars=300
Remarks, if any, on the payment.
transaction[amount]
optional, in cents, min=1
transaction[payment_method]
required, enumerated string
Possible values are
cashCashcheckCheckbank_transferBank TransferotherPayment Methods other than the above types
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
transaction[custom_payment_method_id]
optional, string, max chars=50
transaction[id_at_gateway]
optional, string, max chars=100
transaction[status]
optional, enumerated string
Possible values are
successThe transaction is successful.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure
Show all values[+]
transaction[date]
optional, timestamp(UTC) in seconds
transaction[error_code]
optional, string, max chars=100
transaction[error_text]
optional, string, max chars=65k
invoice invoice
always returned
Resource object representing invoice
transaction transaction
always returned
Resource object representing transaction

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Records tax_withheld by the customer against the invoice specified. This operation is allowed only when all of the following conditions are true:

  • Tax Amount Withheld is enabled.
  • The invoice does not have a linked_taxes_withheld record associated with it already.
  • invoice.amount_due is greater than zero.
  • invoice.status is one of the following: payment_due, not_paid, or posted.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_tax_withheld \
     -u {site_api_key}:\
     -d tax_withheld[amount]=200 \
     -d tax_withheld[date]=1635080065
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 800,
        "amount_paid": 0,
        "amount_to_collect": 800,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "channel": "web",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asr8SmwH1ZM2w",
        "date": 1635076461,
        "deleted": false,
        "due_date": 1635076461,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1635076462,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8asr8SmwH4Z83z",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "in_progress",
        "exchange_rate": 1,
        "first_invoice": false,
        "generated_at": 1635076461,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asr8SmwH1ZM2w",
                "date_from": 1635076461,
                "date_to": 1635162861,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8asr8SmwH4WO3y",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asr8SmwH1ZM2w",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1635076462,
                "txn_amount": 1000,
                "txn_date": 1635076462,
                "txn_id": "txn___test__8asr8SmwH4Z83z",
                "txn_status": "failure"
            },
            {..}
        ],
        "linked_taxes_withheld": [
            {
                "amount": 200,
                "date": 1635080065,
                "description": "A tax amount of $2.00 withheld by the customer was recorded against the invoice due amount.",
                "id": "tax_wh___test__8assSSmwH5Bhr"
            },
            {..}
        ],
        "net_term_days": 0,
        "next_retry_at": 1635162862,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517478871359,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1000,
        "subscription_id": "__test__8asr8SmwH1ZM2w",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517478871,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/record_tax_withheld

Method

tax_withheld[amount]
required, in cents, min=1
tax_withheld[reference_number]
optional, string, max chars=100
tax_withheld[date]
optional, timestamp(UTC) in seconds
tax_withheld[description]
optional, string, max chars=65k
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Removes a linked_taxes_withheld record from the invoice specified. This operation is allowed only when all of the following conditions are true:

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_tax_withheld \
     -u {site_api_key}:\
     -d tax_withheld[id]="tax_wh___test__8assSSmwIEze1w"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1000,
        "amount_paid": 0,
        "amount_to_collect": 1000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "channel": "web",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aszjSmwIBcx2w",
        "date": 1635076738,
        "deleted": false,
        "due_date": 1635076738,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1635076739,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8aszjSmwIER23z",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "in_progress",
        "exchange_rate": 1,
        "first_invoice": false,
        "generated_at": 1635076738,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aszjSmwIBcx2w",
                "date_from": 1635076738,
                "date_to": 1635163138,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8aszjSmwIEO63y",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8aszjSmwIBcx2w",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1635076739,
                "txn_amount": 1000,
                "txn_date": 1635076739,
                "txn_id": "txn___test__8aszjSmwIER23z",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "next_retry_at": 1635163139,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517479147665,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1000,
        "subscription_id": "__test__8aszjSmwIBcx2w",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517479147,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/remove_tax_withheld

Method

tax_withheld[id]
required, string, max chars=40
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Refunds the invoice. The refund request is processed via the payment gateway originally used to charge the customer. You can choose to either make a full refund for the entire amount or make many partial refunds until you reach the total amount charged for the invoice. The API returns an error if an attempt is made to:

  • Refund an offline invoice. For such invoices, use the Record refund API.
  • Refund a fully refunded invoice.

If the refund transaction succeeds, a credit_note capturing this refund detail is created for the invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__14/refund \
     -u {site_api_key}:\
     -d refund_amount=500 \
     -d credit_note[reason_code]="SERVICE_UNSATISFACTORY"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 0,
        "amount_refunded": 500,
        "base_currency_code": "USD",
        "create_reason_code": "Service Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTKEe3L",
        "date": 1517490275,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__4",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__8asyKSOcTKEe3L",
                "date_from": 1517490275,
                "date_to": 1517490275,
                "description": "SSL Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "ssl-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTKQc3b",
                "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": 500
            },
            {..}
        ],
        "linked_refunds": [
            {
                "applied_amount": 500,
                "applied_at": 1517490275,
                "txn_amount": 500,
                "txn_date": 1517490275,
                "txn_id": "txn___test__8asyKSOcTKQE3Z",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "service_unsatisfactory",
        "reference_invoice_id": "__demo_inv__14",
        "refunded_at": 1517490275,
        "resource_version": 1517490275164,
        "round_off_amount": 0,
        "status": "refunded",
        "sub_total": 500,
        "taxes": [],
        "total": 500,
        "type": "refundable",
        "updated_at": 1517490275
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 500,
        "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__8asyKSOcTKEe3L",
        "date": 1517490274,
        "deleted": false,
        "due_date": 1517490274,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__14",
        "is_gifted": false,
        "issued_credit_notes": [
            {
                "cn_create_reason_code": "Service Unsatisfactory",
                "cn_date": 1517490275,
                "cn_id": "__demo_cn__4",
                "cn_reason_code": "service_unsatisfactory",
                "cn_status": "refunded",
                "cn_total": 500
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__8asyKSOcTKEe3L",
                "date_from": 1517490274,
                "date_to": 1517490274,
                "description": "SSL Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "ssl-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTKKc3T",
                "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": 500
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 500,
                "applied_at": 1517490274,
                "txn_amount": 500,
                "txn_date": 1517490274,
                "txn_id": "txn___test__8asyKSOcTKOR3U",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 500,
        "object": "invoice",
        "paid_at": 1517490274,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517490275163,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 500,
        "tax": 0,
        "term_finalized": true,
        "total": 500,
        "updated_at": 1517490275,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 500,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTKEe3L",
        "date": 1517490275,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__8aspaSOcTCvD1y",
        "id": "txn___test__8asyKSOcTKQE3Z",
        "id_at_gateway": "cb___test__8asyKSOcTKOV3V",
        "linked_credit_notes": [
            {
                "applied_amount": 500,
                "applied_at": 1517490275,
                "cn_create_reason_code": "Service Unsatisfactory",
                "cn_date": 1517490275,
                "cn_id": "__demo_cn__4",
                "cn_reason_code": "service_unsatisfactory",
                "cn_reference_invoice_id": "__demo_inv__14",
                "cn_status": "refunded",
                "cn_total": 500
            },
            {..}
        ],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__8asyKSOcTKF63N",
        "refunded_txn_id": "txn___test__8asyKSOcTKOR3U",
        "resource_version": 1517490275165,
        "status": "success",
        "type": "refund",
        "updated_at": 1517490275
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/refund

Method

refund_amount[]
optional, in cents, min=1
The amount to be refunded. If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid via online transactions, and not already refunded. Note: Any linked_taxes_withheld associated with the invoice cannot be refunded via this operation.
comment[]
optional, string, max chars=300
Comment, if any, on the refund.
customer_notes[]
optional, string, max chars=2000
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
credit_note[reason_code]
optional, enumerated string
Possible values are
product_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder Cancellation
Show all values[+]
credit_note[create_reason_code]
optional, string, max chars=100
invoice invoice
always returned
Resource object representing invoice
transaction transaction
always returned
Resource object representing transaction
credit_note credit_note
optional
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Refunds the invoice. The refund is provided against the following in order of precedence:

Example

Consider an invoice with the following payments and tax withheld.

  • Offline payments: $30
  • Online payments: $20
  • Tax withheld: $5

When recording a refund worth $40, the refund amount is split as follows:

  • Refund against offline payments: $30
  • Refund against tax withheld: $5
  • Refund against online payments: $5

For payments made via online transactions, the refund request is processed via the payment gateway originally used to charge the customer.

Tip

If the order of precendence described above does not work for your use case, and you want to provide a refund against online linked_payments first, use the Refund an invoice API.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__13/record_refund \
     -u {site_api_key}:\
     -d transaction[amount]=100 \
     -d transaction[payment_method]="BANK_TRANSFER" \
     -d transaction[date]=1517490274
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 0,
        "amount_refunded": 100,
        "base_currency_code": "USD",
        "create_reason_code": "Other",
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTK1x2z",
        "date": 1517490274,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__3",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 100,
                "customer_id": "__test__8asyKSOcTK1x2z",
                "date_from": 1517490274,
                "date_to": 1517490274,
                "description": "SSL Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "ssl-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTKBX3F",
                "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": 100
            },
            {..}
        ],
        "linked_refunds": [
            {
                "applied_amount": 100,
                "applied_at": 1517490274,
                "txn_amount": 100,
                "txn_date": 1517490274,
                "txn_id": "txn___test__8asyKSOcTKBP3D",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "other",
        "reference_invoice_id": "__demo_inv__13",
        "refunded_at": 1517490274,
        "resource_version": 1517490274234,
        "round_off_amount": 0,
        "status": "refunded",
        "sub_total": 100,
        "taxes": [],
        "total": 100,
        "type": "refundable",
        "updated_at": 1517490274
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 500,
        "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__8asyKSOcTK1x2z",
        "date": 1517490273,
        "deleted": false,
        "due_date": 1517490273,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__13",
        "is_gifted": false,
        "issued_credit_notes": [
            {
                "cn_create_reason_code": "Other",
                "cn_date": 1517490274,
                "cn_id": "__demo_cn__3",
                "cn_reason_code": "other",
                "cn_status": "refunded",
                "cn_total": 100
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 500,
                "customer_id": "__test__8asyKSOcTK1x2z",
                "date_from": 1517490273,
                "date_to": 1517490273,
                "description": "SSL Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "ssl-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTK6f37",
                "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": 500
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 500,
                "applied_at": 1517490274,
                "txn_amount": 500,
                "txn_date": 1517490274,
                "txn_id": "txn___test__8asyKSOcTKA438",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 500,
        "object": "invoice",
        "paid_at": 1517490274,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517490274233,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 500,
        "tax": 0,
        "term_finalized": true,
        "total": 500,
        "updated_at": 1517490274,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 100,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTK1x2z",
        "date": 1517490274,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__8asyKSOcTKBP3D",
        "linked_credit_notes": [
            {
                "applied_amount": 100,
                "applied_at": 1517490274,
                "cn_create_reason_code": "Other",
                "cn_date": 1517490274,
                "cn_id": "__demo_cn__3",
                "cn_reason_code": "other",
                "cn_reference_invoice_id": "__demo_inv__13",
                "cn_status": "refunded",
                "cn_total": 100
            },
            {..}
        ],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "resource_version": 1517490274235,
        "status": "success",
        "type": "refund",
        "updated_at": 1517490274
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/record_refund

Method

comment[]
optional, string, max chars=65k
Remarks, if any, on the refund.
customer_notes[]
optional, string, max chars=2000
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
transaction[amount]
optional, in cents, min=1
transaction[payment_method]
required, enumerated string
Possible values are
cashCashcheckCheckchargebackOnly applicable for a transaction of type = refund. This value is set by Chargebee when an automated chargeback occurs. You can also set this explicitly when recording a refund.bank_transferBank Transfer
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
transaction[custom_payment_method_id]
optional, string, max chars=50
transaction[date]
required, timestamp(UTC) in seconds
credit_note[reason_code]
optional, enumerated string
Possible values are
chargebackCan be set when you are recording your customer Chargebacksproduct_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Change
Show all values[+]
credit_note[create_reason_code]
optional, string, max chars=100
invoice invoice
always returned
Resource object representing invoice
transaction transaction
optional
Resource object representing transaction
credit_note credit_note
optional
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

This API removes payments applied to an invoice. Once the applied payment is removed, the invoice status returns to not_paid or payment_due. The removed payment is then added to the customer's excess payment balance.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_payment \
     -u {site_api_key}:\
     -d transaction[id]="txn___test__8asyKSOcUWoQ6y"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1000,
        "amount_paid": 0,
        "amount_to_collect": 1000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aso8SOcUUT02s",
        "date": 1612796956,
        "deleted": false,
        "due_date": 1612796956,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796957,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8aso8SOcUWbP3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aso8SOcUUT02s",
                "date_from": 1612796956,
                "date_to": 1612883356,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8aso8SOcUWYm3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8aso8SOcUUT02s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612796957,
                "txn_amount": 1000,
                "txn_date": 1612796957,
                "txn_id": "txn___test__8aso8SOcUWbP3v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490561162,
        "round_off_amount": 0,
        "status": "posted",
        "sub_total": 1000,
        "subscription_id": "__test__8aso8SOcUUT02s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490561,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 1000,
        "amount_unused": 1000,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__8aso8SOcUUT02s",
        "date": 1517490561,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__8aso8SOcUTvz1y",
        "id": "txn___test__8asyKSOcUWoQ6y",
        "id_at_gateway": "cb___test__8asyKSOcUWoU6z",
        "linked_invoices": [],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__8asyKSOcUWmm6r",
        "resource_version": 1517490561166,
        "status": "success",
        "type": "payment",
        "updated_at": 1517490561
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/remove_payment

Method

transaction[id]
required, string, max chars=40
invoice invoice
always returned
Resource object representing invoice
transaction transaction
always returned
Resource object representing transaction

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

This API removes a credit note attached to an invoice. When you remove a credit note from an invoice, the invoice status returns to not_paid.

Note: You cannot remove a credit note from an invoice if it has already been refunded.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__16/remove_credit_note \
     -u {site_api_key}:\
     -d credit_note[id]="__demo_cn__5"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 3000,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Service Unsatisfactory",
        "currency_code": "USD",
        "customer_id": "__test__8asyKSOcTKTb3h",
        "date": 1517490275,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__5",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 3000,
                "customer_id": "__test__8asyKSOcTKTb3h",
                "date_from": 1517490275,
                "date_to": 1517490275,
                "description": "SSL Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "ssl-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTKdj3w",
                "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": 3000
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "service_unsatisfactory",
        "reference_invoice_id": "__demo_inv__15",
        "resource_version": 1517490276708,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 3000,
        "taxes": [],
        "total": 3000,
        "type": "refundable",
        "updated_at": 1517490276
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 4000,
        "amount_paid": 0,
        "amount_to_collect": 4000,
        "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__8asyKSOcTKTb3h",
        "date": 1517490276,
        "deleted": false,
        "due_date": 1517490276,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__16",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 4000,
                "customer_id": "__test__8asyKSOcTKTb3h",
                "date_from": 1517490276,
                "date_to": 1517490276,
                "description": "Encryption Charge USD Monthly",
                "discount_amount": 0,
                "entity_id": "encryption-charge-USD",
                "entity_type": "charge_item_price",
                "id": "li___test__8asyKSOcTKia42",
                "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": 4000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517490276709,
        "round_off_amount": 0,
        "status": "not_paid",
        "sub_total": 4000,
        "tax": 0,
        "term_finalized": true,
        "total": 4000,
        "updated_at": 1517490276,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/remove_credit_note

Method

credit_note[id]
required, string, max chars=50
invoice invoice
always returned
Resource object representing invoice
credit_note credit_note
always returned
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Voids the specified invoice. Any payments must be removed from the invoice before voiding it.

  • Any promotional credits or credit notes applied to the invoice are removed.
  • If an invoice for the current term of a subscription is voided and the subscription is changed later with proration enabled, no prorated credits are issued.
  • Any usages associated with item prices in the invoice are delinked from the invoice. This is done by clearing the invoice_id field of said usages. However, before this is done, a usage PDF is generated and saved to the invoice as an attachment.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/void \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1000,
        "amount_paid": 0,
        "amount_to_collect": 1000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8at01SOcUsFk2s",
        "date": 1612797047,
        "deleted": false,
        "due_date": 1612797047,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612797048,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8at01SOcUuIQ3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8at01SOcUsFk2s",
                "date_from": 1612797047,
                "date_to": 1612883447,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8at01SOcUuFN3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8at01SOcUsFk2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612797048,
                "txn_amount": 1000,
                "txn_date": 1612797048,
                "txn_id": "txn___test__8at01SOcUuIQ3v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490652136,
        "round_off_amount": 0,
        "status": "voided",
        "sub_total": 1000,
        "subscription_id": "__test__8at01SOcUsFk2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490652,
        "voided_at": 1517490652,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/void

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
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.
invoice invoice
always returned
Resource object representing invoice
credit_note credit_note
optional
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API writes off an Invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/write_off \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "credit_note": {
        "allocations": [
            {
                "allocated_amount": 1000,
                "allocated_at": 1517490684,
                "invoice_date": 1612797080,
                "invoice_id": "__demo_inv__4",
                "invoice_status": "paid"
            },
            {..}
        ],
        "amount_allocated": 1000,
        "amount_available": 0,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "create_reason_code": "Write Off",
        "currency_code": "USD",
        "customer_id": "__test__8asySSOcV0r62s",
        "date": 1517490684,
        "deleted": false,
        "exchange_rate": 1,
        "fractional_correction": 0,
        "id": "__demo_cn__1",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asySSOcV0r62s",
                "date_from": 1517490684,
                "date_to": 1517490684,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8asyKSOcV2xV8q",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asySSOcV0r62s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "write_off",
        "reference_invoice_id": "__demo_inv__4",
        "refunded_at": 1517490684,
        "resource_version": 1517490684670,
        "round_off_amount": 0,
        "status": "adjusted",
        "sub_total": 1000,
        "subscription_id": "__test__8asySSOcV0r62s",
        "taxes": [],
        "total": 1000,
        "type": "adjustment",
        "updated_at": 1517490684
    },
    "invoice": {
        "adjustment_credit_notes": [
            {
                "cn_create_reason_code": "Write Off",
                "cn_date": 1517490684,
                "cn_id": "__demo_cn__1",
                "cn_reason_code": "write_off",
                "cn_status": "adjusted",
                "cn_total": 1000
            },
            {..}
        ],
        "amount_adjusted": 1000,
        "amount_due": 0,
        "amount_paid": 0,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asySSOcV0r62s",
        "date": 1612797080,
        "deleted": false,
        "due_date": 1612797080,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612797081,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8asySSOcV2l83v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asySSOcV0r62s",
                "date_from": 1612797080,
                "date_to": 1612883480,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8asySSOcV2hz3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asySSOcV0r62s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612797081,
                "txn_amount": 1000,
                "txn_date": 1612797081,
                "txn_id": "txn___test__8asySSOcV2l83v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517490684,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490684658,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "subscription_id": "__test__8asySSOcV0r62s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490684,
        "write_off_amount": 1000
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/write_off

Method

comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
invoice invoice
always returned
Resource object representing invoice
credit_note credit_note
always returned
Resource object representing credit_note

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

Deletes the specified invoice. Any payments must be removed from the invoice before deleting it.

Caution

All associated usages are permanently deleted on deleting an invoice. If you want to regenerate such an invoice, add or bulk import usages before invoice regeneration.

  • Any promotional credits or credit notes applied to the invoice are removed.
  • If an invoice for the current term of a subscription is deleted and the subscription is changed later with proration enabled, no prorated credits are issued.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/delete \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1000,
        "amount_paid": 0,
        "amount_to_collect": 1000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asnHSOcU9yY2s",
        "date": 1612796877,
        "deleted": false,
        "due_date": 1612796877,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796878,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8asnHSOcUCAN3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "in_progress",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asnHSOcU9yY2s",
                "date_from": 1612796877,
                "date_to": 1612883277,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8asnHSOcUC6o3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asnHSOcU9yY2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612796878,
                "txn_amount": 1000,
                "txn_date": 1612796878,
                "txn_id": "txn___test__8asnHSOcUCAN3v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "next_retry_at": 1612883278,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1612796878750,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1000,
        "subscription_id": "__test__8asnHSOcU9yY2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1612796878,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/delete

Method

comment[]
optional, string, max chars=300
Reason for deleting the invoice. This comment will be added to the subscription entity if the invoice belongs to a subscription. It is added to the customer entity if the invoice is associated only with a customer.
claim_credits[]
optional, boolean, default=false
Indicates whether to put prorated credits back to the subscription or ignore while deleting the invoice.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

This API allows you to update the invoice Billing/Shipping address, VAT and PO number. During this operation if Billing Info (Billing Address, vat_number), Shipping info and PO number are not already present in the system the data will be added. If data is already present, the existing values will be replaced. If info is present in the system, but not passed as part of the request, the info will not be removed from the system.

Note: Incase, tax is already applied will now vary due to address change, you cannot update the address. You cannot update the VAT Number if the billing address is not present in the API request.This will update the invoice only, it won't change the corresponding customer/subscription details.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/update_details \
     -u {site_api_key}:\
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 1000,
        "amount_paid": 0,
        "amount_to_collect": 1000,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "city": "Walnut",
            "country": "US",
            "first_name": "John",
            "last_name": "Doe",
            "line1": "PO Box 9999",
            "object": "billing_address",
            "state": "California",
            "state_code": "CA",
            "validation_status": "not_validated",
            "zip": "91789"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aso4SOcUkmt2s",
        "date": 1612797018,
        "deleted": false,
        "due_date": 1612797018,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612797019,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8aso4SOcUmkA3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "in_progress",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aso4SOcUkmt2s",
                "date_from": 1612797018,
                "date_to": 1612883418,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8aso4SOcUmhA3u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8aso4SOcUkmt2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1612797019,
                "txn_amount": 1000,
                "txn_date": 1612797019,
                "txn_id": "txn___test__8aso4SOcUmkA3v",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "next_retry_at": 1612883419,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490623059,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 1000,
        "subscription_id": "__test__8aso4SOcUkmt2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490623,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/update_details

Method

vat_number[]
optional, string, max chars=20
VAT/ Tax registration number of the customer. Learn more.
vat_number_prefix[]
optional, string, max chars=10
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.
po_number[]
optional, string, max chars=100
Purchase Order Number for this invoice.
comment[]
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
billing_address[first_name]
optional, string, max chars=150
billing_address[last_name]
optional, string, max chars=150
billing_address[email]
optional, string, max chars=70
billing_address[company]
optional, string, max chars=250
billing_address[phone]
optional, string, max chars=50
billing_address[line1]
optional, string, max chars=150
billing_address[line2]
optional, string, max chars=150
billing_address[line3]
optional, string, max chars=150
billing_address[city]
optional, string, max chars=50
billing_address[state_code]
optional, string, max chars=50
billing_address[state]
optional, string, max chars=50
billing_address[zip]
optional, string, max chars=20
billing_address[country]
optional, string, max chars=50
billing_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
shipping_address[first_name]
optional, string, max chars=150
shipping_address[last_name]
optional, string, max chars=150
shipping_address[email]
optional, string, max chars=70
shipping_address[company]
optional, string, max chars=250
shipping_address[phone]
optional, string, max chars=50
shipping_address[line1]
optional, string, max chars=150
shipping_address[line2]
optional, string, max chars=150
shipping_address[line3]
optional, string, max chars=150
shipping_address[city]
optional, string, max chars=50
shipping_address[state_code]
optional, string, max chars=50
shipping_address[state]
optional, string, max chars=50
shipping_address[zip]
optional, string, max chars=20
shipping_address[country]
optional, string, max chars=50
shipping_address[validation_status]
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
Show all values[+]
statement_descriptor[descriptor]
optional, string, max chars=65k
statement_descriptor[additional_info]
optional, string, max chars=65k
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
Creates installments for an invoice, enabling the invoice to be paid in multiple, scheduled payments. Note: The invoice must be in payment_due.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/installments \
     -u {site_api_key}:\
     -d config_id="HmeBDXhU50lPuS3i0" \
     -d amount="100000"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8asxfSOcTzpo2s",
        "date": 1612796839,
        "deleted": false,
        "due_date": 1612796839,
        "dunning_attempts": [
            {
                "attempt": 0,
                "created_at": 1612796840,
                "dunning_type": "auto_collect",
                "transaction_id": "txn___test__8asxfSOcU2Ku3v",
                "txn_amount": 1000,
                "txn_status": "failure"
            },
            {..}
        ],
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__4",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8asxfSOcTzpo2s",
                "date_from": 1612796839,
                "date_to": 1612883239,
                "description": "Basic USD 2",
                "discount_amount": 0,
                "entity_id": "basic-USD2",
                "entity_type": "plan_item_price",
                "id": "li___test__8asxfSOcU2D83u",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__8asxfSOcTzpo2s",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517490444,
                "txn_amount": 1000,
                "txn_date": 1517490444,
                "txn_id": "txn___test__8asyKSOcU2bm5W",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517490444,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517490444979,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "subscription_id": "__test__8asxfSOcTzpo2s",
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517490444,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 1000,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__8asxfSOcTzpo2s",
        "date": 1517490444,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__8asxfSOcTyhc1y",
        "id": "txn___test__8asyKSOcU2bm5W",
        "id_at_gateway": "cb___test__8asyKSOcU2bq5X",
        "linked_invoices": [
            {
                "applied_amount": 1000,
                "applied_at": 1517490444,
                "invoice_date": 1612796839,
                "invoice_id": "__demo_inv__4",
                "invoice_status": "paid",
                "invoice_total": 1000
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__8asyKSOcU2Zm5P",
        "resource_version": 1517490444979,
        "status": "success",
        "subscription_id": "__test__8asxfSOcTzpo2s",
        "type": "payment",
        "updated_at": 1517490444
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/installments

Method

config_id[]
required, string
The identifier of the installment_config used to create the installments.
amount[]
optional, in cents, min=0
The part of the invoice.amount_due to be distributed across the installments. If unspecified, the full invoice.amount_due is considered by default.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
Resend failed einvoice of an invoice to the customer using this API.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/resend_einvoice \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "id": "__demo_inv__1",
        "customer_id": "customer",
        "recurring": false,
        "status": "paid",
        "vat_number": "812526315",
        "price_type": "tax_exclusive",
        "date": 1619600068,
        "due_date": 1619600068,
        "net_term_days": 0,
        "exchange_rate": 1,
        "total": 1190,
        "amount_paid": 1190,
        "amount_adjusted": 0,
        "write_off_amount": 0,
        "credits_applied": 0,
        "amount_due": 0,
        "paid_at": 1619600068,
        "updated_at": 1619600076,
        "resource_version": 1619600076416,
        "deleted": false,
        "object": "invoice",
        "first_invoice": false,
        "amount_to_collect": 0,
        "round_off_amount": 0,
        "has_advance_charges": false,
        "currency_code": "USD",
        "base_currency_code": "USD",
        "generated_at": 1619600068,
        "is_gifted": false,
        "term_finalized": true,
        "channel": "web",
        "is_digital": true,
        "einvoice": {
            "id": "HmaT0avT2mtbTL3mR",
            "status": "scheduled",
            "message": "E-invoice sending is scheduled and not yet processed.",
            "object": "einvoice"
        },
        "tax": 190,
        "line_items": [
            {
                "id": "li_HmaT0avT2mtbMt3mD",
                "date_from": 1649356200,
                "date_to": 1649529000,
                "unit_amount": 1000,
                "quantity": 1,
                "amount": 1000,
                "pricing_model": "flat_fee",
                "is_taxed": true,
                "tax_amount": 190,
                "tax_rate": 19,
                "object": "line_item",
                "customer_id": "customer",
                "description": "none",
                "entity_type": "adhoc",
                "metered": false,
                "discount_amount": 0,
                "item_level_discount_amount": 0
            },
            {..}
        ],
        "taxes": [
            {
                "object": "tax",
                "name": "VAT",
                "description": "VAT @ 19%",
                "amount": 190
            },
            {..}
        ],
        "line_item_taxes": [
            {
                "tax_name": "VAT",
                "tax_rate": 19,
                "tax_juris_type": "country",
                "tax_juris_name": "Germany",
                "tax_juris_code": "DE",
                "object": "line_item_tax",
                "line_item_id": "li_HmaT0avT2mtbMt3mD",
                "tax_amount": 190,
                "is_partial_tax_applied": false,
                "taxable_amount": 1000,
                "is_non_compliance_tax": false
            },
            {..}
        ],
        "sub_total": 1000,
        "linked_payments": [
            {
                "txn_id": "txn_HmaT0avT2mtbQ93mJ",
                "applied_amount": 1190,
                "applied_at": 1619600068,
                "txn_status": "success",
                "txn_date": 1619600068,
                "txn_amount": 1190
            },
            {..}
        ],
        "applied_credits": [],
        "adjustment_credit_notes": [],
        "issued_credit_notes": [],
        "linked_orders": [],
        "dunning_attempts": [],
        "billing_address": {
            "country": "DE",
            "validation_status": "not_validated",
            "object": "billing_address"
        }
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/resend_einvoice

Method

invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x

This endpoint is used to send an e-invoice for invoice.

To support cases like TDS and invoice edits, we need to stop auto e-invoice sending and be able to send e-invoices manually.

This endpoint schedules e-invoices manually. This operation is not allowed when any of the following condition matches: 

  • If e-invoicing is not enabled at the site and customer level. 

  • If there is an e-invoice generated already for the invoice.

  • If the “Use automatic e-invoicing “ option is selected.

  • If there are no generated e-invoices with the failed or skipped status.

  • If the invoice status is voided or pending.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/send_einvoice \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "amount_to_collect": 0,
        "applied_credits": [],
        "base_currency_code": "USD",
        "billing_address": {
            "first_name": "Duncan",
            "last_name": "Walpole",
            "object": "billing_address",
            "validation_status": "not_validated"
        },
        "channel": "web",
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__8aswXTV3cHBBk",
        "date": 1517462002,
        "deleted": false,
        "due_date": 1517462002,
        "dunning_attempts": [],
        "exchange_rate": 1,
        "first_invoice": true,
        "generated_at": 1517462002,
        "has_advance_charges": false,
        "id": "__demo_inv__1",
        "is_gifted": false,
        "issued_credit_notes": [],
        "einvoice": {
            "id": "HmaT0avT2mtbTL3mR",
            "status": "scheduled",
            "message": "E-invoice sending is scheduled and not yet processed.",
            "object": "einvoice"
        },
        "line_items": [
            {
                "amount": 1000,
                "customer_id": "__test__8aswXTV3cHBBk",
                "date_from": 1517462002,
                "date_to": 1517462002,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__8aswXTV3cHWst",
                "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": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517462002,
                "txn_amount": 1000,
                "txn_date": 1517462002,
                "txn_id": "txn___test__8aswXTV3cHZEu",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 1000,
        "object": "invoice",
        "paid_at": 1517462002,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517462003147,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517462003,
        "write_off_amount": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice-id}/send_einvoice

Method

invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x