You are viewing the documentation for Chargebee API V2. If you're using the older version (V1), click here.

An invoice is a commercial document representing a sale of products/services offered by you to a customer. It enumerates all the charges, adjustments, payments, discounts and taxes associated with the sale.

An invoice is said to be a recurring one when it is has at least one charge for a plan or an addon item price. It is a non-recurring one when it has charges for only charge-item prices or one-time charges.

The item prices for any given billing term of a subscription are billed via an invoice at the beginning of the term (unless the charges are left unbilled). However, item prices that belong to metered items are billed at the end of the term via a pending invoice that can close automatically or via an API call. Moreover, when there are no metered items in the subscription, the invoices can still be generated as pending while creating or updating a subscription.

Auto-collection

If auto-collection is enabled, then immediately on invoice generation (or, in case of subscriptions that have create_pending_invoices as true, on invoice closure), the payment method on file is charged:

  • If the payment succeeds, the invoice is marked as paid.
  • On payment failure, the invoice is marked as payment_due and dunning settings are taken into account for payment retries.
  • If no retry attempts are configured, or when retries are exhausted, the invoice is marked as not_paid.
  • the amount due is zero or negative, the invoice is immediately marked as paid and the balance, if any, is added to excess payments for the customer.

Note: If consolidated invoicing is enabled, the attribute subscription_id is unavailable when the invoice has line items from multiple subscriptions. The individual subscription ids are seen under line_items.subscription_id.

Sample invoice [ JSON ]

