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.

Sample invoice [ JSON ]

{ "id": "1", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1414780212, "due_date": 1414780212, "net_term_days": 0, "exchange_rate": 1.0, "total": 900, "amount_paid": 900, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1414780213, "updated_at": 1496825867, "resource_version": 1496825867000, "deleted": false, "object": "invoice", "first_invoice": true, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqqTY9N", "date_from": 1414780212, "date_to": 1417372212, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 900, "description": "Basic", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 900, "linked_payments": [ { "txn_id": "txn_8asn8QLqqTdZO", "applied_amount": 900, "applied_at": 1414780213, "txn_status": "success", "txn_date": 1414780213, "txn_amount": 900 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [ { "cn_id": "TEST-CN-1", "cn_reason_code": "waiver", "cn_date": 1496825867, "cn_total": 100, "cn_status": "refund_due" }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "new", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1496825846 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" } }

API Index URL GET

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

Invoice attributes

id
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
string, max chars=50
po_number
Purchase Order Number for this invoice.
optional, string, max chars=100
customer_id
A unique identifier to identify the customer this invoice belongs to.
string, max chars=50
subscription_id
A unique identifier to identify the subscription this invoice belongs to.
optional, string, max chars=50
recurring
Boolean indicating whether this invoice belongs to a subscription.
boolean, default=true
status
Current status of this invoice.
enumerated string
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.pendingIndicates the invoice is not closed yet. New line items can be added when the invoice is in this state.
vat_number
VAT number of the customer to whom this invoice is raised.
optional, string, max chars=20
price_type
The price type of the invoice.
enumerated string, default=tax_exclusive
Possible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
date
Closing date of the invoice. Typically this is the date on which invoice is generated. If you have "wait & notify to send invoices enabled for usage based billing" this will not be the same as date on which invoice was actually sent to customer.
optional, timestamp(UTC) in seconds
due_date
Due date of the invoice.
optional, timestamp(UTC) in seconds
net_term_days
Number of days within which the invoice has to be paid.
optional, integer, default=0
currency_code
The currency code (ISO 4217 format) for the invoice.
string, max chars=3
total
Invoiced amount in cents.
optional, in cents, min=0
amount_paid
Total payments received for this invoice.
optional, in cents, min=0
amount_adjusted
Total adjustments made against this invoice.
optional, in cents, default=0, min=0
write_off_amount
Amount written off against this invoice.
optional, in cents, default=0, min=0
credits_applied
Total credits applied against this invoice.
optional, in cents, default=0, min=0
amount_due
Total amount to be collected.
optional, in cents, min=0
paid_at
Timestamp indicating the date & time this invoice got paid.
optional, timestamp(UTC) in seconds
dunning_status
Current dunning status of the invoice.
optional, enumerated string
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
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
optional, timestamp(UTC) in seconds
voided_at
Timestamp indicating the date & time this invoice got voided.
optional, timestamp(UTC) in seconds
resource_version
Version number of this resource. Each update of this resource results in incremental change of this number. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long
updated_at
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.
optional, timestamp(UTC) in seconds
sub_total
The invoice sub-total.
in cents, min=0
tax
Total tax amount for this invoice.
in cents, min=0
first_invoice
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.
optional, boolean
has_advance_charges
Boolean indicating any advance charge is present in this invoice.
optional, boolean
deleted
Indicates that this resource has been deleted.
boolean
line_items
Show attributes[+]
The list of line items for this invoice.
optional, list of line_item
Line item attributes
id
Uniquely identifies a line_item.
optional, string, max chars=40
subscription_id
A unique identifier for the subscription this lineitem belongs to.
optional, string, max chars=3
date_from
Start date of this lineitem.
timestamp(UTC) in seconds
date_to
End date of this lineitem.
timestamp(UTC) in seconds
unit_amount
Unit amount of the lineitem.
in cents
quantity
Quantity of the recurring item which is represented by this lineitem.
optional, integer, default=1
is_taxed
Specifies whether this line item is taxed or not.
boolean, default=false
tax_amount
The tax amount charged for this item.
optional, in cents, default=0, min=0
tax_rate
Rate of tax used to calculate tax for this lineitem.
optional, double, min=0.0, max=100.0
amount
Total amount of this lineitem. Typically equals to unit amount x quantity.
in cents
discount_amount
Total discounts for this line.
optional, in cents, min=0
item_level_discount_amount
'Item' level discounts for this line.
optional, in cents, min=0
description
Detailed description about this lineitem.
string, max chars=250
entity_type
Specifies the modelled entity (plan / addon etc) this lineitem is based on.
enumerated string
Possible values are
plan_setupIndicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id.planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.
tax_exempt_reason
The reason or category due to which the line item price/amount is excluded from taxable amount.
optional, enumerated string
Possible values are
tax_not_configuredIf tax is not enabled for the site.region_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 jurisdiction.exportIf the Merchant is not registered for Tax in this region, taxes will not be applied.customer_exemptIf the Customer is marked as Tax exempt.product_exemptIf the Plan or Addon is marked as Tax exempt.zero_ratedIf the rate of tax is 0% and no Sales/ GST tax is collectable for that line item.reverse_chargeIf the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU only .
entity_id
The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=50
discounts
Show attributes[+]
The list of discounts applied for this invoice.
optional, list of discount
Discount attributes
amount
Discount amount.
in cents, min=0
description
Detailed description of this discount line item.
optional, string, max chars=250
entity_type
Type of this Discount lineitem.
enumerated string
Possible values are
item_level_couponRepresents the 'Item' level coupons applied to this invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based on.document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'entity_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case.prorated_creditsRepresents the credit adjustment items in invoice. The 'entity_id' attribute will be null in this case.
entity_id
The identifier of the modelled entity this lineitem is bases on. Will be null for 'Prorated Credits' & 'Promotional Credits'.
optional, string, max chars=100
line_item_discounts
Show attributes[+]
The list of discount(s) applied for each line item of this invoice.
optional, list of line_item_discount
Line item discount attributes
line_item_id
The unique reference id of the line item for which the discount is applicable.
string, max chars=50
discount_type
Type of this discount line item.
enumerated string
Possible values are
item_level_couponRepresents the 'Item' level coupons applied to this invoice. Further the 'coupon_id' attribute specifies the coupon id this discount is based on.document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'coupon_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'coupon_id' attribute will be null in this case.prorated_creditsRepresents the credit adjustment items in invoice. The 'coupon_id' attribute will be null in this case.
coupon_id
Coupon id.
optional, string, max chars=50
discount_amount
Discount amount.
in cents, min=0
taxes
Show attributes[+]
The list of taxes applied for this invoice.
optional, list of tax
Tax attributes
name
The name of the tax applied. E.g. GST.
string, max chars=100
amount
The tax amount.
in cents, min=0
description
Description of the tax item.
optional, string, max chars=250
line_item_taxes
Show attributes[+]
The list of taxes applied on line items.
optional, list of line_item_tax
Line item tax attributes
line_item_id
The unique reference id of the line item for which the tax is applicable.
optional, string, max chars=40
tax_name
The name of the tax applied.
string, max chars=100
tax_rate
The rate of tax used to calculate tax amount.
double, default=0.0, min=0.0, max=100.0
tax_amount
The tax amount.
in cents, min=0
tax_juris_type
The type of tax jurisdiction.
optional, enumerated string
Possible values are
countryThe tax jurisdiction is a country.stateThe tax jurisdiction is a state.countyThe tax jurisdiction is a county.cityThe tax jurisdiction is a city.specialSpecial tax jurisdiction.otherJurisdictions other than the ones listed above.
tax_juris_name
The name of the tax jurisdiction.
optional, string, max chars=250
tax_juris_code
The tax jurisdiction code.
optional, string, max chars=250
linked_payments
Show attributes[+]
The list of transactions for this invoice.
optional, list of invoice_transaction
Linked payment attributes
txn_id
Uniquely identifies the transaction.
string, max chars=40
applied_amount
The transaction amount applied to this invoice.
in cents, min=0
applied_at
Timestamp at which the transaction is applied.
timestamp(UTC) in seconds
txn_status
The status of this transaction.
optional, enumerated string
Possible values are
in_progressTransaction is being processed via ACH.successTransaction is sucessful.voidedTransaction got voided.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.timeoutTransaction 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
Indicates when this transaction occurred.
optional, timestamp(UTC) in seconds
txn_amount
Total amount of the transaction.
optional, in cents, min=1
applied_credits
Show attributes[+]
Refundable Credits applied on this invoice.
optional, list of applied_credit
Applied credit attributes
cn_id

string, max chars=50
applied_amount

in cents, min=0
applied_at

timestamp(UTC) in seconds
cn_reason_code
Credit note reason code.
enumerated string, default=product_unsatisfactory
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 enabled.subscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operation.chargebackCan be set when you are recording your customer Chargebacks.
product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]
cn_date
Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds
cn_status
Credit note status.
enumerated string
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 canceled.
adjustment_credit_notes
Show attributes[+]
Adjustments created for this invoice.
optional, list of created_credit_note
Adjustment credit note attributes
cn_id
Credit-note id.
string, max chars=50
cn_reason_code
Credit note reason code.
enumerated string, default=product_unsatisfactory
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 enabled.subscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operation.chargebackCan be set when you are recording your customer Chargebacks.
product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]
cn_date
Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds
cn_total
Total amount of the credit note.
optional, in cents, default=0, min=0
cn_status
Credit note status.
enumerated string
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 canceled.
issued_credit_notes
Show attributes[+]
Credit notes issued for this invoice.
optional, list of created_credit_note
Issued credit note attributes
cn_id
Credit-note id.
string, max chars=50
cn_reason_code
Credit note reason code.
enumerated string, default=product_unsatisfactory
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 enabled.subscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operation.chargebackCan be set when you are recording your customer Chargebacks.
product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]
cn_date
Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds
cn_total
Total amount of the credit note.
optional, in cents, default=0, min=0
cn_status
Credit note status.
enumerated string
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 canceled.
linked_orders
Show attributes[+]
The list of orders for this invoice.
optional, list of order
Linked order attributes
id
Uniquely identifies the order.
string, max chars=40
status
The status of this order.
optional, enumerated string, default=new
Possible values are
newOrder has been created.processingOrder is being processed.completeOrder has been processed successfully.cancelledOrder has been cancelled.voidedOrder has been voided.
reference_id
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.
optional, string, max chars=50
fulfillment_status
The fulfillment status of an order as reflected in the shipping/order management application. Typical statuses include Shipped,Awaiting Shipment,Not fulfilled etc;.
optional, string, max chars=50
batch_id
Unique id to identify a group of orders.
optional, string, max chars=50
created_at
The time at which the order was created.
timestamp(UTC) in seconds
notes
Show attributes[+]
The list of notes associated with the invoice. If entity_type & entity_id are not present, then it is general notes (i.e Notes input provided under "Customize Invoice" action in Chargebee web interface).
optional, list of note
Note attributes
entity_type
Type of the entity for which this invoice notes belongs.
enumerated string
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
Actual note.
string, max chars=1000
entity_id
Unique identifier of the entity.
optional, string, max chars=100
shipping_address
Show attributes[+]
Shipping address for the invoice.
optional, shipping_address
Shipping addres attributes
first_name
First name.
optional, string, max chars=150
last_name
Last name.
optional, string, max chars=150
email
Email.
optional, string, max chars=70
company
Company name.
optional, string, max chars=250
phone
Phone number.
optional, string, max chars=50
line1
Address line 1.
optional, string, max chars=180
line2
Address line 2.
optional, string, max chars=150
line3
Address line 3.
optional, string, max chars=150
city
City.
optional, string, max chars=50
state_code
The ISO 3166-2 state/province code. Supported only for countries US and Canada.
optional, string, max chars=50
state
The state/province name.
optional, string, max chars=50
country
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
zip
Zip or Postal code.
optional, string, max chars=20
validation_status
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
billing_address
Show attributes[+]
Billing address for the invoice.
optional, billing_address
Billing addres attributes
first_name
First name.
optional, string, max chars=150
last_name
Last name.
optional, string, max chars=150
email
Email.
optional, string, max chars=70
company
Company name.
optional, string, max chars=250
phone
Phone number.
optional, string, max chars=50
line1
Address line 1.
optional, string, max chars=150
line2
Address line 2.
optional, string, max chars=150
line3
Address line 3.
optional, string, max chars=150
city
City.
optional, string, max chars=50
state_code
The ISO 3166-2 state/province code. Supported only for countries US and Canada.
optional, string, max chars=50
state
State or Province.
optional, string, max chars=50
country
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
zip
Zip or Postal code.
optional, string, max chars=20
validation_status
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

Create an invoice

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 
curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d charges[amount][1]="1000" \
     -d charges[description][1]="Support charge"
copy
curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}: \
     -d customer_id="8avVGOkx8U1MX" \
     -d charges[amount][1]="1000" \
     -d charges[description][1]="Support charge"

Sample Response [ JSON ]

{"invoice": { "id": "37", "customer_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "date": 1496825954, "due_date": 1496825954, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 400, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 600, "amount_due": 0, "paid_at": 1496825954, "updated_at": 1496825954, "resource_version": 1496825954000, "deleted": false, "object": "invoice", "first_invoice": true, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrA5N2W", "date_from": 1496825954, "date_to": 1496825954, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "Support charge", "entity_type": "adhoc", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0 }, {..} ], "sub_total": 1000, "linked_payments": [ { "txn_id": "txn_8asyvQLqrA702Z", "applied_amount": 400, "applied_at": 1496825954, "txn_status": "success", "txn_date": 1496825954, "txn_amount": 400 }, {..} ], "applied_credits": [ { "applied_amount": 100, "applied_at": 1496825954, "cn_id": "TEST-CN-1", "cn_reason_code": "waiver", "cn_date": 1496825867, "cn_status": "refunded" }, {..} ], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" } }}

URL Format POST

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

Input Parameters

customer_id
Identifier of the customer for which this invoice needs to be created.
required, string, max chars=50
currency_code
The currency code (ISO 4217 format) of the invoice amount.
required if Multicurrency is enabled, string, max chars=3
coupon
The 'One Time' coupon to be applied.
optional, string, max chars=50
po_number
Purchase Order Number for this invoice.
optional, string, max chars=100
payment_source_id
Payment source to be used for this payment.
optional, string, max chars=40
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code. The recommended way of passing the state/province information. Supported for US and Canada now. Further if this is specified, 'state' attribute should not be specified as it will be set automatically.
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
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]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
addons[quantity][0..n]
Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1
addons[unit_price][0..n]
Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0
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]
The amount to be charged.
optional, in cents, min=1
charges[description][0..n]
Description for this charge.
optional, string, max chars=250

Returns

invoice
Resource object representing invoice.
always returned

Create invoice for charge

This API is used to create an invoice for a one-time charge. If Auto Collection is 'ON' (i.e., default payment method is card), a payment attempt will be made on the customer's card. An invoice will be created only if the payment is successful. If Auto Collection is 'OFF', then a 'Payment Due' invoice will be created.

This one-off invoice can be associated with either a Customer or a Subscription. A coupon can be applied while creating this invoice only if it is associated with a customer. As it is a one-off invoice, coupons with "Duration Type" property set as "One Time" and "Apply on" property set as "Invoice Amount" can only be used.

To collect payment for the subscription at the end of the current term, use this API.

Notes

Available Credits and Excess Payments will automatically be applied to this invoice.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/charge \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d amount="1000" \
     -d description="Support charge"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/charge \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d amount="1000" \
     -d description="Support charge"

Sample Response [ JSON ]

{"invoice": { "id": "38", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "date": 1496825954, "due_date": 1496825954, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 1000, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1496825954, "updated_at": 1496825954, "resource_version": 1496825954000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrAD42g", "date_from": 1496825954, "date_to": 1496825954, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "Support charge", "entity_type": "adhoc", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 1000, "linked_payments": [ { "txn_id": "txn_8asyvQLqrADk2h", "applied_amount": 1000, "applied_at": 1496825954, "txn_status": "success", "txn_date": 1496825954, "txn_amount": 1000 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" }, "shipping_address": { "first_name": "Benjamin", "last_name": "Ross", "line1": "PO Box 9999", "city": "Walnut", "state_code": "CA", "state": "California", "country": "US", "zip": "91789", "validation_status": "not_validated", "object": "shipping_address" } }}

URL Format POST

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

Input Parameters

customer_id
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
optional, string, max chars=50
subscription_id
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.
optional, string, max chars=50
currency_code
The currency code (ISO 4217 format) of the invoice amount. Applicable only while creating an invoice for a customer (by specifying customer_id).
required if Multicurrency is enabled, string, max chars=3
amount
The amount to be charged.
required, in cents, min=1
description
Description for this charge.
required, string, max chars=250
coupon
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).
optional, string, max chars=50
po_number
Purchase Order Number for this invoice.
optional, string, max chars=100
payment_source_id
Payment source to be used for this payment.
optional, string, max chars=40

Returns

invoice
Resource object representing invoice.
always returned

Create invoice for addon

Creates a one-off invoice for a 'Non Recurring' addon. The charge will be collected immediately from the card on file if 'auto collection' is turned 'on'. The invoice will get created only if this collection attempt succeeds. However if the 'auto collection' is turned 'off', no collection attempt will be made and the invoice will be created as 'Payment Due'.

This one-off invoice can be associated with either a Customer or a Subscription. If associated with a Customer, a 'One Time' coupon applicable to this addon can be specified explictly while creating this invoice. This is not supported if the invoice is associated with a Subscription. However that Subscription's coupons applicable to this addon will get automatically applied during this invoice creation.

To collect payment for a 'Non Recurring' addon at the end of the current term, use this API.

Notes

Available Credits and Excess Payments will automatically be applied to this invoice.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/charge_addon \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d addon_id="ssl" \
     -d addon_unit_price="495"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/charge_addon \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d addon_id="ssl" \
     -d addon_unit_price="495"

Sample Response [ JSON ]

{"invoice": { "id": "39", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "date": 1496825955, "due_date": 1496825955, "net_term_days": 0, "exchange_rate": 1.0, "total": 495, "amount_paid": 495, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1496825955, "updated_at": 1496825955, "resource_version": 1496825955000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrAIm2m", "date_from": 1496825955, "date_to": 1496825955, "unit_amount": 495, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 495, "description": "Support Charge", "entity_type": "addon", "entity_id": "support_charge", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 495, "linked_payments": [ { "txn_id": "txn_8asyvQLqrAKS2n", "applied_amount": 495, "applied_at": 1496825955, "txn_status": "success", "txn_date": 1496825955, "txn_amount": 495 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" }, "shipping_address": { "first_name": "Benjamin", "last_name": "Ross", "line1": "PO Box 9999", "city": "Walnut", "state_code": "CA", "state": "California", "country": "US", "zip": "91789", "validation_status": "not_validated", "object": "shipping_address" } }}

URL Format POST

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

Input Parameters

customer_id
Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
optional, string, max chars=50
subscription_id
Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.
optional, string, max chars=50
addon_id
The ID of the non-recurring addon to be charged.
required, string, max chars=100
addon_quantity
The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1
addon_unit_price
Amount that will override the Addon's default price.
optional, in cents, default=0, min=0
coupon
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).
optional, string, max chars=50
po_number
Purchase Order Number for this invoice.
optional, string, max chars=100
payment_source_id
Payment source to be used for this payment.
optional, string, max chars=40

Returns

invoice
Resource object representing invoice.
always returned

Stop dunning for invoice

This API is used to stop dunning for "Payment Due" invoices that have been enabled for Auto Collection. When dunning is stopped, the status of the invoice will be changed to "Not Paid".
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/48/stop_dunning \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/48/stop_dunning \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"invoice": { "id": "41", "customer_id": "8asn8QLqrAT06y", "subscription_id": "8asn8QLqrAT06y", "recurring": true, "status": "not_paid", "price_type": "tax_exclusive", "date": 1496573956, "due_date": 1496573956, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 1000, "dunning_status": "stopped", "updated_at": 1496826003, "resource_version": 1496826003000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqrByK7N", "date_from": 1496573956, "date_to": 1499165956, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrAT06y" }, {..} ], "sub_total": 1000, "linked_payments": [ { "txn_id": "txn_8asn8QLqrByy7O", "applied_amount": 1000, "applied_at": 1496573957, "txn_status": "failure", "txn_date": 1496573957, "txn_amount": 1000 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "validation_status": "not_validated", "object": "billing_address" } }}

URL Format POST

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

Returns

invoice
Resource object representing invoice.
always returned

Import invoice

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="8avVGOkx8U1MX" \
     -d subscription_id="8avVGOkx8U1MX" \
     -d date="1394532759" \
     -d total="4900" \
     -d status="payment_due" \
     -d line_items[date_from][1]="1394532759" \
     -d line_items[date_to][1]="1396832759" \
     -d line_items[description][1]="Support Charge" \
     -d line_items[unit_amount][1]="4900" \
     -d line_items[quantity][1]="1" \
     -d line_items[entity_type][1]="plan" \
     -d line_items[entity_id][1]="basic" \
     -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/import_invoice \
     -u {site_api_key}: \
     -d id="old_inv_001" \
     -d customer_id="8avVGOkx8U1MX" \
     -d subscription_id="8avVGOkx8U1MX" \
     -d date="1394532759" \
     -d total="4900" \
     -d status="payment_due" \
     -d line_items[date_from][1]="1394532759" \
     -d line_items[date_to][1]="1396832759" \
     -d line_items[description][1]="Support Charge" \
     -d line_items[unit_amount][1]="4900" \
     -d line_items[quantity][1]="1" \
     -d line_items[entity_type][1]="plan" \
     -d line_items[entity_id][1]="basic" \
     -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 ]

{"invoice": { "id": "old_inv_001", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": true, "status": "payment_due", "price_type": "tax_exclusive", "date": 1394532759, "due_date": 1394532759, "net_term_days": 0, "exchange_rate": 1.0, "total": 4900, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 4900, "updated_at": 1496826003, "resource_version": 1496826003000, "deleted": false, "object": "invoice", "first_invoice": true, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrMvP2s", "date_from": 1394532759, "date_to": 1396832759, "unit_amount": 4900, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 4900, "description": "Support Charge", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 4900, "linked_payments": [], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "John", "last_name": "Doe", "line1": "PO Box 9999", "city": "Walnut", "state": "California", "country": "US", "zip": "91789", "validation_status": "not_validated", "object": "billing_address" } }}

URL Format POST

https://{site}.chargebee.com/api/v2/invoices/import_invoice

Input Parameters

id
Invoice Number.
required, string, max chars=50
currency_code
The currency code (ISO 4217 format) for the invoice.
required if Multicurrency is enabled, string, max chars=3
customer_id
Identifier of the customer for which this invoice needs to be created.
optional, string, max chars=50
subscription_id
If recurring items are present in line items then subscription id is required.
optional, string, max chars=50
po_number
Purchase Order Number for this invoice.
optional, string, max chars=100
price_type
The price type of the invoice.
optional, enumerated string, default=tax_exclusive
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
Applicbale for exempted (VAT exemption, Customer exemption etc) invoices.
optional, enumerated string
Possible values are
id_exemptVat Exempt.customer_exemptCustomer exemption from tax.
vat_number
Vat Number. Required if this invoice is VAT exempted.
optional, string, max chars=20
date
Date when invoice raised.
required, timestamp(UTC) in seconds
total
Invoice total amount.
required, in cents, min=0
round_off
Round off amount.
optional, in cents, min=0
status
Current status of this invoice.
optional, enumerated string, default=payment_due
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.
due_date
Invoice Due Date.
optional, timestamp(UTC) in seconds
net_term_days
Invoice net term days.
optional, integer, default=0
use_for_proration
If the invoice falls within the subscription current term will be used for proration.
optional, boolean, default=false
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
First name.
optional, string, max chars=150
billing_address[last_name]
Last name.
optional, string, max chars=150
billing_address[email]
Email.
optional, string, max chars=70
billing_address[company]
Company name.
optional, string, max chars=250
billing_address[phone]
Phone number.
optional, string, max chars=50
billing_address[line1]
Address line 1.
optional, string, max chars=150
billing_address[line2]
Address line 2.
optional, string, max chars=150
billing_address[line3]
Address line 3.
optional, string, max chars=150
billing_address[city]
City.
optional, string, max chars=50
billing_address[state_code]
The ISO 3166-2 state/province code. The recommended way of passing the state/province information. Supported for US and Canada now. Further if this is specified, 'state' attribute should not be specified as it will be set automatically.
optional, string, max chars=50
billing_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
billing_address[zip]
Zip or Postal code.
optional, string, max chars=20
billing_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
First name.
optional, string, max chars=150
shipping_address[last_name]
Last name.
optional, string, max chars=150
shipping_address[email]
Email.
optional, string, max chars=70
shipping_address[company]
Company name.
optional, string, max chars=250
shipping_address[phone]
Phone number.
optional, string, max chars=50
shipping_address[line1]
Address line 1.
optional, string, max chars=180
shipping_address[line2]
Address line 2.
optional, string, max chars=150
shipping_address[line3]
Address line 3.
optional, string, max chars=150
shipping_address[city]
City.
optional, string, max chars=50
shipping_address[state_code]
The ISO 3166-2 state/province code. The recommended way of passing the state/province information. Supported for US and Canada now. Further if this is specified, 'state' attribute should not be specified as it will be set automatically.
optional, string, max chars=50
shipping_address[state]
The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50
shipping_address[zip]
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validated
Possible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.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[date_from][0..n]
Start date of this lineitem.
optional, timestamp(UTC) in seconds
line_items[date_to][0..n]
End date of this lineitem.
optional, timestamp(UTC) in seconds
line_items[description][0..n]
Description for this line item.
required, string, max chars=250
line_items[unit_amount][0..n]
Unit amount of the lineitem.
optional, in cents
line_items[quantity][0..n]
Quantity of the recurring item which is represented by this lineitem.
optional, integer, default=1
line_items[amount][0..n]
Total amount of this lineitem. Not required if the line_items[unit_amount] param is passed.
optional, in cents
line_items[entity_type][0..n]
Specifies the modelled entity (plan / addon etc) this lineitem is based on.
optional, enumerated string, default=adhoc
Possible values are
plan_setupIndicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id.planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.
line_items[entity_id][0..n]
The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=50
line_items[item_level_discount1_entity_id][0..n]
First item level discount entity id.
optional, string, max chars=50
line_items[item_level_discount1_amount][0..n]
First item level discount amount.
optional, in cents, min=0
line_items[item_level_discount2_entity_id][0..n]
Second item level discount entity id.
optional, string, max chars=50
line_items[item_level_discount2_amount][0..n]
Second item level discount amount.
optional, in cents, min=0
line_items[tax1_name][0..n]
First tax name.
optional, string, max chars=50
line_items[tax1_amount][0..n]
First tax amount.
optional, in cents, min=0
line_items[tax2_name][0..n]
Second tax name.
optional, string, max chars=50
line_items[tax2_amount][0..n]
Second tax amount.
optional, in cents, min=0
line_items[tax3_name][0..n]
Third tax name.
optional, string, max chars=50
line_items[tax3_amount][0..n]
Third tax amount.
optional, in cents, min=0
line_items[tax4_name][0..n]
Fourth tax name.
optional, string, max chars=50
line_items[tax4_amount][0..n]
Fourth tax amount.
optional, in cents, min=0
discounts
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
discounts[entity_type][0..n]
Type of this Discount lineitem.
required, enumerated string
Possible values are
document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'entity_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case.
discounts[entity_id][0..n]
Coupon Id. Required, if the entity type is document level coupon.
optional, string, max chars=100
discounts[description][0..n]
Description of discount.
optional, string, max chars=250
discounts[amount][0..n]
Discount amount.
required, in cents, min=0
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]
The name of the tax applied.
required, string, max chars=100
taxes[rate][0..n]
The rate of tax used to calculate tax amount.
required, double, default=0.0, min=0.0, max=100.0
taxes[amount][0..n]
Total tax amount charged for this invoice.
optional, in cents, min=0
taxes[description][0..n]
Description of tax.
optional, string, max chars=null
taxes[juris_type][0..n]
The type of tax jurisdiction.
optional, enumerated string, default=other
Possible values are
countryThe tax jurisdiction is a country.stateThe tax jurisdiction is a state.countyThe tax jurisdiction is a county.cityThe tax jurisdiction is a city.specialSpecial tax jurisdiction.otherJurisdictions other than the ones listed above.
taxes[juris_name][0..n]
The name of the tax jurisdiction.
optional, string, max chars=250
taxes[juris_code][0..n]
The tax jurisdiction code.
optional, string, max chars=250
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]
Payment made for this invoice.
required, in cents, min=1
payments[payment_method][0..n]
Mode of payment.
required, enumerated string
Possible values are
cashCash.checkCheck.
bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
payments[date][0..n]
Payment date.
optional, timestamp(UTC) in seconds
payments[reference_number][0..n]
Reference number for this payment.
optional, string, min chars=1, max chars=100
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]
Type of the entity for which this invoice notes belongs.
optional, enumerated string
Possible values are
planEntity that represents a plan.addonEntity that represents an addon.couponEntity that represents a coupon.
notes[entity_id][0..n]
Id of the mentioned entity type.
optional, string, max chars=50
notes[note][0..n]
Actual note.
optional, string, max chars=1000

