Settings
Configure SDK
Invoices
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_dueand 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
paidand 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
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. 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.
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 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. 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
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. 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.
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. 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. The date and time at which dunning should resume automatically for the invoice. This attribute is present only if dunning is currently paused for the invoice.
See also: Dunning resumption process.
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. 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. 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.
The list of line items for this invoice
The list of all deductions applied to the invoice.
The list of deduction(s) applied for each line item of this invoice
The list of taxes applied for this invoice
The list of taxes applied on line items
A list of store credits applied to line items.
The list of tiers applicable for this line item
The list of transactions for this invoice
The list of dunning_attempts for this invoice
Refundable Credits applied on this invoice.
Adjustments created for this invoice
Credit notes issued 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.
Statement descriptor for the invoice.
Billing address for the invoice.
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.
Details of
tax_withheld against this invoice. It contains site-specific information, including timezone and organisational address.
It represents information about the tax details that are applied to an invoice. Additionally, it specifies the country from which the tax is applied, as well as the relevant tax registration number.
The list of addresses used for tax calculation on line items.
Create invoice for items and one-time charges ¶
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 Response [ JSON ]
URL Format POST
Input Parameters
Unique ID of the customer this invoice should be created for. Either this or subscription_id must be provided.
The invoice is linked to the same business entity as this customer.
Unique ID of the subscription this invoice should be created for. Either this or customer_id must be provided.
The invoice is linked to the same business entity as this subscription.
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
Set as
true to remove the general note from this invoice. 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. pass parameters as shipping_address[<param name>]
pass parameters as card[<param name>]
pass parameters as bank_account[<param name>]
pass parameters as payment_method[<param name>]
pass parameters as payment_intent[<param name>]
pass parameters as item_prices[<param name>][<idx:0..n>]
pass parameters as item_tiers[<param name>][<idx:0..n>]
pass parameters as charges[<param name>][<idx:0..n>]
pass parameters as notes_to_remove[<param name>][<idx:0..n>]
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
pass parameters as discounts[<param name>][<idx:0..n>]
Returns
Resource object representing invoice
Stop dunning for invoice ¶
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
Pause dunning for invoice ¶
Pause dunning for the specified invoice until expected_payment_date. Chargebee cancels all configured payment collection retry attempts and dunning email notifications for the invoice until expected_payment_date.
Prerequisites
This operation is only permitted for an invoice that meets all the following conditions:
- The status of the invoice is
payment_due. - The invoice belongs to a subscription or customer with
auto_collectionset toon. - The invoice does not have dunning paused currently.
Automatic dunning resumption
Unless you resume dunning for the invoice, Chargebee attempts to collect payment on the expected_payment_date. If payment collection fails, the next action is taken as follows:
- If the
expected_payment_dateis within the dunning period for the invoice, Chargebee resumes any dunning retries and email notifications that remain after the pause period, and not attempt the retries or notifications that were canceled during the pause period. - If the
expected_payment_dateis after the dunning period for the invoice, the final action configured in Billing is initiated for the invoice and, if applicable, for the subscription.
Sample Response [ JSON ]
URL Format POST
Input Parameters
The date and time at which dunning should resume.
See also: Dunning resumption process.
An internal comment to add to the invoice for this operation. This comment is displayed on the Chargebee Billing UI.
Note: This comment does not appear on any customer-facing hosted pages or documents, such as the invoice PDF.
Returns
Resource object representing invoice
Resume dunning for invoice ¶
Immediately resumes dunning for the specified invoice.
- If the current time is within the dunning period for the invoice, Chargebee resumes any dunning retries and email notifications that remain after the pause period, and not attempt the retries or notifications that were canceled during the pause period.
- If the current time is after the dunning period for the invoice, the final action configured in Billing is initiated for the invoice and, if applicable, for the subscription.
Prerequisites
This operation is only permitted for an invoice with a status of payment_due and for which dunning was previously paused.
Sample Response [ JSON ]
URL Format POST
Input Parameters
An internal comment to add to the invoice for this operation. This comment is displayed on the Chargebee Billing UI.
Note: This comment does not appear on any customer-facing hosted pages or documents, such as the invoice PDF.
Returns
Resource object representing invoice
Import invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
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. pass parameters as billing_address[<param name>]
pass parameters as shipping_address[<param name>]
pass parameters as line_items[<param name>][<idx:0..n>]
pass parameters as payment_reference_numbers[<param name>][<idx:0..n>]
pass parameters as line_item_tiers[<param name>][<idx:0..n>]
pass parameters as discounts[<param name>][<idx:0..n>]
pass parameters as taxes[<param name>][<idx:0..n>]
pass parameters as payments[<param name>][<idx:0..n>]
pass parameters as notes[<param name>][<idx:0..n>]
pass parameters as line_item_addresses[<param name>][<idx:0..n>]
Returns
Resource object representing invoice
Resource object representing credit_note
Apply payments for an invoice ¶
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.
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
Sync usages ¶
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.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing invoice
Delete Line Items ¶
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Apply credits for an invoice ¶
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.
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
List invoices ¶
Lists all the Invoices.
Sample Response [ JSON ]
URL Format GET
Input Parameters
Filter Params
For operator usages, see the Pagination and Filtering section.
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.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → total[is] = "1000"
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. Supported operators : is, is_not, lt, lte, gt, gte, between
Example → amount_paid[is] = "800"
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. Supported operators : is, is_not, lt, lte, gt, gte, between
Example → amount_due[is] = "200"
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. Supported operators : after, before, on, between
Example → updated_at[after] = "1243545465"
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.
Supported operators : is, is_not, starts_with, in, not_in
Example → void_reason_code[is] = "Other"
pass parameters as einvoice[<param name>][<operator>]
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"
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 ¶
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
Input Parameters
Returns
Resource object representing download
Download e-invoice ¶
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
statusissuccess. - 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.
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing downloads
List payment reference numbers ¶
invoice_id or the payment_reference_number[number] to retrieve the PRN.Sample Response [ JSON ]
URL Format GET
Input Parameters
Filter Params
For operator usages, see the Pagination and Filtering section.
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.
Supported operators : in, is
Example → id[in] = "old_inv_001"
pass parameters as payment_reference_number[<param name>][<operator>]
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.
Supported operators : in, is
Example → payment_reference_number[number][in] = "001234"
Returns
Resource object representing payment_reference_number
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`.
Add one-time charge to a pending invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
The amount to be charged. The unit depends on the type of currency.
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
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.
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.
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.
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:
- India has been enabled as a Tax Region. (An error is returned when this condition is not true.)
- The AvaTax for Sales integration has been enabled in Chargebee.
This represents the TaxJar product code to which the one-time charge is mapped. Applicable only if you use Chargebee's TaxJar integration.
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
Add a charge-item to a pending invoice ¶
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.
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.
pass parameters as item_price[<param name>]
pass parameters as item_tiers[<param name>][<idx:0..n>]
Returns
Resource object representing invoice
Close a pending invoice ¶
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.
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.
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
Set as
true to remove the general note from this invoice. 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.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]
Returns
Resource object representing invoice
Collect payment for an invoice ¶
- 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_dueassociated with theapp_storeandplay_storechannels.
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
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
Resource object representing transaction
Record an invoice payment ¶
Use this API to record an offline payment for the invoice. If the payment covers the full outstanding amount, the invoice status changes to Paid.
- If no transaction amount is specified, the system will automatically use the invoice's due amount as the transaction amount.
- If the payment exceeds the invoice's outstanding balance, the excess amount is added to the customer's Excess Payments balance. This balance can be applied to future invoices.
Implications of the operation
PAID Invoices
When the entire due amount is recorded as a payment, the invoice status is updated to Paid. However, if only a partial amount is recorded as an offline payment, the due amount is reduced, but the invoice status does not change.
PAYMENT_DUE, NOT_PAID & POSTED INVOICES
When the full due amount is recorded as payment, then the invoice status will change to Paid. If a partial amount is recorded as an offline payment, the due amount will be reduced while the invoice status remains unchanged.
FAQs
What happens if I try to record a payment that exceeds the invoice amount?
The system does not allow recording a payment amount greater than the invoice's outstanding balance.
Troubleshooting
The idempotency key provided has already been used for a different request. Use a new idempotency key or ensure the endpoint matches the original request signature. 422 - unable_to_process_request
This API is idempotent. To ensure idempotent behavior, include a custom header named chargebee-idempotency-key with the POST request. If this key is not unique, the Chargebee API returns this error.
Provide a unique idempotency key with the request options to perform an idempotent request.
Operation not supported as the invoice is in Paid, Pending, or Voided state. 409 - invalid_invoice_state
Payments can only be recorded if the invoice has an outstanding due amount. This API cannot be used for invoices with statuses of Paid, Voided, or Pending (Draft Invoice).
- For a paid invoice, remove the payment associated with the invoice before proceeding.
- For a draft invoice, close it to generate the actual invoice and then record the payment against the invoice.
Operation not supported as the collectable amount for this invoice is zero. 409 - record_payment_not_supported
Payments can only be accepted if the invoice amount is greater than zero. Attempting to record a payment against an invoice with zero value results in this error.
Use this API with an invoice that has an amount greater than zero.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as transaction[<param name>]
Returns
Resource object representing invoice
Resource object representing transaction
Record tax withheld for an invoice ¶
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
invoicedoes not have alinked_taxes_withheldrecord associated with it already. invoice.amount_dueis greater than zero.invoice.statusis one of the following:payment_due,not_paid, orposted.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Remove tax withheld for an invoice ¶
Removes a linked_taxes_withheld record from the invoice specified. This operation is allowed only when all of the following conditions are true:
invoice.statusis one of the following:payment_due,not_paid, orposted.- There are no
adjustment_credit_notesassociated with the invoice. - There are no
issued_credit_notesassociated with the invoice.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Refund an invoice ¶
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.
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
transactions, 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
Resource object representing credit_note
Record refund for an invoice ¶
Refunds the invoice. The refund is provided against the following in order of precedence:
- Offline
linked_payments - Any
linked_taxes_withheld - Online
linked_payments
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
pass parameters as transaction[<param name>]
Returns
Resource object representing invoice
Resource object representing transaction
Resource object representing credit_note
Remove payment from an invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Resource object representing transaction
Remove credit note from an invoice ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Resource object representing credit_note
Void an invoice ¶
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
prorationenabled, 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_idfield of said usages. However, before this is done, a usage PDF is generated and saved to the invoice as an attachment.
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
Resource object representing credit_note
Write off an invoice ¶
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
Resource object representing credit_note
Delete an invoice ¶
Deletes the specified invoice. Any payments must be removed from the invoice before deleting it.
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
prorationenabled, no prorated credits are issued.
Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Update invoice details ¶
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.
Sample Response [ JSON ]
URL Format POST
Input Parameters
VAT/ Tax registration number of the customer. Learn more.
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. 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.
pass parameters as billing_address[<param name>]
pass parameters as shipping_address[<param name>]
Returns
Resource object representing invoice
Apply payment schedule scheme to an invoice ¶
payment_due.Sample Response [ JSON ]
URL Format POST
Input Parameters
Returns
Resource object representing invoice
Retrieve payment schedules for an invoice ¶
Sample Response [ JSON ]
URL Format GET
Returns
Resource object representing payment_schedules
Resend failed einvoice in invoices ¶
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing invoice
Send an einvoice for invoices ¶
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
failedorskippedstatus. -
If the invoice status is
voidedorpending.
Sample Response [ JSON ]
URL Format POST
Returns
Resource object representing invoice