API Version
Product Catalog
Library

Invoices are statements containing charges, adjustments and any discounts for a subscription specific to a term. For every subscription a draft invoice (upcoming invoice) is used to track all the charges, credits and adjustments for the current term.

Generally, an invoice is closed at start of the next term. However, cancellation and other such operations on subscription may trigger premature closing. While closing the invoice, in addition to recurring charges, credits and coupons are applied to calculate the final amount that is due.

When invoice is closed, an attempt to charge the credit card is made. If the payment succeeds, it is marked as paid. If the payment fails, the invoice is marked as payment_due and retry settings are taken into account. If no retry attempts are configured, the invoice is marked as not_paid. If the amount due is zero or negative, the invoice is immediately marked as paid and the balance if any is carried forward to the next term of the invoice.

Note: If consolidated invoicing is enabled, the attribute invoice.subscription_id should not be used (as it will not be present if the invoice has lines from multiple subscriptions). Instead to know the related subscriptions, their line_items' subscription_id attribute should be referred.

Sample invoice [ JSON ]

{ "amount": 200, "amount_adjusted": 0, "amount_due": 0, "amount_paid": 200, "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__3Nl7obaRNQyaXr1S", "end_date": 1517492040, "first_invoice": true, "id": "__demo_inv__13", "line_items": [ { "amount": 200, "date_from": 1517492040, "date_to": 1517492040, "description": "non_recurring_addon", "entity_id": "non_recurring_addon", "entity_type": "addon", "is_taxed": false, "object": "line_item", "quantity": 2, "tax": 0, "type": "charge", "unit_amount": 100 } ], "linked_orders": [], "linked_transactions": [ { "applied_amount": 200, "applied_at": 1517492041, "txn_amount": 200, "txn_date": 1517492041, "txn_id": "txn___test__3Nl7obaRNQyacB1a", "txn_status": "success", "txn_type": "payment" } ], "object": "invoice", "paid_on": 1517492041, "price_type": "tax_exclusive", "recurring": false, "start_date": 1517492040, "status": "paid", "sub_total": 200, "tax": 0 }

API Index URL GET

https://{site}.chargebee.com/api/v1/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.payment_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.voidedIndicates a voided invoice.
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[+]
start_date
timestamp(UTC) in seconds
Start date of the invoice.
end_date
optional, timestamp(UTC) in seconds
The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. However, if the invoice is created as pending, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date.
currency_code
string, max chars=3
The currency code (ISO 4217 format) for the invoice
amount
optional, in cents, min=0
Invoiced amount displayed in cents; that is, a decimal point is not present between the whole number and the decimal part. For example, $499.99 is displayed as 49999, and so on.
amount_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.
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_on
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
optional, timestamp(UTC) in seconds
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
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.
tax
in cents, min=0
Total tax amount for this 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.
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.
optional, list of tax
The list of taxes applied for this invoice
linked_transactions
Show attributes [+]
optional, list of invoice_transaction
The list of transactions 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.
billing_address
Show attributes [+]
optional, billing_address
Billing address for the 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.
start_date start_date
timestamp(UTC) in seconds
Start date of the invoice.
end_date end_date
optional, timestamp(UTC) in seconds
The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. However, if the invoice is created as pending, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date.
currency_code currency_code
string, max chars=3
The currency code (ISO 4217 format) for the invoice
amount amount
optional, in cents, min=0
Invoiced amount displayed in cents; that is, a decimal point is not present between the whole number and the decimal part. For example, $499.99 is displayed as 49999, and so on.
amount_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.
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_on
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 next_retry
optional, timestamp(UTC) in seconds
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
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.
tax tax
in cents, min=0
Total tax amount for this invoice
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.
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.
taxes
optional, list of tax
The list of taxes applied for this invoice
linked_transactions
optional, list of invoice_transaction
The list of transactions 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.
billing_address
optional, billing_address
Billing address for the invoice.
Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

Creates a one-off invoice for multiple 'Non Recurring' addon & ad-hoc charges for a customer. If the 'auto collection' has been turned 'on' for that customer then payment will be immediately collected using the payment method associated with the customer. The invoice will be generated only upon successful collection of payments. However if the 'auto collection' is turned 'off', no collection attempt will be made and the invoice generated would have a “Payment Due” status.

The Shipping Address can be passed, which will then be attached to the generated invoice.

A 'One Time' coupon can be explicitly specified while creating this invoice.

Notes

Available Credits and Excess Payments will automatically be applied to this invoice.
Sample Request
# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v1/invoices \
     -u {site_api_key}:\
     -d customer_id="__test__3Nl7obaRNQyaXr1S" \
     -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 addons[id][0]="non_recurring_addon" \
     -d addons[quantity][0]=2 
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 200,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 200,
        "billing_address": {
            "first_name": "John",
            "last_name": "Mathew",
            "object": "billing_address"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyaXr1S",
        "end_date": 1517492040,
        "first_invoice": true,
        "id": "__demo_inv__13",
        "line_items": [
            {
                "amount": 200,
                "date_from": 1517492040,
                "date_to": 1517492040,
                "description": "non_recurring_addon",
                "entity_id": "non_recurring_addon",
                "entity_type": "addon",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 2,
                "tax": 0,
                "type": "charge",
                "unit_amount": 100
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 200,
                "applied_at": 1517492041,
                "txn_amount": 200,
                "txn_date": 1517492041,
                "txn_id": "txn___test__3Nl7obaRNQyacB1a",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492041,
        "price_type": "tax_exclusive",
        "recurring": false,
        "start_date": 1517492040,
        "status": "paid",
        "sub_total": 200,
        "tax": 0
    }
}

URL Format POST

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

Method

customer_id[]
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.(not applicable for consolidated invoice).
po_number[]
optional, string, max chars=100
Purchase Order Number for this invoice.
coupon[]
optional, string, max chars=100
The 'One Time' coupon to be applied.
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.
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
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[reference_id]
optional, string, max chars=65k
addons[id][0..n]
optional, string, max chars=100
addons[quantity][0..n]
optional, integer, default=1, min=1
charges[amount][0..n]
optional, in cents, min=1
charges[description][0..n]
optional, string, max chars=250
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API generates invoices for a one-time charge.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/charge \
     -u {site_api_key}:\
     -d subscription_id="__test__3Nl7obaRNQyaqJ24" \
     -d amount=1000 \
     -d description="Support Charge"
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 1000,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyaqJ24",
        "end_date": 1517492042,
        "first_invoice": true,
        "id": "__demo_inv__17",
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517492042,
                "date_to": 1517492042,
                "description": "Support Charge",
                "entity_type": "adhoc",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 1000,
                "applied_at": 1517492042,
                "txn_amount": 1000,
                "txn_date": 1517492042,
                "txn_id": "txn___test__3Nl7obaRNQyavf2K",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492042,
        "price_type": "tax_exclusive",
        "recurring": false,
        "start_date": 1517492042,
        "status": "paid",
        "sub_total": 1000,
        "subscription_id": "__test__3Nl7obaRNQyaqJ24",
        "tax": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/charge

Method

customer_id[]
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.(not applicable for consolidated invoice).
amount[]
optional, in cents, min=1
The amount to be charged. The unit depends on the type of currency.
description[]
required, string, max chars=250
Description for this charge.
coupon[]
optional, string, max chars=100
The 'One Time' coupon to be applied. Supported only if this one-off invoice is associated with a Customer(i.e customer_id is specified).
po_number[]
optional, string, max chars=100
Purchase Order Number for this invoice.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API generates invoices for a non-recurring addon.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/charge_addon \
     -u {site_api_key}:\
     -d subscription_id="__test__3Nl7obaRNQyagm1k" \
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=2
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 200,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 200,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyagm1k",
        "end_date": 1517492041,
        "first_invoice": true,
        "id": "__demo_inv__15",
        "line_items": [
            {
                "amount": 200,
                "date_from": 1517492041,
                "date_to": 1517492041,
                "description": "non_recurring_addon",
                "entity_id": "non_recurring_addon",
                "entity_type": "addon",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 2,
                "tax": 0,
                "type": "charge",
                "unit_amount": 100
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 200,
                "applied_at": 1517492041,
                "txn_amount": 200,
                "txn_date": 1517492041,
                "txn_id": "txn___test__3Nl7obaRNQyanA20",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492041,
        "price_type": "tax_exclusive",
        "recurring": false,
        "start_date": 1517492041,
        "status": "paid",
        "sub_total": 200,
        "subscription_id": "__test__3Nl7obaRNQyagm1k",
        "tax": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/charge_addon

Method

customer_id[]
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
subscription_id[]
optional, string, max chars=50
Identifier of the subscription for which this invoice(not applicable for consolidated invoice) needs to be created. Should be specified if 'customer_id' is not specified.
addon_id[]
required, string, max chars=100
The ID of the non-recurring addon to be charged.
addon_quantity[]
optional, integer, min=1
The number of addon units to be charged. Mandatory for quantity based addons.
coupon[]
optional, string, max chars=100
The 'One Time' coupon to be applied. Supported only if this one-off invoice is associated with a Customer(i.e customer_id is specified).
po_number[]
optional, string, max chars=100
Purchase Order Number for this invoice.
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/v1/invoices/__demo_inv__36/stop_dunning \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 895,
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQyfFj4F",
        "dunning_status": "stopped",
        "end_date": 1554824059,
        "first_invoice": false,
        "id": "__demo_inv__36",
        "line_items": [
            {
                "amount": 895,
                "date_from": 1554824059,
                "date_to": 1557416059,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 895,
                "applied_at": 1554824060,
                "txn_amount": 895,
                "txn_date": 1554824060,
                "txn_id": "txn___test__3Nl7oZlRNQyfRf4m",
                "txn_status": "failure",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1554730458,
        "status": "not_paid",
        "sub_total": 895,
        "subscription_id": "__test__3Nl7oZlRNQyfFj4F",
        "tax": 0
    }
}

URL Format POST

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

Method

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/v1/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "invoice": {
                "amount": 895,
                "amount_adjusted": 0,
                "amount_due": 0,
                "amount_paid": 895,
                "billing_address": {
                    "first_name": "Rachel",
                    "last_name": "Green",
                    "object": "billing_address"
                },
                "credits_applied": 0,
                "currency_code": "USD",
                "customer_id": "__test__3Nl7oZlRNQya2D1h",
                "dunning_status": "stopped",
                "end_date": 1554824039,
                "first_invoice": false,
                "id": "__demo_inv__12",
                "line_items": [
                    {
                        "amount": 895,
                        "date_from": 1554824039,
                        "date_to": 1557416039,
                        "description": "No Trial",
                        "entity_id": "no_trial",
                        "entity_type": "plan",
                        "is_taxed": false,
                        "object": "line_item",
                        "quantity": 1,
                        "tax": 0,
                        "type": "charge",
                        "unit_amount": 895
                    },
                    {..}
                ],
                "linked_orders": [],
                "linked_transactions": [
                    {
                        "applied_amount": 895,
                        "applied_at": 1517492040,
                        "txn_amount": 895,
                        "txn_date": 1517492040,
                        "txn_id": "txn___test__3Nl7obaRNQyaUq1O",
                        "txn_status": "success",
                        "txn_type": "payment"
                    },
                    {..}
                ],
                "object": "invoice",
                "paid_on": 1517492040,
                "price_type": "tax_exclusive",
                "recurring": true,
                "start_date": 1554730438,
                "status": "paid",
                "sub_total": 895,
                "subscription_id": "__test__3Nl7oZlRNQya2D1h",
                "tax": 0
            }
        },
        {..}
    ],
    "next_offset": "[\"1554730442000\",\"192000000084\"]"
}