Returns

invoice
Resource object representing invoice.
always returned

List invoices

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[is]="paid" \
     --data-urlencode total[gt]="1000" \
     --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[is]="paid" \
     --data-urlencode total[is]="1000" \
     --data-urlencode sort_by[asc]="date"

Sample Response [ JSON ]

{ "list": [ {"invoice": { "id": "39", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "date": 1496825955, "due_date": 1496825955, "net_term_days": 0, "exchange_rate": 1.0, "total": 495, "amount_paid": 495, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1496825955, "updated_at": 1496825955, "resource_version": 1496825955000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrAIm2m", "date_from": 1496825955, "date_to": 1496825955, "unit_amount": 495, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 495, "description": "Support Charge", "entity_type": "addon", "entity_id": "support_charge", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 495, "linked_payments": [ { "txn_id": "txn_8asyvQLqrAKS2n", "applied_amount": 495, "applied_at": 1496825955, "txn_status": "success", "txn_date": 1496825955, "txn_amount": 495 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" }, "shipping_address": { "first_name": "Benjamin", "last_name": "Ross", "line1": "PO Box 9999", "city": "Walnut", "state_code": "CA", "state": "California", "country": "US", "zip": "91789", "validation_status": "not_validated", "object": "shipping_address" } }}, {..} ], "next_offset": "[\"1496825955000\",\"147000000267\"]" }

URL Format GET

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

Input Parameters

limit
Limits the number of resources to be returned.
optional, integer, default=10, min=1, max=100
offset
Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000
include_deleted
If set to true, includes the deleted resources in the response. For the deleted resources in the response, the 'deleted' attribute will be 'true'.
optional, boolean, default=false
sort_by[<sort-order>]
Sorts based on the specified attribute.
Supported attributes : date
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.
optional, string filter
Filter Params
For operator usages, see the Pagination and Filtering section.
id[<operator>]
To filter based on Invoice Id.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "INVOICE_654"
optional, string filter
subscription_id[<operator>]
To filter based on Invoice Subscription Id.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → subscription_id[is] = "3bdjnDnsdQn"
optional, string filter
customer_id[<operator>]
To filter based on Invoice Customer Id.
Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is_not] = "3bdjnDnsdQn"
optional, string filter
recurring[<operator>]
To filter based on Invoice Recurring. Possible values are : true, false
Supported operators : is

Example → recurring[is] = "true"
optional, boolean filter
status[<operator>]
To filter based on Invoice Status. Possible values are : paid, posted, payment_due, not_paid, voided, pending.
Supported operators : is, is_not, in, not_in

Example → status[is] = "paid"
optional, enumerated string filter
price_type[<operator>]
To filter based on Invoice Price Type. Possible values are : tax_exclusive, tax_inclusive.
Supported operators : is, is_not, in, not_in

Example → price_type[is] = "tax_exclusive"
optional, enumerated string filter
date[<operator>]
To filter based on Invoice End Date.
Supported operators : after, before, on, between

Example → date[after] = "1394532759"
optional, timestamp(UTC) in seconds filter
paid_at[<operator>]
To filter based on Invoice Paid On.
Supported operators : after, before, on, between

Example → paid_at[before] = "1394532759"
optional, timestamp(UTC) in seconds filter
total[<operator>]
To filter based on Invoice Amount.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → total[gte] = "1000"
optional, in cents filter
amount_paid[<operator>]
To filter based on Invoice Amount Paid.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_paid[is_not] = "800"
optional, in cents filter
amount_adjusted[<operator>]
To filter based on Invoice Amount Adjusted.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_adjusted[lte] = "100"
optional, in cents filter
credits_applied[<operator>]
To filter based on Invoice Amount Credited.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → credits_applied[gte] = "100"
optional, in cents filter
amount_due[<operator>]
To filter based on Invoice Amount Due.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_due[lt] = "200"
optional, in cents filter
dunning_status[<operator>]
To filter based on Invoice Dunning Status. Possible values are : in_progress, exhausted, stopped, success.
Supported operators : is, is_not, in, not_in, is_present

Example → dunning_status[is] = "in_progress"
optional, enumerated string filter
voided_at[<operator>]
To filter based on Voided At.
Supported operators : after, before, on, between

Example → voided_at[after] = "1394532759"
optional, timestamp(UTC) in seconds filter
updated_at[<operator>]
To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-09-28.
Supported operators : after, before, on, between

Example → updated_at[on] = "1243545465"
optional, timestamp(UTC) in seconds filter

Returns

invoice
Resource object representing invoice.
always returned
next_offset
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”.
optional, string, max chars=1000

Retrieve an invoice

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

Sample Response [ JSON ]

{"invoice": { "id": "1", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1414780212, "due_date": 1414780212, "net_term_days": 0, "exchange_rate": 1.0, "total": 900, "amount_paid": 900, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1414780213, "updated_at": 1496825945, "resource_version": 1496825945000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqqTY9N", "date_from": 1414780212, "date_to": 1417372212, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 900, "description": "Basic", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 900, "linked_payments": [ { "txn_id": "txn_8asn8QLqqTdZO", "applied_amount": 900, "applied_at": 1414780213, "txn_status": "success", "txn_date": 1414780213, "txn_amount": 900 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [ { "cn_id": "TEST-CN-1", "cn_reason_code": "waiver", "cn_date": 1496825867, "cn_total": 100, "cn_status": "refunded" }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1496825846 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" } }}

URL Format GET

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

Returns

invoice
Resource object representing invoice.
always returned

Sample admin console URL

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

Retrieve Invoice as PDF

Gets the invoice as PDF. The returned URL is secure and allows download. The URL will expire in 60 minutes.

Related Tutorial

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

Sample Response [ JSON ]

{"download": { "download_url": "https://cb-downloads-dev.s3.amazonaws.com/yourapp/invoice/8asyvQLqrNiZ2u.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Finvoice%2F8asyvQLqrNiZ2u.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20170607T090009Z&X-Amz-SignedHeaders=host&X-Amz-Expires=59&X-Amz-Credential=AKIAJ3MOW2V2DPJQTCMQ%2F20170607%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=5505c17ea0deeaa2d89e622fab092de64713203a15921ae7870f4d99d6506ab0", "valid_till": 1496826069, "object": "download" }}

URL Format POST

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

Returns

download
Resource object representing download.
always returned

Add charge item to pending invoice

Adds charge for 'pending' invoice. This API can be used for metered billing. After invoking this API, call close the pending invoice API to collect the charges.

Related Tutorial

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

Sample Response [ JSON ]

{"invoice": { "id": "43", "customer_id": "8asn8QLqrOUU8T", "subscription_id": "8asn8QLqrOUU8T", "recurring": true, "status": "pending", "price_type": "tax_exclusive", "date": 1496826010, "net_term_days": 0, "exchange_rate": 1.0, "total": 930, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 930, "updated_at": 1496826010, "resource_version": 1496826010000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrOdb2v", "date_from": 1496826010, "date_to": 1499072409, "unit_amount": 780, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 780, "description": "sample plan - Prorated Charges", "entity_type": "plan", "entity_id": "basic", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrOUU8T" }, {..} ], "sub_total": 930, "linked_payments": [], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [] }}

