You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).
    Library
You are viewing the documentation for the older version of our API (V1). Click here for information on upgrading to the latest version (V2).

Invoices

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

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

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

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

Sample invoice [ JSON ]

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

API Index URL GET

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

Invoice attributes

id
string, max chars=50
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
po_number
optional, string, max chars=100
Purchase Order Number for this invoice
customer_id
string, max chars=50
The identifier of the customer this invoice belongs to.
subscription_id
optional, string, max chars=50
The identifier of the subscription this invoice belongs to.
Note: When consolidated invoicing is enabled, you have to refer to line_item`s subscription_id to identify the subscriptions associated with this invoice. However, it is important to avoid using this attribute if the invoice includes charges from multiple subscriptions, as it will be null in such cases.
recurring
boolean, default=true
Boolean indicating whether this invoice belongs to a subscription
status
enumerated string
Current status of this invoice.
Possible values are
paidIndicates a paid invoice.payment_dueIndicates the payment is not yet collected and is being retried as per retry settings.not_paidIndicates the payment is not made and all attempts to collect is failed.voidedIndicates a voided invoice.pendingThe 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.
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.
start_date
timestamp(UTC) in seconds
Start date of the invoice.
end_date
optional, timestamp(UTC) in seconds
The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. However, if the invoice is created as pending, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date.
currency_code
string, max chars=3
The currency code (ISO 4217 format) for the invoice
amount
optional, in cents, min=0
Invoiced amount displayed in cents; that is, a decimal point is not present between the whole number and the decimal part. For example, $499.99 is displayed as 49999, and so on.
amount_paid
optional, in cents, min=0
Payments collected successfully for the invoice. This is the sum of linked_payments[].txn_amount for all linked_payments[] that have txn_status as success.
amount_adjusted
optional, in cents, default=0, min=0
Total adjustments made against this invoice.
credits_applied
optional, in cents, default=0, min=0
Total credits applied against this invoice.
amount_due
optional, in cents, min=0
The unpaid amount that is due on the invoice. This is calculated as: total - amount_paid - sum of applied_credits.applied_amount - sum of adjustment_credit_notes.cn_total - sum of linked_taxes_withheld.amount.
paid_on
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got paid.
dunning_status
optional, enumerated string
Current dunning status of the invoice.
Possible values are
in_progressDunning is still in progress.exhaustedMaximum number of attempts have been made.stoppedDunning has stopped for this invoice.successPayment successfully collected during dunning process.
next_retry
optional, timestamp(UTC) in seconds
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
sub_total
in cents, min=0
The sum of all the line item amounts minus the sum of all line item discounts. In other words, this is the sum of all line_items[].amount - the sum of all line_item_discounts[].discount_amount.
tax
in cents, min=0
Total tax amount for this invoice
first_invoice
optional, boolean
Boolean indicating the first invoice raised for the subscription. In the case of a non-recurring invoice, it indicates the first invoice raised for the customer.
line_items
Show attributes[+]
optional, list of line_item
The list of line items for this invoice
Line item attributes
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 which is represented by this line item.
amount
optional, in cents
Total amount of this line item. Typically equals to unit amount x quantity
is_taxed
boolean, default=false
Specifies whether this line item is taxed or not
tax
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
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.
type
enumerated string
Type of this lineitem. This along with 'entity_type' and 'entity_id' attributes consitutes the meta information of this lineitem.
Possible values are
chargeRepresents the 'charge' lineitems in invoice. The 'entity_type' attribute further identifies the modelled entity (plan / addon etc) this charge is based onprorated_chargeRepresents the 'charge' lineitems that are pro-rated. The 'entity_type' attribute further identifies the modelled entity (plan / addon etc) this 'prorated charge' is based onsetup_chargeRepresents the 'setup charge' lineitem in invoice - which is a one-time charge included only in the first invoice of the subscription
entity_type
enumerated string
Specifies the modelled entity this line item is based on.
Possible values are
planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan idaddonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon idadhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case
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
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.
type
enumerated string
Type of this Discount lineitem
Possible values are
couponRepresents the coupon discount items in invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based oncredit_adjustmentRepresents the Prorated Credits items in invoice. The 'entity_id' attribute will be null in this caseaccount_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case
entity_id
optional, string, max chars=100
When the deduction is due to a coupon, then this is the id of the coupon.
taxes
Show attributes[+]
optional, list of tax
The list of taxes applied for this invoice
Tax attributes
amount
in cents, min=0
The tax amount.
description
optional, string, max chars=250
Description of the tax item.
linked_transactions
Show attributes[+]
optional, list of invoice_transaction
The list of transactions for this invoice
Linked transaction 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_type
enumerated string
Type of the transaction.
Possible values are
authorizationThe transaction represents an authorization for capturing the amount from the customer’s payment_source.paymentThe transaction represents capture of amount from the customer’s payment_source.refundThe transaction represents a refund of amount to the customer’s payment_source.payment_reversalIndicates a reversal transaction.
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
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
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 systemvoidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management system
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
notes
Show attributes[+]
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
planEntity that represents a plan.addonEntity that represents an addon.couponEntity that represents a coupon.subscriptionEntity that represents a subscription of customer.customerEntity that represents a customer.
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.
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.

Create an invoice

Idempotency Supported
Note: This operation optionally supports 3DS verification flow. To achieve the same, create the Payment Intent and pass it as input parameter to this API.

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

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

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

Notes

Available Credits and Excess Payments will automatically be applied to this invoice.
Sample Request 
# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v1/invoices \
     -u {site_api_key}:\
     -d customer_id="__test__3Nl7obaRNQyaXr1S" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[quantity][0]=2 \
     -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/v1/invoices \
     -u {site_api_key}:\
     -d customer_id="__test__3Nl7obaRNQyaXr1S" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[quantity][0]=2 \
     -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": { "amount": 200, "amount_adjusted": 0, "amount_due": 0, "amount_paid": 200, "billing_address": { "first_name": "John", "last_name": "Mathew", "object": "billing_address" }, "credits_applied": 0, "currency_code": "USD", "customer_id": "__test__3Nl7obaRNQyaXr1S", "end_date": 1517492040, "first_invoice": true, "id": "__demo_inv__13", "line_items": [ { "amount": 200, "date_from": 1517492040, "date_to": 1517492040, "description": "non_recurring_addon", "entity_id": "non_recurring_addon", "entity_type": "addon", "is_taxed": false, "object": "line_item", "quantity": 2, "tax": 0, "type": "charge", "unit_amount": 100 }, {..} ], "linked_orders": [], "linked_transactions": [ { "applied_amount": 200, "applied_at": 1517492041, "txn_amount": 200, "txn_date": 1517492041, "txn_id": "txn___test__3Nl7obaRNQyacB1a", "txn_status": "success", "txn_type": "payment" }, {..} ], "object": "invoice", "paid_on": 1517492041, "price_type": "tax_exclusive", "recurring": false, "start_date": 1517492040, "status": "paid", "sub_total": 200, "tax": 0 }}

URL Format POST

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

Input Parameters

customer_id
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
subscription_id
optional, string, max chars=50
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.(not applicable for consolidated invoice).
po_number
optional, string, max chars=100
Purchase Order Number for this invoice.
coupon
optional, string, max chars=100
The 'One Time' coupon to be applied.
replace_primary_payment_source
optional, boolean, default=false
Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
+
shipping_address
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.

+
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[reference_id]
optional, string, max chars=65k
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
+
addons
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
addons[id][0..n]
optional, string, max chars=100
Identifier of the addon. Multiple addons can be passed.
addons[quantity][0..n]
optional, integer, default=1, min=1
Quantity of the addon. Applicable for addons with pricing_model other than flat_fee.
+
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[description][0..n]
optional, string, max chars=250
Description for this charge

Returns

invoice
always returned
Resource object representing invoice

Create invoice for a one-time charge

Idempotency Supported
This API generates invoices for a one-time charge.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/charge \
     -u {site_api_key}:\
     -d subscription_id="__test__3Nl7obaRNQyaqJ24" \
     -d amount=1000 \
     -d description="Support Charge"
copy
curl  https://{site}.chargebee.com/api/v1/invoices/charge \
     -u {site_api_key}:\
     -d subscription_id="__test__3Nl7obaRNQyaqJ24" \
     -d amount=1000 \
     -d description="Support Charge"

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

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

Returns

invoice
always returned
Resource object representing invoice

Create invoice for a non-recurring addon

Idempotency Supported
This API generates invoices for a non-recurring addon.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/charge_addon \
     -u {site_api_key}:\
     -d subscription_id="__test__3Nl7obaRNQyagm1k" \
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=2
copy
curl  https://{site}.chargebee.com/api/v1/invoices/charge_addon \
     -u {site_api_key}:\
     -d subscription_id="__test__3Nl7obaRNQyagm1k" \
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=2

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

customer_id
optional, string, max chars=50
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
subscription_id
optional, string, max chars=50
Identifier of the subscription for which this invoice(not applicable for consolidated invoice) needs to be created. Should be specified if 'customer_id' is not specified.
addon_id
required, string, max chars=100
The ID of the non-recurring addon to be charged.
addon_quantity
optional, integer, min=1
The number of addon units to be charged. Mandatory for quantity based addons.
coupon
optional, string, max chars=100
The 'One Time' coupon to be applied. Supported only if this one-off invoice is associated with a Customer(i.e customer_id is specified).
po_number
optional, string, max chars=100
Purchase Order Number for this invoice.

Returns

invoice
always returned
Resource object representing invoice

Stop dunning for invoice

Idempotency Supported
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/v1/invoices/__demo_inv__36/stop_dunning \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__36/stop_dunning \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

Returns

invoice
always returned
Resource object representing invoice

List invoices

Lists all the Invoices.

Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3
copy
curl  https://{site}.chargebee.com/api/v1/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3

Sample Response [ JSON ]

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

URL Format GET

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

Input Parameters

limit
optional, integer, default=10, min=1, max=100
The number of resources to be returned.
offset
optional, string, max chars=1000
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
paid_on_after
optional, timestamp(UTC) in seconds
Returns only the invoices that got paid at/after this time. Invoices list will be sorted by 'paid_on' in ascending order.

Returns

invoice
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”.

List invoices for a customer

Lists all the invoices (latest first) for the specified customer.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/customers/__test__3Nl7obaRNQybMo2n/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/customers/__test__3Nl7obaRNQybMo2n/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

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

URL Format GET

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

Input Parameters

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.

Returns

invoice
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”.

List invoices for a subscription

Lists all the invoices (latest first) for the specified subscription.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__3Nl7obaRNQybUb35/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2
copy
curl  https://{site}.chargebee.com/api/v1/subscriptions/__test__3Nl7obaRNQybUb35/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=2

Sample Response [ JSON ]

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

URL Format GET

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

Input Parameters

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.

Returns

invoice
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 an invoice

Retrieve the invoice for the specified invoice id.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__33 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__33 \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format GET

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

Returns

invoice
always returned
Resource object representing invoice

Sample admin console URL

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

Retrieve Invoice as PDF

Idempotency Supported

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

URL Format POST

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

Returns

download
always returned
Resource object representing download

Add one-time charge to a pending invoice

Idempotency Supported
This API endpoint adds a one-time charge to a pending invoice.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__4/add_charge \
     -u {site_api_key}:\
     -d amount=150 \
     -d description="$0.05 each for 30 messages"
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__4/add_charge \
     -u {site_api_key}:\
     -d amount=150 \
     -d description="$0.05 each for 30 messages"

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

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.

Returns

invoice
always returned
Resource object representing invoice

Add non-recurring addon to a pending invoice

Idempotency Supported
This API endpoint adds a non-recurring addon to a pending invoice.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/add_addon_charge \
     -u {site_api_key}:\
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=2
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__2/add_addon_charge \
     -u {site_api_key}:\
     -d addon_id="non_recurring_addon" \
     -d addon_quantity=2

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

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

Returns

invoice
always returned
Resource object representing invoice

Close pending invoice

Idempotency Supported

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

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

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

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

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

Related Tutorial

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

Sample Response [ JSON ]

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

URL Format POST

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

Returns

invoice
always returned
Resource object representing invoice

Collect payment for an invoice

Idempotency Supported

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

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

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

amount
optional, in cents, min=1
Amount to be collected. If this parameter is not passed then the entire amount due will be collected.

Returns

invoice
always returned
Resource object representing invoice
transaction
always returned
Resource object representing transaction

Refund an invoice

Idempotency Supported

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

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

Read more on refunds in our docs.

Error will be thrown if you attempt to:

  • refund an offline invoice. To record refund for such invoices, use this API.
  • refund an entirely refunded invoice.
Sample Request 
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__28/refund \
     -u {site_api_key}:\
     -d refund_amount=1000
copy
curl  https://{site}.chargebee.com/api/v1/invoices/__demo_inv__28/refund \
     -u {site_api_key}:\
     -d refund_amount=1000

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

refund_amount
optional, in cents, min=1
The amount to be refunded. If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid via online transactions, and not already refunded. Note: Any linked_taxes_withheld associated with the invoice cannot be refunded via this operation.
memo
optional, string, max chars=300
Comment, if any, on the refund.

Returns

invoice
always returned
Resource object representing invoice
transaction
always returned
Resource object representing transaction

Record refund for an invoice

Idempotency Supported

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

Read more on refunds in our docs.

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

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

memo
required, string, max chars=65k
Remarks, if any, on the refund.
+
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.

Returns

invoice
always returned
Resource object representing invoice
transaction
optional
Resource object representing transaction

Void an invoice

Idempotency Supported

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

Voiding an invoice is not possible

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

Notes

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

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

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.

Returns

invoice
always returned
Resource object representing invoice

Delete an invoice

Idempotency Supported

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

Deleting an invoice is not possible

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

Notes

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

Sample Response [ JSON ]

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

URL Format POST

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

Input Parameters

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.

Returns

invoice
always returned
Resource object representing invoice