{ "adjustment_credit_notes": [], "amount_adjusted": 0, "amount_due": 0, "amount_paid": 2000, "amount_to_collect": 0, "applied_credits": [], "base_currency_code": "USD", "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address", "validation_status": "not_validated" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__KyVkkWS1xLskm8", "date": 1517463749, "deleted": false, "due_date": 1517463749, "dunning_attempts": [], "exchange_rate": 1, "first_invoice": true, "has_advance_charges": false, "id": "__demo_inv__1", "is_gifted": false, "issued_credit_notes": [], "line_items": [{ "amount": 2000, "customer_id": "__test__KyVkkWS1xLskm8", "date_from": 1517463749, "date_to": 1517463749, "description": "SSL Charge USD Monthly", "discount_amount": 0, "entity_id": "ssl-charge-USD", "entity_type": "charge_item_price", "id": "li___test__KyVkkWS1xLt9LF", "is_taxed": false, "item_level_discount_amount": 0, "object": "line_item", "pricing_model": "flat_fee", "quantity": 1, "tax_amount": 0, "tax_exempt_reason": "tax_not_configured", "unit_amount": 2000 }], "linked_orders": [], "linked_payments": [{ "applied_amount": 2000, "applied_at": 1517463750, "txn_amount": 2000, "txn_date": 1517463750, "txn_id": "txn___test__KyVkkWS1xLtFiG", "txn_status": "success" }], "net_term_days": 0, "new_sales_amount": 2000, "object": "invoice", "paid_at": 1517463750, "price_type": "tax_exclusive", "recurring": false, "resource_version": 1517463750000, "round_off_amount": 0, "shipping_address": { "city": "Walnut", "country": "US", "first_name": "John", "last_name": "Mathew", "object": "shipping_address", "state": "California", "state_code": "CA", "validation_status": "not_validated", "zip": "91789" }, "status": "paid", "sub_total": 2000, "tax": 0, "term_finalized": true, "total": 2000, "updated_at": 1517463750, "write_off_amount": 0 }

API Index URL GET

https://{site}.chargebee.com/api/v2/invoices
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: If consolidated invoicing is enabled, to know the subscriptions attached with this invoice you have to refer line_item's subscription_id. This attribute should not be used (which will be null if this invoice has charges from multiple subscriptions).
recurring
boolean, default=true
Boolean indicating whether this invoice belongs to a subscription
status
enumerated string
Current status of this invoice.
Possible values are
paidIndicates a paid invoice.postedIndicates the payment is not yet collected and will be in this state till the due date to indicate the due period.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.pendingThe invoice is yet to be closed (sent for payment collection). An invoice is generated with this status when it has line items that belong to items that are metered or when the subscription.create_pending_invoicesattribute is set to true.
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.
date
optional, timestamp(UTC) in seconds
The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. However, if the invoice is created as pending, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date.
due_date
optional, timestamp(UTC) in seconds
Due date of the invoice
net_term_days
optional, integer, default=0
Number of days within which the invoice has to be paid
exchange_rate
optional, bigdecimal, min=1E-9, max=999999999.999999999
Exchange rate used for base currency conversion
currency_code
string, max chars=3
The currency code (ISO 4217 format) for the invoice
total
optional, in cents, min=0
Invoiced amount displayed in cents; that is, a decimal point is not present between the whole number and the decimal part. For example, $499.99 is displayed as 49999, and so on.
amount_paid
optional, in cents, min=0
Payments collected successfully for the invoice. This is the sum of linked_payments[].txn_amount for all linked_payments[] that have txn_status as success.
amount_adjusted
optional, in cents, default=0, min=0
Total adjustments made against this invoice.
write_off_amount
optional, in cents, default=0, min=0
Amount written off against this invoice.
credits_applied
optional, in cents, default=0, min=0
Total credits applied against this invoice.
amount_due
optional, in cents, min=0
The unpaid amount that is due on the invoice. This is calculated as: total - amount_paid - sum of applied_credits.applied_amount - sum of adjustment_credit_notes.cn_total - sum of linked_taxes_withheld.amount.
paid_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got paid.
dunning_status
optional, enumerated string
Current dunning status of the invoice.
Possible values are
in_progressDunning is still in progress.exhaustedMaximum number of attempts have been made.stoppedDunning has stopped for this invoice.successPayment successfully collected during dunning process.
next_retry_at
optional, timestamp(UTC) in seconds
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
voided_at
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got voided.
resource_version
optional, long
The version number of this resource. For every change made to the resource, resource_version is updated with a new timestamp in milliseconds.
updated_at
optional, timestamp(UTC) in seconds
Timestamp indicating when this invoice was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
Note: This value does not change when the following attributes are changed: next_retry_at, dunning_status, has_advance_charges
sub_total
in cents, min=0
The sum of all the line item amounts minus the sum of all line item discounts. In other words, this is the sum of all line_items[].amount - the sum of all line_item_discounts[].discount_amount.
sub_total_in_local_currency
optional, in cents, min=0
Invoice subtotal in the currency of the place of supply.
total_in_local_currency
optional, in cents, min=0
Total invoice amount in the currency of the place of supply.
local_currency_code
optional, string, max chars=3
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.
tax
in cents, min=0
Total tax amount for this invoice
first_invoice
optional, boolean
Boolean indicating the first invoice raised for the subscription. In the case of a non-recurring invoice, it indicates the first invoice raised for the customer.
new_sales_amount
optional, in cents, min=0
The share of the invoice total due to new sales. When first_invoice is true, this attribute is the same as total. However, when the invoice is a consolidated one, then it is the sum of all line_items.amount belonging to a new.
has_advance_charges
optional, boolean
Boolean indicating any advance charge is present in this invoice.
term_finalized
boolean, default=true
Boolean indicating this invoice line_items terms are finalized or not.
is_gifted
boolean, default=false
Boolean indicating this invoice is gifted or not.
generated_at
optional, timestamp(UTC) in seconds
The date when the invoice is finalized. This is the date in the invoice lifecycle when its status becomes any one of the following for the first time: payment_due, posted, or paid. For an invoice with status as pending, this happens when it gets closed.
expected_payment_date
optional, timestamp(UTC) in seconds
Expected payment date recorded for this invoice.
amount_to_collect
optional, in cents, min=0
Payments that are yet to be collected for the invoice. This is the same value as amount_due - the sum of linked_payments[].txn_amount for all linked_payments[] that have txn_status as in_progress.
round_off_amount
optional, in cents, min=0
Indicates the rounded-off amount. For example, if your invoice amount is $99.99, and the amount is rounded off to $100.00, in this case, $100.00 is your invoice amount, $0.01 is the round_off_amount. If there is no round-off amount, it will display 0.
payment_owner
optional, string, max chars=50
Payment owner of an invoice
void_reason_code
optional, string, max chars=100
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive
deleted
boolean
Indicates that this resource has been deleted.
vat_number_prefix
optional, string, max chars=10
An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.
channel
optional, enumerated string
The subscription channel this object originated from and is maintained in.
Possible values are
webThe object was created (and is maintained) for the web channel directly in Chargebee via API or UI.app_storeThe object data is synchronized with data from in-app subscription(s) created in Apple App Store. Direct manipulation of this object via UI or API is disallowed.play_storeThe object data is synchronized with data from in-app subscription(s) created in Google Play Store. Direct manipulation of this object via UI or API is disallowed.

In-App Subscriptions is currently in early access. Contact eap@chargebee.com for more information.
.
business_entity_id
string, max chars=50
The unique ID of the business entity of this invoice. Depending on whether the invoice was created directly for a customer or for a subscription, this is the business entity of the customer or the subscription respectively.
line_items
Show attributes[+]
optional, list of line_item
The list of line items for this invoice
Line item attributes
id
optional, string, max chars=40
Uniquely identifies a line_item
subscription_id
optional, string, max chars=50
A unique identifier for the subscription this line item belongs to.
date_from
timestamp(UTC) in seconds
Start date of this line item.
date_to
timestamp(UTC) in seconds
End date of this line item.
unit_amount
in cents
Unit amount of the line item.
quantity
optional, integer, default=1

Quantity of the recurring item represented by this line item. 

For metered line items, this value is updated from usages when:

  • the invoice is generated as pending 

  • the invoice is closed

  • the sync usages API is called


amount
optional, in cents
Total amount of this line item. Typically equals to unit amount x quantity
pricing_model
optional, enumerated string
The pricing scheme for this item price.
Possible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
is_taxed
boolean, default=false
Specifies whether this line item is taxed or not
tax_amount
optional, in cents, default=0, min=0
The tax amount charged for this item
tax_rate
optional, double, min=0.0, max=100.0
Rate of tax used to calculate tax for this lineitem
unit_amount_in_decimal
optional, string, max chars=33
The decimal representation of the unit amount of the line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
quantity_in_decimal
optional, string, max chars=33
The decimal representation of the quantity of this line_item. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
amount_in_decimal
optional, string, max chars=33
The decimal representation of the amount for the line_item, in major units of the currency. Typically equals to unit_amount_in_decimal x quantity_in_decimal. Returned when multi-decimal pricing is enabled.
discount_amount
optional, in cents, min=0
Total discounts for this line
item_level_discount_amount
optional, in cents, min=0
Line Item-level discounts for this line.
reference_line_item_id
optional, string, max chars=40
Invoice Reference Line Item ID
description
string, max chars=250
Detailed description about this line item.
entity_description
string, max chars=500
Detailed description about this item.
entity_type
enumerated string
Specifies the modelled entity this line item is based on.
Possible values are
adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this caseplan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
tax_exempt_reason
optional, enumerated string
The reason due to which the line item price/amount is exempted from tax.
Possible values are
tax_not_configuredIf tax is not enabled for the siteregion_non_taxableIf the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdictionexportYou are not registered for tax in the customer’s region. This is also the reason code when both billing_address and shipping_address have not been provided for the customer and subscription respectivelycustomer_exemptIf the Customer is marked as Tax exemptproduct_exemptIf the Plan or Addon is marked as Tax exemptzero_ratedIf the rate of tax is 0% and no Sales/ GST tax is collectable for that line itemreverse_chargeIf the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU onlyhigh_value_physical_goodsIf physical goods are sold from outside Australia to customers in Australia, and the price of all the physical good line items is greater than AUD 1000, then tax will not be applied
entity_id
optional, string, max chars=100
The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type
customer_id
optional, string, max chars=100
A unique identifier for the customer this line item belongs to
discounts
Show attributes[+]
optional, list of discount
The list of all deductions applied to the invoice.
Discount attributes
amount
in cents, min=0
The amount deducted. The format of this value depends on the kind of currency.
description
optional, string, max chars=250
Description for this deduction.
line_item_id
optional, string, max chars=40
The unique id of the line item that this deduction is for. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.
entity_type
enumerated string
The type of deduction and the amount to which it is applied.
Possible values are
item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. prorated_creditsThe deduction is due to a legacy adjustment credit applied to the invoice. The entity_id is null in this case. The legacy credits feature is superseded by adjustment_credit_notes.item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id. document_level_discountThe deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.
discount_type
optional, enumerated string
The type of discount that is applied to the line item. Relevant only when discounts[entity_type] is one of item_level_discount , item_level_coupon, document_level_discount, or document_level_coupon
Possible values are
fixed_amountwhen amount is applied as discountpercentagewhen percentage is applied as discount
entity_id
optional, string, max chars=100
When the deduction is due to a coupon or a discount, then this is the id of the coupon or discount.
coupon_set_code
optional, string, max chars=50
The coupon code, if applicable, used to provide the discount. The coupon.id is available in entity_id.
line_item_discounts
Show attributes[+]
optional, list of line_item_discount
The list of deduction(s) applied for each line item of this invoice
Line item discount attributes
line_item_id
string, max chars=50
The unique id of the line item that this deduction is for.
discount_type
enumerated string
The type of deduction and the amount to which it is applied.
Possible values are
item_level_couponThe deduction is due to a coupon applied to a line item of the invoice. The coupon id is available as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is available as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. The entity_id is null in this case.prorated_creditsThe deduction is due to a legacy adjustment credit applied to the invoice. The entity_id is null in this case. The legacy credits feature is superseded by adjustment_credit_notes.item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id. document_level_discountThe deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.
entity_id
optional, string, max chars=50
When the deduction is due to a coupon or a discount, then this is the id of the coupon or discount.
discount_amount
in cents, min=0
The amount deducted. The format of this value depends on the kind of currency.
optional, list of tax
The list of taxes applied for this invoice
Tax attributes
name
string, max chars=100
The name of the tax applied. E.g. GST.
amount
in cents, min=0
The tax amount.
description
optional, string, max chars=250
Description of the tax item.
line_item_taxes
Show attributes[+]
optional, list of line_item_tax
The list of taxes applied on line items
Line item tax attributes
line_item_id
optional, string, max chars=40
The unique reference id of the line item for which the tax is applicable
tax_name
string, max chars=100
The name of the tax applied
tax_rate
double, default=0.0, min=0.0, max=100.0
The rate of tax used to calculate tax amount
is_partial_tax_applied
optional, boolean
Indicates if tax is applied only on a portion of the line item amount.
is_non_compliance_tax
optional, boolean
Indicates the non-compliance tax that should not be reported to the jurisdiction.
taxable_amount
in cents, min=0
Indicates the actual portion of the line item amount that is taxable.
tax_amount
in cents, min=0
The tax amount
tax_juris_type
optional, enumerated string
The type of tax jurisdiction
Possible values are
countryThe tax jurisdiction is a countryfederalThe tax jurisdiction is a federalstateThe tax jurisdiction is a statecountyThe tax jurisdiction is a countycityThe tax jurisdiction is a cityspecialSpecial tax jurisdiction.unincorporatedCombined tax of state and county.otherJurisdictions other than the ones listed above.
tax_juris_name
optional, string, max chars=250
The name of the tax jurisdiction
tax_juris_code
optional, string, max chars=250
The tax jurisdiction code
tax_amount_in_local_currency
optional, in cents, min=0
Total tax amount in the currency of the place of supply. This is applicable only for Invoice and Credit Notes API.
local_currency_code
optional, string, max chars=3
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.
line_item_tiers
Show attributes[+]
optional, list of line_item_tier
The list of tiers applicable for this line item
Line item tier attributes
line_item_id
optional, string, max chars=40
Uniquely identifies a line_item
starting_unit
integer, min=0
The lower limit of a range of units for the tier
ending_unit
optional, integer
The upper limit of a range of units for the tier
quantity_used
integer, min=0
The number of units purchased in a range.
unit_amount
in cents, min=0
The price of the tier if the charge model is a stairtstep pricing , or the price of each unit in the tier if the charge model is tiered/volume pricing.
starting_unit_in_decimal
optional, string, max chars=33
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the line_items.pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
ending_unit_in_decimal
optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the line_items.pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
quantity_used_in_decimal
optional, string, max chars=33
The decimal representation of the quantity purchased from this tier. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
unit_amount_in_decimal
optional, string, max chars=40
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
linked_payments
Show attributes[+]
optional, list of invoice_transaction
The list of transactions for this invoice
Linked payment attributes
txn_id
string, max chars=40
Uniquely identifies the transaction.
applied_amount
in cents, min=0
The transaction amount applied to this invoice
applied_at
timestamp(UTC) in seconds
Timestamp at which the transaction is applied.
txn_status
optional, enumerated string
The status of this transaction.
Possible values are
in_progressTransaction is being processed by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failuretimeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually
txn_date
optional, timestamp(UTC) in seconds
Indicates when this transaction occurred.
txn_amount
optional, in cents, min=1
Total amount of the transaction
dunning_attempts
Show attributes[+]
optional, list of dunning_attempt
The list of dunning_attempts for this invoice
Dunning attempt attributes
attempt
integer
Dunning attempt number.
transaction_id
optional, string, max chars=40
Transaction associated with attempt.
dunning_type
enumerated string, default=auto_collect
Types of dunning
Possible values are
auto_collectDunning type is auto collection.offlineDunning type is offline.direct_debitDunning type is direct debit.
created_at
optional, timestamp(UTC) in seconds
Timestamp at which the attempt was made.
txn_status
optional, enumerated string
The status of this transaction.
Possible values are
in_progressTransaction is being processed by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failuretimeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually
txn_amount
optional, in cents, min=1
Total amount of the transaction
applied_credits
Show attributes[+]
optional, list of applied_credit
Refundable Credits applied on this invoice.
Applied credit attributes
cn_id
string, max chars=50
Credit applied on the credit note ID.
applied_amount
in cents, min=0
Total credit amount applied to this invoice.
applied_at
timestamp(UTC) in seconds
Timestamp when the credit amount was applied to this invoice.
cn_reason_code
optional, enumerated string
Credit note reason code. Deprecated; use the cn_create_reason_code parameter instead
Possible values are
write_offThis reason will be set automatically for the Credit Notes created during invoice Write Off operation.subscription_changeThis reason will be set automatically for Credit Notes created during Change Subscription operation when proration is enabledsubscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operationsubscription_pauseThis reason will be automatically set to credit notes created during pause/resume subscription operation.
chargebackCan be set when you are recording your customer Chargebacksproduct_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder CancellationwaiverWaiverotherCan be set when none of the above reason codes are applicablefraudulentFRAUDULENT
Show all values[+]
cn_create_reason_code
optional, string, max chars=100
Credit note reason code
cn_date
optional, timestamp(UTC) in seconds
Indicates the date at which this credit note is created
cn_status
enumerated string
Credit note status.
Possible values are
adjustedWhen the Credit Note has been adjusted against an invoice.refundedWhen the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded).refund_dueWhen the credits are yet to be used, or have been partially used.voidedWhen the Credit Note has been cancelled.
adjustment_credit_notes
Show attributes[+]
optional, list of created_credit_note
Adjustments created for this invoice
Adjustment credit note attributes
cn_id
string, max chars=50
Credit-note id
cn_reason_code
optional, enumerated string
Credit note reason code. Deprecated; use the cn_create_reason_code parameter instead
Possible values are
write_offThis reason will be set automatically for the Credit Notes created during invoice Write Off operation.subscription_changeThis reason will be set automatically for Credit Notes created during Change Subscription operation when proration is enabledsubscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operationsubscription_pauseThis reason will be automatically set to credit notes created during pause/resume subscription operation.
chargebackCan be set when you are recording your customer Chargebacksproduct_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder CancellationwaiverWaiverotherCan be set when none of the above reason codes are applicablefraudulentFRAUDULENT
Show all values[+]
cn_create_reason_code
optional, string, max chars=100
Credit note reason code
cn_date
optional, timestamp(UTC) in seconds
Indicates the date at which this credit note is created
cn_total
optional, in cents, default=0, min=0
Total amount of the credit note.
cn_status
enumerated string
Credit note status.
Possible values are
adjustedWhen the Credit Note has been adjusted against an invoice.refundedWhen the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded).refund_dueWhen the credits are yet to be used, or have been partially used.voidedWhen the Credit Note has been cancelled.
issued_credit_notes
Show attributes[+]
optional, list of created_credit_note
Credit notes issued for this invoice
Issued credit note attributes
cn_id
string, max chars=50
Credit-note id
cn_reason_code
optional, enumerated string
Credit note reason code. Deprecated; use the cn_create_reason_code parameter instead
Possible values are
write_offThis reason will be set automatically for the Credit Notes created during invoice Write Off operation.subscription_changeThis reason will be set automatically for Credit Notes created during Change Subscription operation when proration is enabledsubscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operationsubscription_pauseThis reason will be automatically set to credit notes created during pause/resume subscription operation.
chargebackCan be set when you are recording your customer Chargebacksproduct_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder CancellationwaiverWaiverotherCan be set when none of the above reason codes are applicablefraudulentFRAUDULENT
Show all values[+]
cn_create_reason_code
optional, string, max chars=100
Credit note reason code
cn_date
optional, timestamp(UTC) in seconds
Indicates the date at which this credit note is created
cn_total
optional, in cents, default=0, min=0
Total amount of the credit note.
cn_status
enumerated string
Credit note status.
Possible values are
adjustedWhen the Credit Note has been adjusted against an invoice.refundedWhen the entire credits (Credit Note amount) have been used (i.e either allocated to invoices or refunded).refund_dueWhen the credits are yet to be used, or have been partially used.voidedWhen the Credit Note has been cancelled.
linked_orders
Show attributes[+]
optional, list of linked_order
The list of orders for this invoice
Linked order attributes
id
string, max chars=40
Uniquely identifies the order. It is the api identifier for the order
document_number
optional, string, max chars=50
The order's serial number
status
optional, enumerated string, default=new
The status of this order.
Possible values are
newOrder has been created. Applicable only if you are using Chargebee's legacy order management system.processingOrder is being processed. Applicable only if you are using Chargebee's legacy order management systemcompleteOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management systemcancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management system
voidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management systemqueuedOrder is yet to be processed by any system, these are scheduled orders created by Chargebeeawaiting_shipmentThe order has been picked up by an integration system, and synced to a shipping management platformon_holdThe order is paused from being processed.deliveredThe order has been delivered to the customer.shippedThe order has moved from order management system to a shipping system.partially_deliveredThe order has been partially delivered to the customer.returnedThe order has been returned after delivery.
Show all values[+]
order_type
optional, enumerated string
Order type
Possible values are
manualThe order has been created by the the user using Chargebee's legacy order management system.system_generatedThe order has been created by Chargebee automatically based on the preferences set by the user.
reference_id
optional, string, max chars=50
Reference id can be used to map the orders in the shipping/order management application to the orders in ChargeBee. The reference_id generally is same as the order id in the third party application.
fulfillment_status
optional, string, max chars=50
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;
batch_id
optional, string, max chars=50
Unique id to identify a group of orders.
created_at
timestamp(UTC) in seconds
The time at which the order was created
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:
Note attributes
entity_type
enumerated string
Type of entity to which the note belongs.
Possible values are
couponEntity that represents a coupon.subscriptionEntity that represents a subscription of customer.customerEntity that represents a customer.plan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
note
string, max chars=2000
Actual note.
entity_id
optional, string, max chars=100
Unique identifier of the entity.
shipping_address
Show attributes[+]
optional, shipping_address
Shipping address for the invoice.
Shipping address attributes
first_name
optional, string, max chars=150
The first name of the contact.
last_name
optional, string, max chars=150
The last name of the contact.
email
optional, string, max chars=70
The email address.
company
optional, string, max chars=250
The company name.
phone
optional, string, max chars=50
The phone number.
line1
optional, string, max chars=150
Address line 1
line2
optional, string, max chars=150
Address line 2
line3
optional, string, max chars=150
Address line 3
city
optional, string, max chars=50
The name of the city.
state_code
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
state
optional, string, max chars=50
The state/province name.
country
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.