URL Format POST

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

Input Parameters

amount
The amount to be charged.
required, in cents, min=1
description
Detailed description about this lineitem.
required, string, max chars=250

Returns

invoice
Resource object representing invoice.
always returned

Add addon item to pending invoice

Adds non-recurring addon to the 'pending' invoice. This API can be used for metered billing. After invoking this API, call close the pending invoice API to collect the charges.

Related Tutorial

Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/12/add_addon_charge \
     -u {site_api_key}: \
     -d addon_id="ssl" \
     -d addon_unit_price="495"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/12/add_addon_charge \
     -u {site_api_key}: \
     -d addon_id="ssl" \
     -d addon_unit_price="495"

Sample Response [ JSON ]

{"invoice": { "id": "45", "customer_id": "8asn8QLqrOmD8h", "subscription_id": "8asn8QLqrOmD8h", "recurring": true, "status": "pending", "price_type": "tax_exclusive", "date": 1496826011, "net_term_days": 0, "exchange_rate": 1.0, "total": 1275, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 1275, "updated_at": 1496826011, "resource_version": 1496826011000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrOtu33", "date_from": 1496826011, "date_to": 1499072410, "unit_amount": 780, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 780, "description": "sample plan - Prorated Charges", "entity_type": "plan", "entity_id": "basic", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrOmD8h" }, {..} ], "sub_total": 1275, "linked_payments": [], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [] }}

URL Format POST

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

Input Parameters

addon_id
The ID of the non-recurring addon to be charged.
required, string, max chars=100
addon_quantity
The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1
addon_unit_price
Amount that will override the Addon's default price.
optional, in cents, default=0, min=0

Returns

invoice
Resource object representing invoice.
always returned

Close a pending invoice

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

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

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

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

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

Related Tutorial

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

Sample Response [ JSON ]

{"invoice": { "id": "47", "customer_id": "8asn8QLqrP4r8v", "subscription_id": "8asn8QLqrP4r8v", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1496826012, "due_date": 1496826012, "net_term_days": 0, "exchange_rate": 1.0, "total": 780, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 780, "amount_due": 0, "paid_at": 1496826012, "updated_at": 1496826012, "resource_version": 1496826012000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrPDl3B", "date_from": 1496826012, "date_to": 1499072411, "unit_amount": 780, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 780, "description": "sample plan - Prorated Charges", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrP4r8v" }, {..} ], "sub_total": 780, "linked_payments": [], "applied_credits": [ { "applied_amount": 780, "applied_at": 1496826012, "cn_id": "TEST-CN-5", "cn_reason_code": "subscription_change", "cn_date": 1496826012, "cn_status": "refund_due" }, {..} ], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "validation_status": "not_validated", "object": "billing_address" } }}

URL Format POST

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

Returns

invoice
Resource object representing invoice.
always returned

Collect payment for an invoice

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

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

Sample Response [ JSON ]

{ "invoice": { "id": "49", "customer_id": "8asn8QLqrPNJ99", "subscription_id": "8asn8QLqrPNJ99", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1496574013, "due_date": 1496574013, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 1000, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1496826051, "dunning_status": "stopped", "updated_at": 1496826051, "resource_version": 1496826051000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqrTvy9q", "date_from": 1496574013, "date_to": 1499166013, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrPNJ99" }, {..} ], "sub_total": 1000, "linked_payments": [ { "txn_id": "txn_8asn8QLqrTwf9r", "applied_amount": 1000, "applied_at": 1496574014, "txn_status": "failure", "txn_date": 1496574014, "txn_amount": 1000 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "validation_status": "not_validated", "object": "billing_address" } }, "transaction": { "id": "txn_8asyvQLqrZFb3L", "customer_id": "8asn8QLqrPNJ99", "subscription_id": "8asn8QLqrPNJ99", "gateway_account_id": "gw_8asn8QLqqJps2", "payment_method": "card", "gateway": "chargebee", "type": "payment", "date": 1496826051, "exchange_rate": 1.0, "amount": 1000, "id_at_gateway": "cb_8asyvQLqrZG63M", "status": "success", "updated_at": 1496826051, "resource_version": 1496826051000, "deleted": false, "object": "transaction", "masked_card_number": "************1111", "currency_code": "USD", "base_currency_code": "USD", "amount_unused": 0, "linked_invoices": [ { "invoice_id": "49", "applied_amount": 1000, "applied_at": 1496826051, "invoice_date": 1496574013, "invoice_total": 1000, "invoice_status": "paid" }, {..} ], "linked_refunds": [] } }

URL Format POST

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

Input Parameters

amount
Amount to be collected. If this parameter is not passed then the entire amount due will be collected.
optional, in cents, min=1
payment_source_id
Payment source to be used for this payment.
optional, string, max chars=40

Returns

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

Record an invoice payment

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's due amoumt, 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/8/record_payment \
     -u {site_api_key}: \
     -d transaction[amount]="200" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Check payment received for INV-001"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/8/record_payment \
     -u {site_api_key}: \
     -d transaction[amount]="200" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Check payment received for INV-001"

Sample Response [ JSON ]

{ "invoice": { "id": "51", "customer_id": "8asn8QLqrZMVAP", "subscription_id": "8asn8QLqrZMVAP", "recurring": true, "status": "payment_due", "price_type": "tax_exclusive", "date": 1496574051, "due_date": 1496574051, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 200, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 800, "dunning_status": "in_progress", "next_retry_at": 1496919653, "updated_at": 1496826060, "resource_version": 1496826060000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqrauWAo", "date_from": 1496574051, "date_to": 1499166051, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrZMVAP" }, {..} ], "sub_total": 1000, "linked_payments": [ { "txn_id": "txn_8asyvQLqrbld3P", "applied_amount": 200, "applied_at": 1496826060, "txn_status": "success", "txn_date": 1435054328, "txn_amount": 200 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "validation_status": "not_validated", "object": "billing_address" } }, "transaction": { "id": "txn_8asyvQLqrbld3P", "customer_id": "8asn8QLqrZMVAP", "subscription_id": "8asn8QLqrZMVAP", "payment_method": "bank_transfer", "gateway": "not_applicable", "type": "payment", "date": 1435054328, "exchange_rate": 1.0, "amount": 200, "status": "success", "updated_at": 1496826060, "resource_version": 1496826060000, "deleted": false, "object": "transaction", "currency_code": "USD", "base_currency_code": "USD", "amount_unused": 0, "linked_invoices": [ { "invoice_id": "51", "applied_amount": 200, "applied_at": 1496826060, "invoice_date": 1496574051, "invoice_total": 1000, "invoice_status": "payment_due" }, {..} ], "linked_refunds": [] } }

URL Format POST

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

Input Parameters

comment
Remarks, if any, on the payment.
optional, string, max chars=300
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[amount]
The payment transaction amount. If not specified, this value will be the invoice's due amount.
optional, in cents, min=1
transaction[payment_method]
The Payment Method of this transaction.
required, enumerated string, default=card
Possible values are
cashCash.checkCheck.
bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
transaction[reference_number]
The reference number for this transaction. e.g check number in case of 'check' payments.
optional, string, max chars=100
transaction[id_at_gateway]
The id with which this transaction is referred in gateway.
optional, string, max chars=100
transaction[status]
The status of this transaction.
optional, enumerated string, default=success
Possible values are
successTransaction is sucessful.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.
transaction[date]
Indicates when this transaction occurred.
optional, timestamp(UTC) in seconds
transaction[error_code]
Error code received from the payment gateway on failure.
optional, string, max chars=100
transaction[error_text]
Error message received from the payment gateway on failure.
optional, string, max chars=65k