URL Format GET

https://{site}.chargebee.com/api/v1/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.
paid_on_after[]
optional, timestamp(UTC) in seconds
Returns only the invoices that got paid at/after this time. Invoices list will be sorted by 'paid_on' in ascending order.
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
Lists all the invoices (latest first) for the specified customer.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/customers/__test__3Nl7obaRNQybMo2n/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "invoice": {
                "amount": 400,
                "amount_adjusted": 0,
                "amount_due": 0,
                "amount_paid": 400,
                "billing_address": {
                    "first_name": "John",
                    "last_name": "Mathew",
                    "object": "billing_address"
                },
                "credits_applied": 0,
                "currency_code": "USD",
                "customer_id": "__test__3Nl7obaRNQybMo2n",
                "end_date": 1517492044,
                "first_invoice": false,
                "id": "__demo_inv__22",
                "line_items": [
                    {
                        "amount": 400,
                        "date_from": 1517492044,
                        "date_to": 1517492044,
                        "description": "non_recurring_addon",
                        "entity_id": "non_recurring_addon",
                        "entity_type": "addon",
                        "is_taxed": false,
                        "object": "line_item",
                        "quantity": 2,
                        "tax": 0,
                        "type": "charge",
                        "unit_amount": 200
                    },
                    {..}
                ],
                "linked_orders": [],
                "linked_transactions": [
                    {
                        "applied_amount": 400,
                        "applied_at": 1517492044,
                        "txn_amount": 400,
                        "txn_date": 1517492044,
                        "txn_id": "txn___test__3Nl7obaRNQybRd31",
                        "txn_status": "success",
                        "txn_type": "payment"
                    },
                    {..}
                ],
                "object": "invoice",
                "paid_on": 1517492044,
                "price_type": "tax_exclusive",
                "recurring": false,
                "start_date": 1517492044,
                "status": "paid",
                "sub_total": 400,
                "tax": 0
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v1/customers/{customer-id}/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.
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
Lists all the invoices (latest first) for the specified subscription.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__3Nl7obaRNQybUb35/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "list": [
        {
            "invoice": {
                "amount": 1000,
                "amount_adjusted": 0,
                "amount_due": 0,
                "amount_paid": 1000,
                "credits_applied": 0,
                "currency_code": "USD",
                "customer_id": "__test__3Nl7obaRNQybUb35",
                "end_date": 1517492044,
                "first_invoice": true,
                "id": "__demo_inv__24",
                "line_items": [
                    {
                        "amount": 1000,
                        "date_from": 1517492044,
                        "date_to": 1517492044,
                        "description": "non_recurring_addon",
                        "entity_id": "non_recurring_addon",
                        "entity_type": "addon",
                        "is_taxed": false,
                        "object": "line_item",
                        "quantity": 2,
                        "tax": 0,
                        "type": "charge",
                        "unit_amount": 500
                    },
                    {..}
                ],
                "linked_orders": [],
                "linked_transactions": [
                    {
                        "applied_amount": 1000,
                        "applied_at": 1517492044,
                        "txn_amount": 1000,
                        "txn_date": 1517492044,
                        "txn_id": "txn___test__3Nl7obaRNQybaB3L",
                        "txn_status": "success",
                        "txn_type": "payment"
                    },
                    {..}
                ],
                "object": "invoice",
                "paid_on": 1517492044,
                "price_type": "tax_exclusive",
                "recurring": false,
                "start_date": 1517492044,
                "status": "paid",
                "sub_total": 1000,
                "subscription_id": "__test__3Nl7obaRNQybUb35",
                "tax": 0
            }
        },
        {..}
    ]
}

URL Format GET

https://{site}.chargebee.com/api/v1/subscriptions/{subscription-id}/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.
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/v1/invoices/__demo_inv__33 \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 1000,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "billing_address": {
            "first_name": "Duncan",
            "last_name": "Walpole",
            "object": "billing_address"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQycrd4j",
        "end_date": 1517492049,
        "first_invoice": true,
        "id": "__demo_inv__33",
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517492049,
                "date_to": 1517492049,
                "description": "Support Charge",
                "entity_type": "adhoc",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 1000,
                "applied_at": 1517492049,
                "txn_amount": 1000,
                "txn_date": 1517492049,
                "txn_id": "txn___test__3Nl7obaRNQyctZ4r",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492049,
        "price_type": "tax_exclusive",
        "recurring": false,
        "start_date": 1517492049,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0
    }
}

URL Format GET

https://{site}.chargebee.com/api/v1/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/v1/invoices/__demo_inv__34/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__3Nl7obaRNQydzC57.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Finvoice%2F__test__3Nl7obaRNQydzC57.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190412T133418Z&X-Amz-SignedHeaders=host&X-Amz-Expires=-37583940&X-Amz-Credential=AKIAJI4SN7ONHAOGLOGA%2F20190412%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=74cab3c7d5a8b494dcc0a5e97dcca8c1feeb36b1cb79e4455d1f2bbdfd5404b7",
        "object": "download",
        "valid_till": 1517492118
    }
}