zip
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
validation_status
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
index
integer, min=0, max=4
The index number of the subscription to which the item price is added. Provide a unique number between 0 and 4 (inclusive) for each subscription that is to be created.
billing_address
Show attributes[+]
optional, billing_address
Billing address for the invoice.
Billing address attributes
first_name
optional, string, max chars=150
The first name of the billing contact.
last_name
optional, string, max chars=150
The last name of the billing contact.
email
optional, string, max chars=70
The email address.
company
optional, string, max chars=250
The company name.
phone
optional, string, max chars=50
The phone number.
line1
optional, string, max chars=150
Address line 1
line2
optional, string, max chars=150
Address line 2
line3
optional, string, max chars=150
Address line 3
city
optional, string, max chars=50
The name of the city.
state_code
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
state
optional, string, max chars=50
State or Province
country
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.


zip
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
validation_status
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
optional, einvoice
An e-invoice or electronic invoice is a structured representation of an invoice that is interoperable between computerized invoicing systems. Depending on the country, e-invoicing can be necessary to meet financial/taxation authority regulations.
Einvoice attributes
id
string, max chars=50
The unique id for the e-invoice. This is auto-generated by Chargebee.
status
enumerated string
The status of processing the e-invoice. To obtain detailed information about the current status, see message.
Possible values are
scheduledSending the e-invoice to the customer has been scheduled.skippedThe e-invoice was not sent. This could be due to missing information or because the entity_identifier is not registered on the e-invoicing network.in_progressThe e-invoice has been sent and Chargebee is waiting for confirmation from the receiving entity.successThe e-invoice has been successfully delivered to the customer.failedThe e-invoice was sent and there was an error due to which it was not delivered.
message
optional, string, max chars=250
Detailed information about the status of the e-invoice. When status is skipped or failed, this contains the reason or error details. The following are some valid examples:
  • Invoice successfully sent to customer via the e-invoicing network 9090:123456
  • Invoice successfully sent to customer via email id abc@acme.com

linked_taxes_withheld
Show attributes[+]
optional, list of linked_tax_withheld
Details of tax_withheld against this invoice.
Linked taxes withheld attributes
id
string, max chars=40
An auto-generated unique identifier for the tax withheld. The value starts with the prefix tax_wh_. For example, tax_wh_16BdDXSlbu4uV1Ee6.
amount
optional, in cents, min=1
The amount withheld by the customer as tax from the invoice. The unit depends on the type of currency.
description
optional, string, max chars=65k
The description for this tax withheld.
date
optional, timestamp(UTC) in seconds
Date or time associated with the tax withheld.
reference_number
optional, string, max chars=100
A unique external reference number for the tax withheld. Typically, this is the reference number used by the system you are integrating the API with. Depending on your integration, this could be the reference number issued by the taxation authority to identify the customer or the specific tax transaction.

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

Notes

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

Sample Request
# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges \
     -u {site_api_key}:\
     -d customer_id="__test__KyVkkWS1xLskm8" \
     -d item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 \
     -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"
copy
# 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 item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 \
     -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"

Sample Response [ JSON ]

Show more...
{"invoice": { "adjustment_credit_notes": [], "amount_adjusted": 0, "amount_due": 0, "amount_paid": 2000, "amount_to_collect": 0, "applied_credits": [], "base_currency_code": "USD", "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address", "validation_status": "not_validated" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__KyVkkWS1xLskm8", "date": 1517463749, "deleted": false, "due_date": 1517463749, "dunning_attempts": [], "exchange_rate": 1, "first_invoice": true, "has_advance_charges": false, "id": "__demo_inv__1", "is_gifted": false, "issued_credit_notes": [], "line_items": [ { "amount": 2000, "customer_id": "__test__KyVkkWS1xLskm8", "date_from": 1517463749, "date_to": 1517463749, "description": "SSL Charge USD Monthly", "discount_amount": 0, "entity_id": "ssl-charge-USD", "entity_type": "charge_item_price", "id": "li___test__KyVkkWS1xLt9LF", "is_taxed": false, "item_level_discount_amount": 0, "object": "line_item", "pricing_model": "flat_fee", "quantity": 1, "tax_amount": 0, "tax_exempt_reason": "tax_not_configured", "unit_amount": 2000 }, {..} ], "linked_orders": [], "linked_payments": [ { "applied_amount": 2000, "applied_at": 1517463750, "txn_amount": 2000, "txn_date": 1517463750, "txn_id": "txn___test__KyVkkWS1xLtFiG", "txn_status": "success" }, {..} ], "net_term_days": 0, "new_sales_amount": 2000, "object": "invoice", "paid_at": 1517463750, "price_type": "tax_exclusive", "recurring": false, "resource_version": 1517463750000, "round_off_amount": 0, "shipping_address": { "city": "Walnut", "country": "US", "first_name": "John", "last_name": "Mathew", "object": "shipping_address", "state": "California", "state_code": "CA", "validation_status": "not_validated", "zip": "91789" }, "status": "paid", "sub_total": 2000, "tax": 0, "term_finalized": true, "total": 2000, "updated_at": 1517463750, "write_off_amount": 0 }}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges
customer_id
optional, string, max chars=50

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

Note

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

.
subscription_id
optional, string, max chars=50

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

Note

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

.
currency_code
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) of the invoice amount.
invoice_note
optional, string, max chars=2000
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
remove_general_note
optional, boolean, default=false
Set as true to remove the general note from this invoice.
po_number
optional, string, max chars=100
Purchase Order Number for this invoice.
coupon_ids[0..n]
optional, list of string
List of Coupons to be added.
authorization_transaction_id
optional, string, max chars=40
Authorization transaction to be captured.
payment_source_id
optional, string, max chars=40
Payment source to be used for this payment.
auto_collection
optional, enumerated string
The customer level auto collection will be override if specified.
Possible values are
onWhenever an invoice is created, an automatic attempt will be made to charge.offWhenever an invoice is created as payment due.
invoice_date
optional, timestamp(UTC) in seconds
The document date displayed on the invoice PDF. By default, it is the date of creation of the invoice or, when Metered Billing is enabled, it can be the date of closing the invoice. Provide this value to backdate the invoice (set the invoice date to a value in the past). Backdating an invoice is done for reasons such as booking revenue for a previous date or when the non-recurring charge is effective as of a past date. taxes and line_item_taxes are computed based on the tax configuration as of this date. The date should not be more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
token_id
optional, string, max chars=40
Token generated by Chargebee JS representing payment method details.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
retain_payment_source
optional, boolean, default=true
Indicates whether the payment source should be retained for the customer.
+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
optional, string, max chars=150
The first name of the contact.
shipping_address[last_name]
optional, string, max chars=150
The last name of the contact.
shipping_address[email]
optional, string, max chars=70
The email address.
shipping_address[company]
optional, string, max chars=250
The company name.
shipping_address[phone]
optional, string, max chars=50
The phone number.
shipping_address[line1]
optional, string, max chars=150
Address line 1
shipping_address[line2]
optional, string, max chars=150
Address line 2
shipping_address[line3]
optional, string, max chars=150
Address line 3
shipping_address[city]
optional, string, max chars=50
The name of the city.
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

shipping_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
+
card
Parameters for card
pass parameters as card[<param name>]
card[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
card[first_name]
optional, string, max chars=50
Cardholder's first name
card[last_name]
optional, string, max chars=50
Cardholder's last name
card[number]
required if card provided, string, max chars=1500
The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
card[expiry_month]
required if card provided, integer, min=1, max=12
Card expiry month.
card[expiry_year]
required if card provided, integer
Card expiry year.
card[cvv]
optional, string, max chars=520
The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
card[billing_addr1]
optional, string, max chars=150
Address line 1, as available in card billing address.
card[billing_addr2]
optional, string, max chars=150
Address line 2, as available in card billing address.
card[billing_city]
optional, string, max chars=50
City, as available in card billing address.
card[billing_state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
card[billing_state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
card[billing_zip]
optional, string, max chars=20
Postal or Zip code, as available in card billing address.
card[billing_country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

card[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
+
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
bank_account[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
bank_account[iban]
optional, string, min chars=10, max chars=50
Account holder’s International Bank Account Number. For the GoCardless platform, this can be the local bank details
bank_account[first_name]
optional, string, max chars=150
Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
bank_account[last_name]
optional, string, max chars=150
Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
bank_account[company]
optional, string, max chars=250
Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
bank_account[email]
optional, string, max chars=70
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
bank_account[phone]
optional, string, max chars=50
Phone number of the account holder that is linked to the bank account.
bank_account[bank_name]
optional, string, max chars=100
Name of account holder’s bank.
bank_account[account_number]
optional, string, min chars=4, max chars=17
Account holder’s bank account number.
bank_account[routing_number]
optional, string, min chars=3, max chars=9
Bank account routing number.
bank_account[bank_code]
optional, string, max chars=20
Indicates the bank code.
bank_account[account_type]
optional, enumerated string
Represents the account type used to create a payment source. Available for Authorize.net ACH and Razorpay NetBanking users only. If not passed, account type is taken as null.
Possible values are
checkingChecking AccountsavingsSavings Accountbusiness_checkingBusiness Checking AccountcurrentCurrent Account
bank_account[account_holder_type]
optional, enumerated string
For Stripe ACH users only. Indicates the account holder type.
Possible values are
individualIndividual Account.companyCompany Account.
bank_account[echeck_type]
optional, enumerated string
For Authorize.net ACH users only. Indicates the type of eCheck.
Possible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
bank_account[issuing_country]
optional, string, max chars=50
two-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
bank_account[swedish_identity_number]
optional, string, min chars=10, max chars=12
For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
bank_account[billing_address]
optional, jsonobject
The billing address associated with the bank account. The value is a JSON object with the following keys and their values:
  • first_name:(string, max chars=150) The first name of the contact.
  • last_name:(string, max chars=150) The last name of the contact.
  • company_name:(string, max chars=250) The company name for the address.
  • line1:(string, max chars=180) The first line of the address.
  • line2:(string, max chars=180) The second line of the address.
  • country:(string) The name of the country for the address.
  • country_code:(string, max chars=50) The two-letter, ISO 3166 alpha-2 country code for the address.
  • state:(string, max chars=50) The name of the state or province for the address. When not provided, this is set automatically for US, Canada, and India.
  • state_code:(string, max chars=50) The ISO 3166-2 state/province code without the country prefix. This is supported for USA, Canada, and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
  • city:(string, max chars=50) The city name for the address.
  • postal_code:(string, max chars=20) The postal or ZIP code for the address.
  • phone:(string, max chars=50) The contact phone number for the address.
  • email:(string, max chars=70) The contact email address for the address.
+
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_method[type]
optional, enumerated string
The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
Possible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.
genericPayments made via Generic Payment Method.alipayPayments made via Alipay.unionpayPayments made via UnionPay.apple_payPayments made via Apple Pay.wechat_payPayments made via WeChat Pay.idealPayments made via iDEAL.google_payPayments made via Google Pay.sofortPayments made via Sofort.bancontactPayments made via Bancontact Card.giropayPayments made via giropay.dotpayPayments made via Dotpay.upiUPI Payments.netbanking_emandatesNetbanking (eMandates) Payments.
Show all values[+]
payment_method[gateway_account_id]
optional, string, max chars=50
The gateway account in which this payment source is stored.
payment_method[reference_id]
optional, string, max chars=200
The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
payment_method[tmp_token]
required if reference_id not provided, string, max chars=65k
Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
payment_method[issuing_country]
optional, string, max chars=50
ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

If you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.
payment_method[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
+
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
payment_intent[id]
optional, string, max chars=150
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
payment_intent[gateway_account_id]
required if payment intent token provided, string, max chars=50
The gateway account used for performing the 3DS flow.
payment_intent[gw_token]
optional, string, max chars=65k
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
payment_intent[payment_method_type]
optional, enumerated string
The list of payment method types (For example, card, ideal, sofort, bancontact, etc.) this Payment Intent is allowed to use. If payment method type is empty, Card is taken as the default type for all gateways except Razorpay.
Possible values are
cardcardidealidealsofortsofortbancontactbancontact
google_paygoogle_paydotpaydotpaygiropaygiropayapple_payapple_payupiupinetbanking_emandatesnetbanking_emandatespaypal_express_checkoutpaypal_express_checkoutdirect_debitdirect_debit
Show all values[+]
payment_intent[reference_id]
optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
payment_intent[additional_information]
optional, jsonobject
  • checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
    • payer: User related information.
      • country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
      • document: Document ID is the user’s identification number based on their country.
  • bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
  • braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • device_session_id: Session ID associated with the user's device.
      • fraud_merchant_id: Your merchant ID for fraud detection.
  • chargebee_payments: While passing raw card details to Chargebee Payments, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
    • fraud: Fraud identification related information.
      • fraud_session_id: Your Chargebee Payments fraud session ID required to perform anti-fraud validation.
+
item_prices
Parameters for item_prices. Multiple item_prices can be passed by specifying unique indices.
pass parameters as item_prices[<param name>][<idx:0..n>]
item_prices[item_price_id][0..n]
optional, string, max chars=100
A unique ID for your system to identify the item price.
item_prices[quantity][0..n]
optional, integer, min=1
Item price quantity
item_prices[quantity_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
item_prices[unit_price][0..n]
optional, in cents, min=0
The price or per-unit-price of the item price. By default, it is the value set for the item_price. This is only applicable when the pricing_model of the item_price is flat_fee or per_unit. The value depends on the type of currency.
item_prices[unit_price_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
item_prices[date_from][0..n]
optional, timestamp(UTC) in seconds
The time when the service period for the item starts.
item_prices[date_to][0..n]
optional, timestamp(UTC) in seconds
The time when the service period for the item ends.
+
item_tiers
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[item_price_id][0..n]
optional, string, max chars=100
The id of the item price to which this tier belongs.
item_tiers[starting_unit][0..n]
optional, integer, min=1
The lowest value in the quantity tier.
item_tiers[ending_unit][0..n]
optional, integer
The highest value in the quantity tier.
item_tiers[price][0..n]
optional, in cents, default=0, min=0
The per-unit price for the tier when the pricing_model is tiered or volume. The total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
item_tiers[price_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
+
charges
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
charges[amount][0..n]
optional, in cents, min=1
The amount to be charged. The unit depends on the type of currency.
charges[amount_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the amount for the one-time charge. Provide the value in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
charges[description][0..n]
optional, string, max chars=250
Description for this charge
charges[taxable][0..n]
optional, boolean, default=true
The amount to be charged is taxable or not.
charges[tax_profile_id][0..n]
optional, string, max chars=50
Tax profile of the charge.
charges[avalara_tax_code][0..n]
optional, string, max chars=50
The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration.
charges[hsn_code][0..n]
optional, string, max chars=50
The HSN code to which the item is mapped for calculating the customer’s tax in India. Applicable only when both of the following conditions are true:
charges[taxjar_product_code][0..n]
optional, string, max chars=50
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
charges[avalara_sale_type][0..n]
optional, enumerated string
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
charges[avalara_transaction_type][0..n]
optional, integer
Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
charges[avalara_service_type][0..n]
optional, integer
Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
charges[date_from][0..n]
optional, timestamp(UTC) in seconds
The time when the service period for the charge starts.
charges[date_to][0..n]
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
charges[discount_amount][0..n]
optional, in cents, min=0
The value of the discount. The format of this value depends on the kind of currency. Either this parameter or charges[discount_percentage] should be passed.
charges[discount_percentage][0..n]
optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it. Either this parameter or charges[discount_amount] should be passed.
+
notes_to_remove
Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]
notes_to_remove[entity_type][0..n]
optional, enumerated string
Type of entity to which the note belongs. To remove the general note, use the remove_general_note parameter.
Possible values are
customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
notes_to_remove[entity_id][0..n]
optional, string, max chars=100
Unique identifier of the note.
+
discounts
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
discounts[percentage][0..n]
optional, double, min=0.01, max=100.0
The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.
discounts[amount][0..n]
optional, in cents, min=0
The value of the discount. The format of this value depends on the kind of currency. This is only applicable when discount.type is fixed_amount.
discounts[apply_on][0..n]
required, enumerated string
The amount on the invoice to which the discount is applied.
Possible values are
invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.
discounts[item_price_id][0..n]
optional, string, max chars=100
The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.
always returned
Resource object representing 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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/stop_dunning \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/stop_dunning \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

Use this endpoint to import invoices that are created outside of Chargebee; for example, import invoices created with a commercial accounting software to Chargebee. This allows you to conveniently manage invoices in one place.

This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}:\
     -d id="old_inv_001" \
     -d customer_id="__test__8asyKSOcTJGo2N" \
     -d subscription_id="__test__8asyKSOcTJMw2U" \
     -d date=1517490271 \
     -d total=4900 \
     -d status="payment_due" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d line_items[date_from][1]=1517490271 \
     -d line_items[date_to][1]=1519909471 \
     -d line_items[description][1]="Standard" \
     -d line_items[unit_amount][1]=4900 \
     -d line_items[quantity][1]=1 \
     -d line_items[entity_type][1]="plan_item_price" \
     -d line_items[entity_id][1]="standard-USD"
copy
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"

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/import_invoice
id
required, string, max chars=50
Invoice Number.
currency_code
required if Multicurrency is enabled, string, max chars=3
The currency code (ISO 4217 format) for the invoice.
customer_id
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created.
subscription_id
optional, string, max chars=50
If recurring items are present in line items then subscription id is required.
po_number
optional, string, max chars=100
Purchase Order Number for this invoice.
price_type
optional, enumerated string, default=tax_exclusive
The price type of the invoice.
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
tax_override_reason
optional, enumerated string
The reason for exempting the invoice from tax. (Applicable only for exempted invoices.).
Possible values are
id_exemptThe customer is from a different country than your business and they have a valid VAT number or, the customer is a business entity. (This reason is only applicable when EU VAT or UK VAT is enabled.)customer_exemptThe customer is exempted from tax.exportThe customer is from a non-taxable region or the billing address and shipping address are unavailable.
vat_number
optional, string, max chars=20
Vat Number. Required if this invoice is VAT exempted.
vat_number_prefix
optional, string, max chars=10
An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.
date
required, timestamp(UTC) in seconds
Date when invoice raised.
total
required, in cents, min=0
Invoice total amount.
round_off
optional, in cents, min=-99, max=99
Round off amount.
status
optional, enumerated string, default=payment_due
Current status of this invoice.
Possible values are
paidIndicates a paid invoice.postedIndicates the payment is not yet collected and will be in this state till the due date to indicate the due periodpayment_dueIndicates the payment is not yet collected and is being retried as per retry settings.pending
The invoice is yet to be closed (sent for payment collection). An invoice is generated with this status when it has line items that belong to items that are metered or when the subscription.create_pending_invoicesattribute is set to true.
The invoice is yet to be closed (sent for payment collection). All invoices are generated with this status when Metered Billing is enabled for the site.
due_date
optional, timestamp(UTC) in seconds
Invoice Due Date.
net_term_days
optional, integer, default=0
Invoice net term days.
use_for_proration
optional, boolean, default=false
If the invoice falls within the subscription current term will be used for proration.
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
optional, string, max chars=150
The first name of the billing contact.
billing_address[last_name]
optional, string, max chars=150
The last name of the billing contact.
billing_address[email]
optional, string, max chars=70
The email address.
billing_address[company]
optional, string, max chars=250
The company name.
billing_address[phone]
optional, string, max chars=50
The phone number.
billing_address[line1]
optional, string, max chars=150
Address line 1
billing_address[line2]
optional, string, max chars=150
Address line 2
billing_address[line3]
optional, string, max chars=150
Address line 3
billing_address[city]
optional, string, max chars=50
The name of the city.
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

billing_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
optional, string, max chars=150
The first name of the contact.
shipping_address[last_name]
optional, string, max chars=150
The last name of the contact.
shipping_address[email]
optional, string, max chars=70
The email address.
shipping_address[company]
optional, string, max chars=250
The company name.
shipping_address[phone]
optional, string, max chars=50
The phone number.
shipping_address[line1]
optional, string, max chars=150
Address line 1
shipping_address[line2]
optional, string, max chars=150
Address line 2
shipping_address[line3]
optional, string, max chars=150
Address line 3
shipping_address[city]
optional, string, max chars=50
The name of the city.
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

shipping_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
+
line_items
Parameters for line_items. Multiple line_items can be passed by specifying unique indices.
pass parameters as line_items[<param name>][<idx:0..n>]
line_items[id][0..n]
optional, string, max chars=40
Uniquely identifies a line_item
line_items[date_from][0..n]
optional, timestamp(UTC) in seconds
Start date of this line item.
line_items[date_to][0..n]
optional, timestamp(UTC) in seconds
End date of this line item.
line_items[description][0..n]
required, string, max chars=250
Description for this line item
line_items[unit_amount][0..n]
optional, in cents
Unit amount of the line item.
line_items[quantity][0..n]
optional, integer, default=1
Quantity of the recurring item which is represented by this line item. For metered line items, this value is updated from usages once when the invoice is generated as pending and finally when the invoice is closed.
Quantity of the recurring item which is represented by this line item.
line_items[amount][0..n]
optional, in cents
Total amount of this lineitem. Not required if the line_items[unit_amount] param is passed
line_items[unit_amount_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the unit amount of the line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
line_items[quantity_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the quantity of this line_item. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
line_items[amount_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the amount for the line_item, in major units of the currency. Typically equals to unit_amount_in_decimal x quantity_in_decimal. Returned when multi-decimal pricing is enabled.
line_items[entity_type][0..n]
optional, enumerated string, default=adhoc
Specifies the modelled entity this line item is based on.
Possible values are
adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this caseplan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
line_items[entity_id][0..n]
optional, string, max chars=100
The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type
line_items[item_level_discount1_entity_id][0..n]
optional, string, max chars=50
First item level discount entity id
line_items[item_level_discount1_amount][0..n]
optional, in cents, min=0
First item level discount amount
line_items[item_level_discount2_entity_id][0..n]
optional, string, max chars=50
Second item level discount entity id
line_items[item_level_discount2_amount][0..n]
optional, in cents, min=0
Second item level discount amount
line_items[tax1_name][0..n]
optional, string, max chars=50
First tax name
line_items[tax1_amount][0..n]
optional, in cents, min=0
First tax amount
line_items[tax2_name][0..n]
optional, string, max chars=50
Second tax name
line_items[tax2_amount][0..n]
optional, in cents, min=0
Second tax amount
line_items[tax3_name][0..n]
optional, string, max chars=50
Third tax name
line_items[tax3_amount][0..n]
optional, in cents, min=0
Third tax amount
line_items[tax4_name][0..n]
optional, string, max chars=50
Fourth tax name
line_items[tax4_amount][0..n]
optional, in cents, min=0
Fourth tax amount
line_items[tax5_name][0..n]
optional, string, max chars=50
Fifth tax name
line_items[tax5_amount][0..n]
optional, in cents, min=0
Fifth tax amount
line_items[tax6_name][0..n]
optional, string, max chars=50
Sixth tax name
line_items[tax6_amount][0..n]
optional, in cents, min=0
Sixth tax amount
line_items[tax7_name][0..n]
optional, string, max chars=50
Seventh tax name
line_items[tax7_amount][0..n]
optional, in cents, min=0
Seventh tax amount
line_items[tax8_name][0..n]
optional, string, max chars=50
Eighth tax name
line_items[tax8_amount][0..n]
optional, in cents, min=0
Eighth tax amount
line_items[tax9_name][0..n]
optional, string, max chars=50
Ninth tax name
line_items[tax9_amount][0..n]
optional, in cents, min=0
Ninth tax amount
line_items[tax10_name][0..n]
optional, string, max chars=50
Tenth tax name
line_items[tax10_amount][0..n]
optional, in cents, min=0
Tenth tax amount
+
line_item_tiers
Parameters for line_item_tiers. Multiple line_item_tiers can be passed by specifying unique indices.
pass parameters as line_item_tiers[<param name>][<idx:0..n>]
line_item_tiers[line_item_id][0..n]
required, string, max chars=40
Uniquely identifies a line_item
line_item_tiers[starting_unit][0..n]
optional, integer, min=0
The lower limit of a range of units for the tier
line_item_tiers[ending_unit][0..n]
optional, integer
The upper limit of a range of units for the tier
line_item_tiers[quantity_used][0..n]
optional, integer, min=0
The number of units purchased in a range.
line_item_tiers[unit_amount][0..n]
optional, in cents, min=0
The price of the tier if the charge model is a stairtstep pricing , or the price of each unit in the tier if the charge model is tiered/volume pricing.
line_item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the line_items.pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
line_item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the line_items.pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
line_item_tiers[quantity_used_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the quantity purchased from this tier. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
line_item_tiers[unit_amount_in_decimal][0..n]
optional, string, max chars=40
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
+
discounts
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
discounts[line_item_id][0..n]
optional, string, max chars=40
The unique id of the line item that this deduction is for. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.
discounts[entity_type][0..n]
required, enumerated string
The type of deduction and the amount to which it is applied.
Possible values are
item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. item_level_discountThe deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id. document_level_discountThe deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.
discounts[entity_id][0..n]
optional, string, max chars=100
When the deduction is due to a coupon, then this is the id of the coupon. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.
discounts[description][0..n]
optional, string, max chars=250
Description for this deduction.
discounts[amount][0..n]
required, in cents, min=0
The amount deducted. The format of this value depends on the kind of currency.
+
taxes
Parameters for taxes. Multiple taxes can be passed by specifying unique indices.
pass parameters as taxes[<param name>][<idx:0..n>]
taxes[name][0..n]
required, string, max chars=100
The name of the tax applied
taxes[rate][0..n]
required, double, default=0.0, min=0.0, max=100.0
The rate of tax used to calculate tax amount
taxes[amount][0..n]
optional, in cents, min=0
Total tax amount charged for this invoice
taxes[description][0..n]
optional, string, max chars=50
Description of tax
taxes[juris_type][0..n]
optional, enumerated string, default=other
The type of tax jurisdiction
Possible values are
countryThe tax jurisdiction is a countryfederalThe tax jurisdiction is a federalstateThe tax jurisdiction is a statecountyThe tax jurisdiction is a countycityThe tax jurisdiction is a cityspecialSpecial tax jurisdiction.unincorporatedCombined tax of state and county.otherJurisdictions other than the ones listed above.
taxes[juris_name][0..n]
optional, string, max chars=250
The name of the tax jurisdiction
taxes[juris_code][0..n]
optional, string, max chars=250
The tax jurisdiction code
+
payments
Parameters for payments. Multiple payments can be passed by specifying unique indices.
pass parameters as payments[<param name>][<idx:0..n>]
payments[amount][0..n]
required, in cents, min=1
Payment made for this invoice
payments[payment_method][0..n]
required, enumerated string
Mode of payment
Possible values are
cashCashcheckCheck
bank_transferBank TransferotherPayment Methods other than the above typesupiupinetbanking_emandatesnetbanking_emandates
Show all values[+]
payments[date][0..n]
optional, timestamp(UTC) in seconds
Payment date
payments[reference_number][0..n]
optional, string, min chars=1, max chars=100
Reference number for this payment
+
notes
Parameters for notes. Multiple notes can be passed by specifying unique indices.
pass parameters as notes[<param name>][<idx:0..n>]
notes[entity_type][0..n]
optional, enumerated string
Type of entity to which the note belongs.
Possible values are
couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
notes[entity_id][0..n]
optional, string, max chars=50
Id of the mentioned entity type
notes[note][0..n]
optional, string, max chars=2000
Actual note.
always returned
Resource object representing 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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_payments \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_payments \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/apply_payments
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
+
transactions
Parameters for transactions. Multiple transactions can be passed by specifying unique indices.
pass parameters as transactions[<param name>][<idx:0..n>]
transactions[id][0..n]
optional, string, max chars=40
Uniquely identifies the transaction. Excess payments available with the customer will be applied against this invoice if this parameter is not passed.
always returned
Resource object representing invoice

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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/draft_inv_AwSNuHT1ebuqgOu/sync_usages \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/draft_inv_AwSNuHT1ebuqgOu/sync_usages \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/sync_usages
always returned
Resource object representing 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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/apply_credits \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/apply_credits \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/apply_credits
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
+
credit_notes
Parameters for credit_notes. Multiple credit_notes can be passed by specifying unique indices.
pass parameters as credit_notes[<param name>][<idx:0..n>]
credit_notes[id][0..n]
optional, string, max chars=50
The Credit Note number acts as an identifier for Credit Notes and is typically generated sequentially. Available refundable credits with the customer will be applied against this invoice if this paramenter is not passed.
always returned
Resource object representing invoice

Lists all the Invoices.

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode status[in]="["paid","payment_due"]" \
     --data-urlencode sort_by[asc]="date"
copy
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"

Sample Response [ JSON ]

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

URL Format GET

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

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

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

Example subscription_id[is] = "3bdjnDnsdQn"
customer_id[<operator>]
optional, string filter
The identifier of the customer this invoice belongs to.
Supported operators : is, is_not, starts_with, in, not_in

Example customer_id[is] = "3bdjnDnsdQn"
recurring[<operator>]
optional, boolean filter
Boolean indicating whether this invoice belongs to a subscription. Possible values are : true, false
Supported operators : is

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

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

Example price_type[is] = "tax_exclusive"
date[<operator>]
optional, timestamp(UTC) in seconds filter
The document date displayed on the invoice PDF.
Supported operators : after, before, on, between

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

Example paid_at[before] = "1394532759"
total[<operator>]
optional, in cents filter
Invoiced amount displayed in cents; that is, a decimal point is not present between the whole number and the decimal part. For example, $499.99 is displayed as 49999, and so on.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example total[gt] = "1000"
amount_paid[<operator>]
optional, in cents filter
Payments collected successfully for the invoice. This is the sum of linked_payments[].txn_amount for all linked_payments[] that have txn_status as success.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example amount_paid[gt] = "800"
amount_adjusted[<operator>]
optional, in cents filter
Total adjustments made against this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example amount_adjusted[gte] = "100"
credits_applied[<operator>]
optional, in cents filter
Total credits applied against this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example credits_applied[is] = "100"
amount_due[<operator>]
optional, in cents filter
The unpaid amount that is due on the invoice. This is calculated as: total - amount_paid - sum of applied_credits.applied_amount - sum of adjustment_credit_notes.cn_total - sum of linked_taxes_withheld.amount.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

Example dunning_status[is] = "in_progress"
payment_owner[<operator>]
optional, string filter
Payment owner of an invoice.
Supported operators : is, is_not, starts_with, in, not_in

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

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

Example channel[is_not] = "APP STORE"
voided_at[<operator>]
optional, timestamp(UTC) in seconds filter
Timestamp indicating the date & time this invoice got voided.
Supported operators : after, before, on, between

Example voided_at[after] = "1394532759"
void_reason_code[<operator>]
optional, string filter
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive.
Supported operators : is, is_not, starts_with, in, not_in

Example void_reason_code[is] = "Other"
+
einvoice
Parameters for einvoice
pass parameters as einvoice[<param name>][<operator>]
einvoice[status][operator]
optional, enumerated string filter
The status of processing the e-invoice. To obtain detailed information about the current status, see message. Possible values are : scheduled, skipped, in_progress, success, failed.
Supported operators : is, is_not, in, not_in

Example einvoice[status][is] = "failed"
always returned
Resource object representing invoice
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”.
Retrieve the invoice for the specified invoice id.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__17 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__17 \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format GET

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

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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/pdf
disposition_type
optional, enumerated string, default=attachment
Determines the pdf should be rendered as inline or attachment in the browser.
Possible values are
attachmentPDF is rendered as attachment in the browserinlinePDF is rendered as inline in the browser
always returned
Resource object representing download

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

Note

  • You can only download e-invoices when their status is success.
  • There are some cases in which the PDF is not available for download. In such cases, you can obtain it from the XML by decoding the value for cbc:EmbeddedDocumentBinaryObject, which is the Base64-encoded version of the PDF.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/download_einvoice \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/download_einvoice \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format GET

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/download_einvoice
always returned
Resource object representing download

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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \
     -u {site_api_key}:\
     -d amount=150 \
     -d description="$0.05 each for 30 messages"
copy
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"

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/add_charge
amount
required, in cents, min=1
The amount to be charged. The unit depends on the type of currency.
description
required, string, max chars=250
Detailed description about this lineitem.
avalara_sale_type
optional, enumerated string
Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
Possible values are
wholesaleTransaction is a sale to another company that will resell your product or service to another consumerretailTransaction is a sale to an end userconsumedTransaction is for an item that is consumed directlyvendor_useTransaction is for an item that is subject to vendor use tax
avalara_transaction_type
optional, integer
Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
avalara_service_type
optional, integer
Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
subscription_id
optional, string, max chars=50
Identifier of the subscription for which this charge needs to be created. Applicable for consolidated invoice.
+
line_item
Parameters for line_item
pass parameters as line_item[<param name>]
line_item[date_from]
optional, timestamp(UTC) in seconds
The time when the service period for the charge starts.
line_item[date_to]
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
always returned
Resource object representing 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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_charge_item \
     -u {site_api_key}:\
     -d item_price[item_price_id]="ssl-charge-USD" \
     -d item_price[unit_price]=495
copy
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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/add_charge_item
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
subscription_id
optional, string, max chars=50
Identifier of the subscription for which this addon needs to be created. Applicable for consolidated invoice.
+
item_price
Parameters for item_price
pass parameters as item_price[<param name>]
item_price[item_price_id]
required, string, max chars=100
A unique ID for your system to identify the item price.
item_price[quantity]
optional, integer, min=1
Item price quantity
item_price[quantity_in_decimal]
optional, string, max chars=33
The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
item_price[unit_price]
optional, in cents, min=0
The price or per-unit-price of the item price. By default, it is the value set for the item_price. This is only applicable when the pricing_model of the item_price is flat_fee or per_unit. The value depends on the type of currency.
item_price[unit_price_in_decimal]
optional, string, max chars=33
The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
item_price[date_from]
optional, timestamp(UTC) in seconds
The time when the service period for the item starts.
item_price[date_to]
optional, timestamp(UTC) in seconds
The time when the service period for the item ends.
+
item_tiers
Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]
item_tiers[starting_unit][0..n]
optional, integer, min=1
The lowest value in the quantity tier.
item_tiers[ending_unit][0..n]
optional, integer
The highest value in the quantity tier.
item_tiers[price][0..n]
optional, in cents, default=0, min=0
The per-unit price for the tier when the pricing_model is tiered or volume. The total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
item_tiers[starting_unit_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
item_tiers[ending_unit_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
item_tiers[price_in_decimal][0..n]
optional, string, max chars=33
The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
always returned
Resource object representing 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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__8/close \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__8/close \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/close
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
invoice_note
optional, string, max chars=2000
A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
remove_general_note
optional, boolean, default=false
Set as true to remove the general note from this invoice.
invoice_date
optional, timestamp(UTC) in seconds
Set the invoice date. Must lie between the date when the invoice was generated and current date. Can only be passed when the site setting to allow overriding is enabled. If not passed, then the default value set at the site level is used.
+
notes_to_remove
Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]
notes_to_remove[entity_type][0..n]
optional, enumerated string
Type of entity to which the note belongs. To remove the general note, use the remove_general_note parameter.
Possible values are
customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Priceaddon_item_priceIndicates that this line item is based on addon Item Pricecharge_item_priceIndicates that this line item is based on charge Item Price
notes_to_remove[entity_id][0..n]
optional, string, max chars=100
Unique identifier of the note.
always returned
Resource object representing 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 API is used to collect payments for payment_due and not_paid invoices. If no payment methods are present for the customer or if the payment is unsuccessful, the corresponding error will be thrown.

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

Notes

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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/collect_payment
amount
optional, in cents, min=1
Amount to be collected. If this parameter is not passed then the entire amount due will be collected.
authorization_transaction_id
optional, string, max chars=40
Authorization transaction to be captured.
payment_source_id
optional, string, max chars=40
Payment source to be used for this payment.
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
always returned
Resource object representing invoice
always returned
Resource object representing transaction

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.

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_payment \
     -u {site_api_key}:\
     -d comment="Payment received" \
     -d transaction[amount]=200 \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]=1612800517
copy
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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/record_payment
comment
optional, string, max chars=300
Remarks, if any, on the payment.
+
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[amount]
optional, in cents, min=1
The payment transaction amount. If not specified, this value will be the invoice's due amount.
transaction[payment_method]
required, enumerated string, default=card
The payment method of this transaction
Possible values are
cashCashcheckCheck
bank_transferBank TransferotherPayment Methods other than the above typesupiupinetbanking_emandatesnetbanking_emandates
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
The reference number for this transaction. e.g check number in case of 'check' payments.
transaction[id_at_gateway]
optional, string, max chars=100
The id with which this transaction is referred in gateway.
transaction[status]
optional, enumerated string, default=success
The status of this transaction.
Possible values are
successThe transaction is successful.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure
transaction[date]
optional, timestamp(UTC) in seconds
Indicates when this transaction occurred.
transaction[error_code]
optional, string, max chars=100
Error code received from the payment gateway on failure.
transaction[error_text]
optional, string, max chars=65k
Error message received from the payment gateway on failure.
always returned
Resource object representing invoice
always returned
Resource object representing transaction

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

  • Tax Amount Withheld is enabled.
  • The invoice does not have a linked_taxes_withheld record associated with it already.
  • invoice.amount_due is greater than zero.
  • invoice.status is one of the following: payment_due, not_paid, or posted.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_tax_withheld \
     -u {site_api_key}:\
     -d tax_withheld[amount]=200 \
     -d tax_withheld[date]=1635080065
copy
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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/record_tax_withheld
+
tax_withheld
Parameters for tax_withheld
pass parameters as tax_withheld[<param name>]
tax_withheld[amount]
required, in cents, min=1
The amount withheld by the customer as tax from the invoice. This must not exceed invoice.amount_due. The unit depends on the type of currency.
tax_withheld[reference_number]
optional, string, max chars=100
A unique external reference number for the tax withheld. Typically, this is the reference number used by the system you are integrating the API with. Depending on your integration, this could be the reference number issued by the taxation authority to identify the customer or the specific tax transaction.
tax_withheld[date]
optional, timestamp(UTC) in seconds
Date or time associated with this tax amount withheld. The default value is the time of invoking this operation.
tax_withheld[description]
optional, string, max chars=65k
The description for this tax withheld.
always returned
Resource object representing invoice

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

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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/remove_tax_withheld
+
tax_withheld
Parameters for tax_withheld
pass parameters as tax_withheld[<param name>]
tax_withheld[id]
required, string, max chars=40
An auto-generated unique identifier for the tax withheld. The value starts with the prefix tax_wh_. For example, tax_wh_16BdDXSlbu4uV1Ee6.
always returned
Resource object representing 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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__14/refund \
     -u {site_api_key}:\
     -d refund_amount=500 \
     -d credit_note[reason_code]="service_unsatisfactory"
copy
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"

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/refund
refund_amount
optional, integer, min=1
The amount to be refunded. If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid via online transactions, and not already refunded. Note: Any linked_taxes_withheld associated with the invoice cannot be refunded via this operation.
comment
optional, string, max chars=300
Comment, if any, on the refund.
customer_notes
optional, string, max chars=2000
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
+
credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
credit_note[reason_code]
optional, enumerated string, default=other
The reason for issuing this Credit Note. The following reason codes are supported now[Deprecated; use the create_reason_code parameter instead]
Possible values are
product_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder CancellationwaiverWaiverotherCan be set when none of the above reason codes are applicable
Show all values[+]
credit_note[create_reason_code]
optional, string, max chars=100
Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. The codes are case-sensitive
always returned
Resource object representing invoice
always returned
Resource object representing transaction
optional
Resource object representing credit_note

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

Example

Consider an invoice with the following payments and tax withheld.

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

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

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

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

Tip

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

Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__13/record_refund \
     -u {site_api_key}:\
     -d transaction[amount]=100 \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]=1517490274
copy
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

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/record_refund
comment
optional, string, max chars=65k
Remarks, if any, on the refund.
customer_notes
optional, string, max chars=2000
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
+
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[amount]
optional, in cents, min=1
The amount to be refunded (for online payments) or recorded as refunded (for offline payments). If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid (and not already refunded) for the invoice. Note: Any linked_taxes_withheld associated with the invoice can also be recorded as refunded via this operation.
transaction[payment_method]
required, enumerated string, default=card
The payment method of this transaction
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 TransferotherPayment Methods other than the above types
Show all values[+]
transaction[reference_number]
optional, string, max chars=100
The reference number for this transaction. For example, the check number when payment_method = check.
transaction[date]
required, timestamp(UTC) in seconds
Indicates when this transaction occurred.
+
credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
credit_note[reason_code]
optional, enumerated string, default=other
The reason for issuing this Credit Note. The following reason codes are supported now[Deprecated; use the create_reason_code parameter instead]
Possible values are
chargebackCan be set when you are recording your customer Chargebacksproduct_unsatisfactoryProduct Unsatisfactoryservice_unsatisfactoryService Unsatisfactoryorder_changeOrder Changeorder_cancellationOrder CancellationwaiverWaiverotherCan be set when none of the above reason codes are applicable
Show all values[+]
credit_note[create_reason_code]
optional, string, max chars=100
Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. The codes are case-sensitive
always returned
Resource object representing invoice
optional
Resource object representing transaction
optional
Resource object representing credit_note

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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_payment \
     -X POST  \
     -u {site_api_key}:\
     -d transaction[id]="txn___test__8asyKSOcUWoQ6y"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_payment \
     -X POST  \
     -u {site_api_key}:\
     -d transaction[id]="txn___test__8asyKSOcUWoQ6y"

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/remove_payment
+
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[id]
required, string, max chars=40
Uniquely identifies the transaction.
always returned
Resource object representing invoice
always returned
Resource object representing transaction

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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__16/remove_credit_note \
     -X POST  \
     -u {site_api_key}:\
     -d credit_note[id]="__demo_cn__5"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__16/remove_credit_note \
     -X POST  \
     -u {site_api_key}:\
     -d credit_note[id]="__demo_cn__5"

Sample Response [ JSON ]

Show more...
{ "credit_note": { "allocations": [], "amount_allocated": 0, "amount_available": 3000, "amount_refunded": 0, "base_currency_code": "USD", "create_reason_code": "Service Unsatisfactory", "currency_code": "USD", "customer_id": "__test__8asyKSOcTKTb3h", "date": 1517490275, "deleted": false, "exchange_rate": 1, "fractional_correction": 0, "id": "__demo_cn__5", "line_item_discounts": [], "line_item_taxes": [], "line_items": [ { "amount": 3000, "customer_id": "__test__8asyKSOcTKTb3h", "date_from": 1517490275, "date_to": 1517490275, "description": "SSL Charge USD Monthly", "discount_amount": 0, "entity_id": "ssl-charge-USD", "entity_type": "charge_item_price", "id": "li___test__8asyKSOcTKdj3w", "is_taxed": false, "item_level_discount_amount": 0, "object": "line_item", "pricing_model": "flat_fee", "quantity": 1, "tax_amount": 0, "tax_exempt_reason": "tax_not_configured", "unit_amount": 3000 }, {..} ], "linked_refunds": [], "object": "credit_note", "price_type": "tax_exclusive", "reason_code": "service_unsatisfactory", "reference_invoice_id": "__demo_inv__15", "resource_version": 1517490276708, "round_off_amount": 0, "status": "refund_due", "sub_total": 3000, "taxes": [], "total": 3000, "type": "refundable", "updated_at": 1517490276 }, "invoice": { "adjustment_credit_notes": [], "amount_adjusted": 0, "amount_due": 4000, "amount_paid": 0, "amount_to_collect": 4000, "applied_credits": [], "base_currency_code": "USD", "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address", "validation_status": "not_validated" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__8asyKSOcTKTb3h", "date": 1517490276, "deleted": false, "due_date": 1517490276, "dunning_attempts": [], "exchange_rate": 1, "first_invoice": false, "has_advance_charges": false, "id": "__demo_inv__16", "is_gifted": false, "issued_credit_notes": [], "line_items": [ { "amount": 4000, "customer_id": "__test__8asyKSOcTKTb3h", "date_from": 1517490276, "date_to": 1517490276, "description": "Encryption Charge USD Monthly", "discount_amount": 0, "entity_id": "encryption-charge-USD", "entity_type": "charge_item_price", "id": "li___test__8asyKSOcTKia42", "is_taxed": false, "item_level_discount_amount": 0, "object": "line_item", "pricing_model": "flat_fee", "quantity": 1, "tax_amount": 0, "tax_exempt_reason": "tax_not_configured", "unit_amount": 4000 }, {..} ], "linked_orders": [], "linked_payments": [], "net_term_days": 0, "object": "invoice", "price_type": "tax_exclusive", "recurring": false, "resource_version": 1517490276709, "round_off_amount": 0, "status": "not_paid", "sub_total": 4000, "tax": 0, "term_finalized": true, "total": 4000, "updated_at": 1517490276, "write_off_amount": 0 } }

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/remove_credit_note
+
credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
credit_note[id]
required, string, max chars=50
Credit-note id.
always returned
Resource object representing invoice
always returned
Resource object representing credit_note

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

  • Any promotional credits or credit notes applied to the invoice are removed.
  • If an invoice for the current term of a subscription is voided and the subscription is changed later with proration enabled, no prorated credits are issued.
  • Any usages associated with item prices in the invoice are delinked from the invoice. This is done by clearing the invoice_id field of said usages. However, before this is done, a usage PDF is generated and saved to the invoice as an attachment.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/void \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/void \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/void
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
void_reason_code
optional, string, max chars=100
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive.
always returned
Resource object representing invoice
optional
Resource object representing credit_note
This API writes off an Invoice.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/write_off \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/write_off \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

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

Caution

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

  • Any promotional credits or credit notes applied to the invoice are removed.
  • If an invoice for the current term of a subscription is deleted and the subscription is changed later with proration enabled, no prorated credits are issued.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/delete
comment
optional, string, max chars=300
Reason for deleting the invoice. This comment will be added to the subscription entity if the invoice belongs to a subscription. It is added to the customer entity if the invoice is associated only with a customer.
claim_credits
optional, boolean, default=false
Indicates whether to put prorated credits back to the subscription or ignore while deleting the invoice.
always returned
Resource object representing invoice

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 Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/update_details \
     -u {site_api_key}:\
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US"
copy
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"

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/update_details
vat_number
optional, string, max chars=20
VAT/ Tax registration number of the customer. Learn more.
vat_number_prefix
optional, string, max chars=10
An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.
po_number
optional, string, max chars=100
Purchase Order Number for this invoice.
comment
optional, string, max chars=300
An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
+
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
optional, string, max chars=150
The first name of the billing contact.
billing_address[last_name]
optional, string, max chars=150
The last name of the billing contact.
billing_address[email]
optional, string, max chars=70
The email address.
billing_address[company]
optional, string, max chars=250
The company name.
billing_address[phone]
optional, string, max chars=50
The phone number.
billing_address[line1]
optional, string, max chars=150
Address line 1
billing_address[line2]
optional, string, max chars=150
Address line 2
billing_address[line3]
optional, string, max chars=150
Address line 3
billing_address[city]
optional, string, max chars=50
The name of the city.
billing_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
billing_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
billing_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
billing_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

billing_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
+
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
optional, string, max chars=150
The first name of the contact.
shipping_address[last_name]
optional, string, max chars=150
The last name of the contact.
shipping_address[email]
optional, string, max chars=70
The email address.
shipping_address[company]
optional, string, max chars=250
The company name.
shipping_address[phone]
optional, string, max chars=50
The phone number.
shipping_address[line1]
optional, string, max chars=150
Address line 1
shipping_address[line2]
optional, string, max chars=150
Address line 2
shipping_address[line3]
optional, string, max chars=150
Address line 3
shipping_address[city]
optional, string, max chars=50
The name of the city.
shipping_address[state_code]
optional, string, max chars=50
The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
shipping_address[state]
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
shipping_address[zip]
optional, string, max chars=20
Zip or postal code. The number of characters is validated according to the rules specified here.
shipping_address[country]
optional, string, max chars=50
The billing address country of the customer. Must be one of ISO 3166 alpha-2 country code.

Note: If you enter an invalid country code, the system will return an error.

Brexit

If you have enabled EU VAT in 2021 or later, or have manually enable the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.

shipping_address[validation_status]
optional, enumerated string, default=not_validated
The address verification status.
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validThe address is valid for taxability but has not been validated for shipping.invalidAddress is invalid.
always returned
Resource object representing invoice
Resend failed einvoice of an invoice to the customer using this API.
Sample Request
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/resend_einvoice \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__1/resend_einvoice \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/resend_einvoice
always returned
Resource object representing invoice