Returns

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

Refund an invoice

This API is used for issuing a automatic 'refund' from a invoice to a customer. The refund request will be processed via the payment gateway that was originally 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. You can record refund for such invoices using our record refund API.
  • refund a fully refunded invoice.

If the refund transaction succeeds, a Credit Note capturing this refund detail will be created for this invoice.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/1/refund \
     -u {site_api_key}: \
     -d refund_amount="200"
copy
curl  https://{site}.chargebee.com/api/v2/invoices/1/refund \
     -u {site_api_key}: \
     -d refund_amount="200"

Sample Response [ JSON ]

{ "invoice": { "id": "1", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1414780212, "due_date": 1414780212, "net_term_days": 0, "exchange_rate": 1.0, "total": 900, "amount_paid": 900, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1414780213, "updated_at": 1496826061, "resource_version": 1496826061000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqqTY9N", "date_from": 1414780212, "date_to": 1417372212, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 900, "description": "Basic", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 900, "linked_payments": [ { "txn_id": "txn_8asn8QLqqTdZO", "applied_amount": 900, "applied_at": 1414780213, "txn_status": "success", "txn_date": 1414780213, "txn_amount": 900 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [ { "cn_id": "TEST-CN-1", "cn_reason_code": "waiver", "cn_date": 1496825867, "cn_total": 100, "cn_status": "refunded" }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1496825846 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" } }, "transaction": { "id": "txn_8asyvQLqrbqu3T", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "gateway_account_id": "gw_8asn8QLqqJps2", "payment_method": "card", "gateway": "chargebee", "type": "refund", "date": 1496826061, "exchange_rate": 1.0, "amount": 200, "id_at_gateway": "cb_8asyvQLqrbri3U", "status": "success", "updated_at": 1496826061, "resource_version": 1496826061000, "deleted": false, "object": "transaction", "masked_card_number": "************1111", "refunded_txn_id": "txn_8asn8QLqqTdZO", "linked_credit_notes": [ { "cn_id": "TEST-CN-6", "applied_amount": 200, "applied_at": 1496826061, "cn_reason_code": "other", "cn_date": 1496826061, "cn_total": 200, "cn_status": "refunded", "cn_reference_invoice_id": "1" }, {..} ], "currency_code": "USD", "base_currency_code": "USD" }, "credit_note": { "id": "TEST-CN-6", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "reference_invoice_id": "1", "type": "refundable", "reason_code": "other", "status": "refunded", "date": 1496826061, "price_type": "tax_exclusive", "exchange_rate": 1.0, "total": 200, "amount_allocated": 0, "amount_refunded": 200, "amount_available": 0, "refunded_at": 1496826061, "updated_at": 1496826061, "resource_version": 1496826061000, "deleted": false, "object": "credit_note", "currency_code": "USD", "base_currency_code": "USD", "sub_total": 200, "line_items": [ { "id": "li_8asyvQLqrbtH3W", "date_from": 1496826061, "date_to": 1496826061, "unit_amount": 200, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 200, "description": "Basic", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "taxes": [], "line_item_taxes": [], "line_item_discounts": [], "linked_refunds": [ { "applied_amount": 200, "applied_at": 1496826061, "txn_id": "txn_8asyvQLqrbqu3T", "txn_status": "success", "txn_date": 1496826061, "txn_amount": 200 }, {..} ], "allocations": [] } }

URL Format POST

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

Input Parameters

refund_amount
Amount to be refunded. If not specified, the entire refundable amount for this invoice will be refunded.
optional, integer, min=1
comment
Comment, if any, on the refund.
optional, string, max chars=300
customer_notes
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
optional, string, max chars=1000
credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
credit_note[reason_code]
The reason for issuing this Credit Note. The following reason codes are supported now.
optional, enumerated string, default=other
Possible values are
product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]

Returns

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

Record refund for an invoice

This API is used for recording offline refund for an invoice. Offline refunds can be recorded for invoices that have been paid via automatic payment methods(Card, Amazon Payments, Paypal Express Checkout etc), as well as offline payment methods.

Read more on refunds in our docs.

If the refund transaction is successfully recorded, a Credit Note capturing this refund detail will be created for this invoice.

Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/1/record_refund \
     -u {site_api_key}: \
     -d transaction[amount]="100" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Refunding as customer canceled the order."
copy
curl  https://{site}.chargebee.com/api/v2/invoices/1/record_refund \
     -u {site_api_key}: \
     -d transaction[amount]="100" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d comment="Refunding as customer canceled the order."

Sample Response [ JSON ]

{ "invoice": { "id": "1", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1414780212, "due_date": 1414780212, "net_term_days": 0, "exchange_rate": 1.0, "total": 900, "amount_paid": 900, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 0, "paid_at": 1414780213, "updated_at": 1496826061, "resource_version": 1496826061000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqqTY9N", "date_from": 1414780212, "date_to": 1417372212, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 900, "description": "Basic", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "sub_total": 900, "linked_payments": [ { "txn_id": "txn_8asn8QLqqTdZO", "applied_amount": 900, "applied_at": 1414780213, "txn_status": "success", "txn_date": 1414780213, "txn_amount": 900 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [ { "cn_id": "TEST-CN-1", "cn_reason_code": "waiver", "cn_date": 1496825867, "cn_total": 100, "cn_status": "refunded" }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1496825846 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "validation_status": "not_validated", "object": "billing_address" } }, "transaction": { "id": "txn_8asyvQLqrbyx3Z", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "payment_method": "bank_transfer", "gateway": "not_applicable", "type": "refund", "date": 1435054328, "exchange_rate": 1.0, "amount": 100, "status": "success", "updated_at": 1496826061, "resource_version": 1496826061000, "deleted": false, "object": "transaction", "linked_credit_notes": [ { "cn_id": "TEST-CN-7", "applied_amount": 100, "applied_at": 1496826061, "cn_reason_code": "other", "cn_date": 1435054328, "cn_total": 100, "cn_status": "refunded", "cn_reference_invoice_id": "1" }, {..} ], "currency_code": "USD", "base_currency_code": "USD" }, "credit_note": { "id": "TEST-CN-7", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "reference_invoice_id": "1", "type": "refundable", "reason_code": "other", "status": "refunded", "date": 1435054328, "price_type": "tax_exclusive", "exchange_rate": 1.0, "total": 100, "amount_allocated": 0, "amount_refunded": 100, "amount_available": 0, "refunded_at": 1496826061, "updated_at": 1496826061, "resource_version": 1496826061000, "deleted": false, "object": "credit_note", "currency_code": "USD", "base_currency_code": "USD", "sub_total": 100, "line_items": [ { "id": "li_8asyvQLqrbzC3b", "date_from": 1435054328, "date_to": 1435054328, "unit_amount": 100, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 100, "description": "Basic", "entity_type": "plan", "entity_id": "basic", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8avVGOkx8U1MX" }, {..} ], "taxes": [], "line_item_taxes": [], "line_item_discounts": [], "linked_refunds": [ { "applied_amount": 100, "applied_at": 1496826061, "txn_id": "txn_8asyvQLqrbyx3Z", "txn_status": "success", "txn_date": 1435054328, "txn_amount": 100 }, {..} ], "allocations": [] } }

URL Format POST

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

Input Parameters

comment
Remarks, if any, on the refund.
optional, string, max chars=65k
customer_notes
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
optional, string, max chars=1000
transaction
Parameters for transaction
pass parameters as transaction[<param name>]
transaction[amount]
Amount to be recorded as refunded. If this parameter is not passed then the entire refundable amount will be recorded as refunded.
optional, in cents, min=1
transaction[payment_method]
The Payment Method of this transaction.
required, enumerated string, default=card
Possible values are
cashCash.checkCheck.chargebackChargeback.
bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
transaction[reference_number]
The reference number for this transaction. e.g check number in case of 'check' payments.
optional, string, max chars=100
transaction[date]
Indicates when this transaction occurred.
required, timestamp(UTC) in seconds
credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
credit_note[reason_code]
The reason for issuing this Credit Note. The following reason codes are supported now.
optional, enumerated string, default=other
Possible values are
chargebackCan be set when you are recording your customer Chargebacks.
product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]

Returns

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

Void an invoice

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

Voiding an invoice is not possible if it has successful payment(s) applied.

Notes

  • If the invoice having charges for the 'current term' is voided and the subscription is changed subsequently with 'proration' enabled, the pro-rated credits will not be issued for the current-term charges (as its invoice became void)
  • Once voided, any Promotional Credits and Prorated Credits applied to this invoice would be reclaimed.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/13/void \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/13/void \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"invoice": { "id": "53", "customer_id": "8asn8QLqrc4kB7", "subscription_id": "8asn8QLqrc4kB7", "recurring": true, "status": "voided", "price_type": "tax_exclusive", "date": 1496826062, "net_term_days": 0, "exchange_rate": 1.0, "total": 780, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 780, "updated_at": 1496826062, "resource_version": 1496826062000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "voided_at": 1496826062, "tax": 0, "line_items": [ { "id": "li_8asyvQLqrcCW3g", "date_from": 1496826062, "date_to": 1499072461, "unit_amount": 780, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 780, "description": "sample plan - Prorated Charges", "entity_type": "plan", "entity_id": "basic", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrc4kB7" }, {..} ], "sub_total": 780, "linked_payments": [], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [] }}

URL Format POST

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

Input Parameters

comment
Reason for voiding invoice. This comment will be added to the invoice.
optional, string, max chars=300

Returns

invoice
Resource object representing invoice.
always returned

Write off an invoice

This API writes off an Invoice.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/1/write_off \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/1/write_off \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{ "invoice": { "id": "55", "customer_id": "8asn8QLqrcLRBL", "subscription_id": "8asn8QLqrcLRBL", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "date": 1496574063, "due_date": 1496574063, "net_term_days": 0, "exchange_rate": 1.0, "total": 1000, "amount_paid": 0, "amount_adjusted": 1000, "write_off_amount": 1000, "credits_applied": 0, "amount_due": 0, "paid_at": 1496826077, "dunning_status": "stopped", "updated_at": 1496826077, "resource_version": 1496826077000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asn8QLqrenWBq", "date_from": 1496574063, "date_to": 1499166063, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrcLRBL" }, {..} ], "sub_total": 1000, "linked_payments": [ { "txn_id": "txn_8asn8QLqreo5Br", "applied_amount": 1000, "applied_at": 1496574064, "txn_status": "failure", "txn_date": 1496574064, "txn_amount": 1000 }, {..} ], "applied_credits": [], "adjustment_credit_notes": [ { "cn_id": "TEST-CN-9", "cn_reason_code": "write_off", "cn_date": 1496826077, "cn_total": 1000, "cn_status": "adjusted" }, {..} ], "issued_credit_notes": [], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "validation_status": "not_validated", "object": "billing_address" } }, "credit_note": { "id": "TEST-CN-9", "customer_id": "8asn8QLqrcLRBL", "subscription_id": "8asn8QLqrcLRBL", "reference_invoice_id": "55", "type": "adjustment", "reason_code": "write_off", "status": "adjusted", "date": 1496826077, "price_type": "tax_exclusive", "exchange_rate": 1.0, "total": 1000, "amount_allocated": 1000, "amount_refunded": 0, "amount_available": 0, "refunded_at": 1496826077, "updated_at": 1496826077, "resource_version": 1496826077000, "deleted": false, "object": "credit_note", "currency_code": "USD", "base_currency_code": "USD", "sub_total": 1000, "line_items": [ { "id": "li_8asyvQLqrgEs3p", "date_from": 1496826077, "date_to": 1496826077, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "entity_type": "plan", "entity_id": "no_trial", "tax_exempt_reason": "tax_not_configured", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrcLRBL" }, {..} ], "taxes": [], "line_item_taxes": [], "line_item_discounts": [], "linked_refunds": [], "allocations": [ { "allocated_amount": 1000, "allocated_at": 1496826077, "invoice_id": "55", "invoice_date": 1496574063, "invoice_status": "paid" }, {..} ] } }

URL Format POST

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

Input Parameters

comment
Reason for writing off this invoice. This comment will be added to the invoice.
optional, string, max chars=300

Returns

invoice
Resource object representing invoice.
always returned
credit_note
Resource object representing credit_note.
always returned

Delete an invoice

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

Deleting an invoice is not possible if it has successful payment(s) applied

Notes

  • If the invoice having charges for the 'current term' is deleted and the subscription is changed subsequently with 'proration' enabled, the pro-rated credits will not be issued for the current-term charges (as its invoice got deleted)
  • During deletetion, any Promotional Credits and Prorated Credits applied to this invoice would be reclaimed.
Sample Request 
curl  https://{site}.chargebee.com/api/v2/invoices/13/delete \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v2/invoices/13/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"invoice": { "id": "57", "customer_id": "8asn8QLqrgIWCE", "subscription_id": "8asn8QLqrgIWCE", "recurring": true, "status": "pending", "price_type": "tax_exclusive", "date": 1496826078, "net_term_days": 0, "exchange_rate": 1.0, "total": 780, "amount_paid": 0, "amount_adjusted": 0, "write_off_amount": 0, "credits_applied": 0, "amount_due": 780, "updated_at": 1496826078, "resource_version": 1496826078000, "deleted": false, "object": "invoice", "first_invoice": false, "has_advance_charges": false, "currency_code": "USD", "base_currency_code": "USD", "tax": 0, "line_items": [ { "id": "li_8asyvQLqrgQn3t", "date_from": 1496826078, "date_to": 1499072478, "unit_amount": 780, "quantity": 1, "is_taxed": false, "tax_amount": 0, "object": "line_item", "amount": 780, "description": "sample plan - Prorated Charges", "entity_type": "plan", "entity_id": "basic", "discount_amount": 0, "item_level_discount_amount": 0, "subscription_id": "8asn8QLqrgIWCE" }, {..} ], "sub_total": 780, "linked_payments": [], "applied_credits": [], "adjustment_credit_notes": [], "issued_credit_notes": [], "linked_orders": [] }}

URL Format POST

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

Input Parameters

comment
Reason for deleting invoice. This comment will be added to the subscription entity if the invoice belongs to a subscription or added to the customer entity if the invoice is associated only with a customer.
optional, string, max chars=300

Returns

invoice
Resource object representing invoice.
always returned