URL Format POST

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

Method

download download
always returned
Resource object representing download

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API endpoint adds a one-time charge to a pending invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/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": {
        "amount": 15517,
        "amount_adjusted": 0,
        "amount_due": 15517,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQyYJIT",
        "end_date": 1517492032,
        "first_invoice": false,
        "id": "__demo_inv__4",
        "line_items": [
            {
                "amount": 15367,
                "date_from": 1517492032,
                "date_to": 1557322432,
                "description": "Basic - Prorated Charges",
                "entity_id": "basic",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "prorated_charge",
                "unit_amount": 15367
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1554730432,
        "status": "pending",
        "sub_total": 15517,
        "subscription_id": "__test__3Nl7oZlRNQyYJIT",
        "tax": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/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.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

https://{site}.chargebee.com/admin-console/invoices/123x
This API endpoint adds a non-recurring addon to a pending invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/add_addon_charge \
     -u {site_api_key}:\
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=2
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 15567,
        "amount_adjusted": 0,
        "amount_due": 15567,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQyWydF",
        "end_date": 1517492029,
        "first_invoice": false,
        "id": "__demo_inv__2",
        "line_items": [
            {
                "amount": 15367,
                "date_from": 1517492029,
                "date_to": 1557322427,
                "description": "Basic - Prorated Charges",
                "entity_id": "basic",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "prorated_charge",
                "unit_amount": 15367
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1554730427,
        "status": "pending",
        "sub_total": 15567,
        "subscription_id": "__test__3Nl7oZlRNQyWydF",
        "tax": 0
    }
}

URL Format POST

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

Method

addon_id[]
required, string, max chars=100
The ID of the non-recurring addon to be charged.
addon_quantity[]
optional, integer, min=1
The number of addon units to be charged. Mandatory for quantity based addons.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

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

This API closes the 'pending' invoice. If "metered billing" is used, please ensure that the usage charges are added before invoking this API.

If the ‘Auto-Collection' is turned ‘ON' for the particular customer, the payment for this invoice will be automatically collected.

While closing the pending invoice, the invoice number will be assigned based on the current invoice number sequence. The invoice end date will also be updated with the date of closure.

Available Credits and Excess Payments will automatically be applied while closing the pending invoice.

Closing a pending invoice would be allowed only if the invoice consists of atleast one line-item. Invoices without line-items cannot be closed. However, they can be deleted using the Delete Invoice API.

Related Tutorial

Notes

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

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 29500,
        "amount_adjusted": 0,
        "amount_due": 28605,
        "amount_paid": 0,
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address"
        },
        "credits_applied": 895,
        "currency_code": "USD",
        "customer_id": "__test__KyVm1KS1QTaBhz",
        "end_date": 1517496365,
        "first_invoice": false,
        "id": "__demo_inv__2",
        "line_items": [
            {
                "amount": 29500,
                "date_from": 1517496365,
                "date_to": 1593960364,
                "description": "Basic - Prorated Charges",
                "entity_id": "basic",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "prorated_charge",
                "unit_amount": 29500
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "next_retry": 1517496371,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1591368364,
        "status": "payment_due",
        "sub_total": 29500,
        "subscription_id": "__test__KyVm1KS1QTaBhz",
        "tax": 0
    }
}

URL Format POST

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

Method

invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

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

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

Notes

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

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 895,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 895,
        "billing_address": {
            "first_name": "Rachel",
            "last_name": "Green",
            "object": "billing_address"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQya2D1h",
        "dunning_status": "stopped",
        "end_date": 1554824039,
        "first_invoice": false,
        "id": "__demo_inv__12",
        "line_items": [
            {
                "amount": 895,
                "date_from": 1554824039,
                "date_to": 1557416039,
                "description": "No Trial",
                "entity_id": "no_trial",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 895,
                "applied_at": 1517492040,
                "txn_amount": 895,
                "txn_date": 1517492040,
                "txn_id": "txn___test__3Nl7obaRNQyaUq1O",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492040,
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1554730438,
        "status": "paid",
        "sub_total": 895,
        "subscription_id": "__test__3Nl7oZlRNQya2D1h",
        "tax": 0
    },
    "transaction": {
        "amount": 895,
        "amount_unused": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQya2D1h",
        "date": 1517492040,
        "gateway": "chargebee",
        "id": "txn___test__3Nl7obaRNQyaUq1O",
        "id_at_gateway": "cb___test__3Nl7obaRNQyaUw1P",
        "linked_invoices": [
            {
                "applied_amount": 895,
                "applied_at": 1517492040,
                "invoice_amount": 895,
                "invoice_date": 1554824039,
                "invoice_id": "__demo_inv__12"
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "status": "success",
        "subscription_id": "__test__3Nl7oZlRNQya2D1h",
        "type": "payment"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/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.
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

A refund returns money to a customer. The refund request is processed via the payment gateway that was used to charge the customer.

You can choose to either make a full refund for the entire amount or you can do as many partial refunds until you reach the total amount charged for the invoice.

Read more on refunds in our docs.

Error will be thrown if you attempt to:

  • refund an offline invoice. To record refund for such invoices, use this API.
  • refund an entirely refunded invoice.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__28/refund \
     -u {site_api_key}:\
     -d refund_amount=1000
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 1000,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "billing_address": {
            "first_name": "John",
            "last_name": "Mathew",
            "object": "billing_address"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyc8r3k",
        "end_date": 1517492047,
        "first_invoice": true,
        "id": "__demo_inv__28",
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517492047,
                "date_to": 1517492047,
                "description": "Support Charge",
                "entity_type": "adhoc",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 1000,
                "applied_at": 1517492047,
                "txn_amount": 1000,
                "txn_date": 1517492047,
                "txn_id": "txn___test__3Nl7obaRNQycBM3s",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492047,
        "price_type": "tax_exclusive",
        "recurring": false,
        "start_date": 1517492047,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0
    },
    "transaction": {
        "amount": 1000,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyc8r3k",
        "date": 1517492047,
        "gateway": "chargebee",
        "id": "txn___test__3Nl7obaRNQycE03w",
        "id_at_gateway": "cb___test__3Nl7obaRNQycBW3t",
        "linked_invoices": [
            {
                "applied_amount": 1000,
                "applied_at": 1517492047,
                "invoice_amount": 1000,
                "invoice_date": 1517492047,
                "invoice_id": "__demo_inv__28"
            },
            {..}
        ],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "refunded_txn_id": "txn___test__3Nl7obaRNQycBM3s",
        "status": "success",
        "type": "refund"
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/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.
memo[]
optional, string, max chars=300
Comment, if any, on the refund.
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

Offline refunds can be recorded for invoices that have been paid via card payments, Amazon Payments, Paypal Express Checkout, as well as offline payments.

Read more on refunds in our docs.

Notes

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__27/record_refund \
     -u {site_api_key}:\
     -d memo="Refunding as customer cancelled the order." \
     -d transaction[amount]=100 \
     -d transaction[payment_method]="BANK_TRANSFER" \
     -d transaction[date]=1517492046
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 1000,
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 1000,
        "billing_address": {
            "first_name": "John",
            "last_name": "Mathew",
            "object": "billing_address"
        },
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyc0J3P",
        "end_date": 1517492046,
        "first_invoice": true,
        "id": "__demo_inv__27",
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517492046,
                "date_to": 1517492046,
                "description": "Support Charge",
                "entity_type": "adhoc",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "charge",
                "unit_amount": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [
            {
                "applied_amount": 1000,
                "applied_at": 1517492046,
                "txn_amount": 1000,
                "txn_date": 1517492046,
                "txn_id": "txn___test__3Nl7obaRNQyc2P3X",
                "txn_status": "success",
                "txn_type": "payment"
            },
            {..}
        ],
        "object": "invoice",
        "paid_on": 1517492046,
        "price_type": "tax_exclusive",
        "recurring": false,
        "start_date": 1517492046,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0
    },
    "transaction": {
        "amount": 100,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7obaRNQyc0J3P",
        "date": 1517492046,
        "description": "Refunding as customer cancelled the order.",
        "gateway": "not_applicable",
        "id": "txn___test__3Nl7obaRNQyc4j3b",
        "linked_invoices": [
            {
                "applied_amount": 100,
                "applied_at": 1517492046,
                "invoice_amount": 1000,
                "invoice_date": 1517492046,
                "invoice_id": "__demo_inv__27"
            },
            {..}
        ],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "status": "success",
        "type": "refund"
    }
}

URL Format POST

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

Method

memo[]
required, string, max chars=65k
Remarks, if any, on the refund.
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[date]
required, timestamp(UTC) in seconds
invoice invoice
always returned
Resource object representing invoice
transaction transaction
optional
Resource object representing transaction

Sample admin console URL

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

This API voids the specified invoice. If the invoice has been successfully voided using this API, the response will contain the voided 'invoice' object and 'Invoice Updated' event will be triggered. If the void has not been successful, a corresponding error message would be returned.

Voiding an invoice is not possible

  • If the invoice has successful payment(s)
  • If the invoice has credit adjustment(s)

Notes

  • Please note that, if the current term invoice is voided and if the subscription is changed with the ‘proration’ enabled, the pro-rated credits will not be created for the subscription.
  • If the invoice that is voided has Promotional Credits applied to it, the same will be reclaimed.
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__40/void \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 15367,
        "amount_adjusted": 0,
        "amount_due": 15367,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQyfsd5n",
        "end_date": 1517492061,
        "first_invoice": false,
        "id": "__demo_inv__40",
        "line_items": [
            {
                "amount": 15367,
                "date_from": 1517492061,
                "date_to": 1557322461,
                "description": "Basic - Prorated Charges",
                "entity_id": "basic",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "prorated_charge",
                "unit_amount": 15367
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1554730461,
        "status": "voided",
        "sub_total": 15367,
        "subscription_id": "__test__3Nl7oZlRNQyfsd5n",
        "tax": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/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.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

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

This API deletes the specified invoice. If the invoice has been successfully deleted using this API, the response will contain the deleted 'invoice' object. If the deletion has not been successful, a corresponding error message would be returned.

Deleting an invoice is not possible

  • If the invoice has successful payment(s)
  • If the invoice has credit adjustment(s)

Notes

  • Please note that, after the current term invoice is deleted, if the subscription is changed with the ‘proration’ enabled, the pro-rated credits will not be created for the subscription.
  • Any Promotional Credits applied to this invoice would be reclaimed.
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__19/delete \
     -X POST  \
     -u {site_api_key}:
copy
Click to Copy

Sample Response [ JSON ]

Show more...
{
    "invoice": {
        "amount": 15367,
        "amount_adjusted": 0,
        "amount_due": 15367,
        "amount_paid": 0,
        "credits_applied": 0,
        "currency_code": "USD",
        "customer_id": "__test__3Nl7oZlRNQyay82T",
        "end_date": 1517492042,
        "first_invoice": false,
        "id": "__demo_inv__19",
        "line_items": [
            {
                "amount": 15367,
                "date_from": 1517492042,
                "date_to": 1557322442,
                "description": "Basic - Prorated Charges",
                "entity_id": "basic",
                "entity_type": "plan",
                "is_taxed": false,
                "object": "line_item",
                "quantity": 1,
                "tax": 0,
                "type": "prorated_charge",
                "unit_amount": 15367
            },
            {..}
        ],
        "linked_orders": [],
        "linked_transactions": [],
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "start_date": 1554730442,
        "status": "pending",
        "sub_total": 15367,
        "subscription_id": "__test__3Nl7oZlRNQyay82T",
        "tax": 0
    }
}

URL Format POST

https://{site}.chargebee.com/api/v1/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.
invoice invoice
always returned
Resource object representing invoice

Sample admin console URL

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