Settings
Configure SDK
Invoices
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
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.
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.
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.
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.
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.
The list of line items for this invoice
The list of all deductions applied to the invoice.
The list of taxes applied for this invoice
The list of transactions for this invoice
The list of orders for this invoice
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:
- Invoice-specific note: It is the note provided via the
invoice_noteparameter for various endpoints in the API that also create invoices. For example, creating a subscription, creating an invoice, and closing a pending invoice. - General note: This note is added to all invoices of the Chargebee site. You can add/edit this note in the Chargebee admin console.
Shipping address for the invoice.
Billing address for the invoice.
Create an 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.
Available Credits and Excess Payments will automatically be applied to this invoice.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as shipping_address[<param name>]
pass parameters as payment_intent[<param name>]
Returns
Resource object representing invoice
Create invoice for a one-time charge ¶
This API generates invoices for a one-time charge.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Create invoice for a non-recurring addon ¶
This API generates invoices for a non-recurring addon.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Stop dunning for invoice ¶
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".
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing invoice
List invoices ¶
Lists all the Invoices.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing invoice
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`.
List invoices for a customer ¶
Lists all the invoices (latest first) for the specified customer.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing invoice
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`.
List invoices for a subscription ¶
Lists all the invoices (latest first) for the specified subscription.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Returns
Resource object representing invoice
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`.
Retrieve an invoice ¶
Retrieve the invoice for the specified invoice id.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing invoice
Sample admin console URL
Retrieve Invoice as PDF ¶
Gets the invoice as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.
Related Tutorial
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing download
Add one-time charge to a pending invoice ¶
This API endpoint adds a one-time charge to a pending invoice.
Sample Response [ JSON ]
URL Format POST
Input Parameters
The amount to be charged. The unit depends on the type of currency .
Returns
Resource object representing invoice
Add non-recurring addon to a pending invoice ¶
This API endpoint adds a non-recurring addon to a pending invoice.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Close pending invoice ¶
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
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing invoice
Collect payment for an invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Resource object representing transaction
Refund an invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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 transaction
s, and not already refunded.
Note:
Any linked_taxes_withheld
associated with the invoice cannot be refunded via this operation.
Returns
Resource object representing invoice
Resource object representing transaction
Record refund for an invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as transaction[<param name>]
Returns
Resource object representing invoice
Resource object representing transaction
Void an invoice ¶
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)
- 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 Response [ JSON ]
URL Format POST
Input Parameters
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 .
Returns
Resource object representing invoice
Delete an invoice ¶
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)
- 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 Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice