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.
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:
paid
.payment_due
and dunning settings are taken into account for payment retries. not_paid
. paid
and the balance, if any, is added to excess payments for the customer. Note: If consolidated invoicing is enabled, the attribute subscription_id
is unavailable when the invoice has line items from multiple subscriptions. The individual subscription ids are seen under line_items.subscription_id
.
{
"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
}
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. 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. Note that when converting foreign currency invoices to local currency for VAT purposes, the exchange rates used differ from the base currency exchange rate provided in this field. This is due to regulations set by tax authorities, which require the use of official sources such as European Central Bank rates for local currency conversion. To calculate the exchange rate utilized for VAT in local currency, you may use the following formula.
Exchange rate = tax_amount_in_local_currency / tax_amount
linked_payments[].txn_amount
for all linked_payments[]
that have txn_status
as success
. total
- amount_paid
- sum of applied_credits.applied_amount
- sum of adjustment_credit_notes.cn_total
- sum of linked_taxes_withheld.amount
. line_items[].amount
- the sum of all line_item_discounts[].discount_amount
. 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. 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. amount_due
- the sum of linked_payments[].txn_amount
for all linked_payments[]
that have txn_status
as in_progress
. billing_address
country
as XI
(which is United Kingdom - Northern Ireland).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. 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_note
parameter for various endpoints in the API that also create invoices. For example, creating a subscription, creating an invoice, and closing a pending invoice.tax_withheld
against this invoice. Creates an invoice for charge-items and one-time charges. The item prices must belong to items of type
charge
.
One-time charges are represented in an invoice as line_items
with entity_type
adhoc
.
# creates an invoice for 'Non Recurring' addon for a customer. curl https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges \ -u {site_api_key}:\ -d customer_id="__test__KyVkkWS1xLskm8" \ -d shipping_address[first_name]="John" \ -d shipping_address[last_name]="Mathew" \ -d shipping_address[city]="Walnut" \ -d shipping_address[state]="California" \ -d shipping_address[zip]="91789" \ -d shipping_address[country]="US" \ -d item_prices[item_price_id][0]="ssl-charge-USD" \ -d item_prices[unit_price][0]=2000
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.
true
to remove the general note from this invoice. 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. curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/stop_dunning \ -X POST \ -u {site_api_key}:
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.
curl https://{site}.chargebee.com/api/v2/invoices/import_invoice \ -u {site_api_key}:\ -d id="old_inv_001" \ -d customer_id="__test__8asyKSOcTJGo2N" \ -d subscription_id="__test__8asyKSOcTJMw2U" \ -d date=1517490271 \ -d total=4900 \ -d status="PAYMENT_DUE" \ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US" \ -d line_items[date_from][1]=1517490271 \ -d line_items[date_to][1]=1519909471 \ -d line_items[description][1]="Standard" \ -d line_items[unit_amount][1]=4900 \ -d line_items[quantity][1]=1 \ -d line_items[entity_type][1]="PLAN_ITEM_PRICE" \ -d line_items[entity_id][1]="standard-USD"
billing_address
country
as XI
(which is United Kingdom - Northern Ireland).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 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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_payments \ -X POST \ -u {site_api_key}:
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.
curl https://{site}.chargebee.com/api/v2/invoices/draft_inv_AwSNuHT1ebuqgOu/sync_usages \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/delete_line_items \ -X POST \ -u {site_api_key}:\ -d line_items[id][0]="test"
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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/apply_credits \ -X POST \ -u {site_api_key}:
Lists all the Invoices.
curl https://{site}.chargebee.com/api/v2/invoices \ -G \ -u {site_api_key}:\ --data-urlencode limit=5 \ --data-urlencode status[in]=["paid","payment_due"] \ --data-urlencode sort_by[asc]=date
linked_payments[].txn_amount
for all linked_payments[]
that have txn_status
as success
. total
- amount_paid
- sum of applied_credits.applied_amount
- sum of adjustment_credit_notes.cn_total
- sum of linked_taxes_withheld.amount
. 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. status
, see message
. Possible values are : scheduled, skipped, in_progress, success, failed, registered curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__17 \ -u {site_api_key}:
Gets the invoice as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__18/pdf \ -X POST \ -u {site_api_key}:
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
status
is success
.cbc:EmbeddedDocumentBinaryObject
, which is the Base64-encoded version of the PDF.curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/download_einvoice \ -u {site_api_key}:
invoice_id
or the payment_reference_number[number]
to retrieve the PRN.curl https://{site}.chargebee.com/api/v2/invoices/payment_reference_numbers \ -G \ -u {site_api_key}:\ --data-urlencode id[is]="__demo_inv__2"
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
.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \ -u {site_api_key}:\ -d amount=150 \ -d description="$0.05 each for 30 messages"
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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_charge_item \ -u {site_api_key}:\ -d item_price[item_price_id]="ssl-charge-USD" \ -d item_price[unit_price]=495
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.
This operation can be automated by using a site setting. Moreover, the automation can be overridden at the customer and subscription level.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__8/close \ -X POST \ -u {site_api_key}:
true
to remove the general note from this invoice. payment_due
associated with the app_store
and play_store
channels.This API is used to collect payments for payment_due
and not_paid invoices
. If no payment methods are present for the customer or if the payment is unsuccessful, the corresponding error will be thrown.
Pass authorization_transaction_id
to capture the already blocked funds to collect payments. Note that if the invoice due amount is greater than the authorized amount, the invoice status is returned as payment_due
.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/collect_payment \ -u {site_api_key}:\ -d payment_source_id="pm___test__8asyKSOcU2Zm5P"
To record a offline payment for an invoice.
The invoice status will be marked as 'paid' if its amount due becomes 0 because of this recorded payment.
Note: If the payment transaction amount is more than the invoice due amount, the remaining transaction amount will be added to the customer's Excess Payments balance to be used against other invoices.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_payment \ -u {site_api_key}:\ -d comment="Payment received" \ -d transaction[amount]=200 \ -d transaction[payment_method]="BANK_TRANSFER" \ -d transaction[date]=1612800517
Records tax_withheld
by the customer against the invoice specified. This operation is allowed only when all of the following conditions are true:
invoice
does not have a linked_taxes_withheld
record associated with it already.invoice.amount_due
is greater than zero.invoice.status
is one of the following: payment_due
, not_paid
, or posted
.curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_tax_withheld \ -u {site_api_key}:\ -d tax_withheld[amount]=200 \ -d tax_withheld[date]=1635080065
Removes a linked_taxes_withheld
record from the invoice
specified. This operation is allowed only when all of the following conditions are true:
invoice.status
is one of the following: payment_due
, not_paid
, or posted
.adjustment_credit_notes
associated with the invoice.issued_credit_notes
associated with the invoice.curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_tax_withheld \ -u {site_api_key}:\ -d tax_withheld[id]="tax_wh___test__8assSSmwIEze1w"
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:
If the refund transaction succeeds, a credit_note
capturing this refund detail is created for the invoice.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__14/refund \ -u {site_api_key}:\ -d refund_amount=500 \ -d credit_note[reason_code]="SERVICE_UNSATISFACTORY"
transaction
s, and not already refunded.
Note: Any linked_taxes_withheld
associated with the invoice cannot be refunded via this operation. Refunds the invoice. The refund is provided against the following in order of precedence:
linked_payments
linked_taxes_withheld
linked_payments
Example
Consider an invoice with the following payments and tax withheld.
When recording a refund worth $40, the refund amount is split as follows:
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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__13/record_refund \ -u {site_api_key}:\ -d transaction[amount]=100 \ -d transaction[payment_method]="BANK_TRANSFER" \ -d transaction[date]=1517490274
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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_payment \ -u {site_api_key}:\ -d transaction[id]="txn___test__8asyKSOcUWoQ6y"
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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__16/remove_credit_note \ -u {site_api_key}:\ -d credit_note[id]="__demo_cn__5"
Voids the specified invoice. Any payments must be removed from the invoice before voiding it.
proration
enabled, no prorated credits are issued. invoice_id
field of said usages. However, before this is done, a usage PDF is generated and saved to the invoice as an attachment. curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/void \ -X POST \ -u {site_api_key}:
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/write_off \ -X POST \ -u {site_api_key}:
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.
proration
enabled, no prorated credits are issued. curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/delete \ -X POST \ -u {site_api_key}:
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.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/update_details \ -u {site_api_key}:\ -d billing_address[first_name]="John" \ -d billing_address[last_name]="Doe" \ -d billing_address[line1]="PO Box 9999" \ -d billing_address[city]="Walnut" \ -d billing_address[state]="California" \ -d billing_address[zip]="91789" \ -d billing_address[country]="US"
billing_address
country
as XI
(which is United Kingdom - Northern Ireland).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. curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/installments \ -u {site_api_key}:\ -d config_id="HmeBDXhU50lPuS3i0" \ -d amount="100000"
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/resend_einvoice \ -X POST \ -u {site_api_key}:
This endpoint is used to send an e-invoice for invoice.
To support cases like TDS and invoice edits, we need to stop auto e-invoice sending and be able to send e-invoices manually.
This endpoint schedules e-invoices manually. This operation is not allowed when any of the following condition matches:
If e-invoicing is not enabled at the site and customer level.
If there is an e-invoice generated already for the invoice.
If the “Use automatic e-invoicing “ option is selected.
If there are no generated e-invoices with the failed
or skipped
status.
If the invoice status is voided
or pending
.
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/send_einvoice \ -X POST \ -u {site_api_key}: