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

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

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

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

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

Sample invoice [ JSON ]

{ "id": "1", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "start_date": 1412101830, "end_date": 1414780230, "amount": 900, "amount_paid": 900, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1414780231, "object": "invoice", "first_invoice": true, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1414780230, "date_to": 1417372230, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "Basic", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 900, "linked_transactions": [ { "txn_id": "txn_3Nl8YKPQ8YayJEE", "applied_amount": 900, "applied_at": 1414780231, "txn_type": "payment", "txn_status": "success", "txn_date": 1414780231, "txn_amount": 900 }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "new", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1484646413 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "object": "billing_address" } }

API Index URL GET

https://{site}.chargebee.com/api/v1/invoices
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
The identifier of the customer this invoice belongs to.
string, max chars=50
subscription_id
The identifier of the subscription this invoice belongs to.
Note: If consolidated invoicing is enabled, to know the subscriptions attached with this invoice you have to refer line_item's subscription_id. This attribute should not be used (which will be null if this invoice has charges from multiple subscriptions).
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.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/ Tax registration number of the customer. Learn more.
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.
start_date
Start date of the invoice.
timestamp(UTC) in seconds
end_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
currency_code
The currency code (ISO 4217 format) for the invoice.
string, max chars=3
amount
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
credits_applied
Total credits applied against this invoice.
optional, in cents, default=0, min=0
amount_due
Total amount to be collected. This includes invoice's payments in progress.
optional, in cents, min=0
paid_on
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
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
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
line_items
Show attributes[+]
The list of line items for this invoice.
optional, list of line_item
Line item attributes
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
amount
Total amount of this lineitem. Typically equals to unit amount x quantity.
optional, in cents
is_taxed
Specifies whether this line item is taxed or not.
boolean, default=false
tax
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
description
Detailed description about this lineitem.
string, max chars=250
type
Type of this lineitem. This along with 'entity_type' and 'entity_id' attributes consitutes the meta information of this lineitem.
enumerated string
Possible values are
chargeRepresents the 'charge' lineitems in invoice. The 'entity_type' attribute further identifies the modelled entity (plan / addon etc) this charge is based on.prorated_chargeRepresents the 'charge' lineitems that are pro-rated. The 'entity_type' attribute further identifies the modelled entity (plan / addon etc) this 'prorated charge' is based on.setup_chargeRepresents the 'setup charge' lineitem in invoice - which is a one-time charge included only in the first invoice of the subscription.
entity_type
Specifies the modelled entity (plan / addon etc) this lineitem is based on.
enumerated string
Possible values are
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.
entity_id
The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100
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
type
Type of this Discount lineitem.
enumerated string
Possible values are
couponRepresents the coupon discount items in invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based on.credit_adjustmentRepresents the Prorated Credits items in invoice. The 'entity_id' attribute will be null in this case.account_creditsRepresents the Promotional Credits item 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
The list of taxes applied for this invoice.
optional, list of tax
Tax attributes
amount
The tax amount.
in cents, min=0
description
Description of the tax item.
optional, string, max chars=250
linked_transactions
Show attributes[+]
The list of transactions for this invoice.
optional, list of invoice_transaction
Linked transaction 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_type
Type of the transaction.
enumerated string
Possible values are
authorizationIndicates the authorization transaction.paymentIndicates the payment transaction.refundIndicates a refund transaction.payment_reversalIndicates a reversal transaction.
txn_status
The status of this transaction.
optional, enumerated string
Possible values are
in_progressTransaction is being processed via ACH.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for 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
linked_orders
Show attributes[+]
The list of orders for this invoice.
optional, list of linked_order
Linked order attributes
id
Uniquely identifies the order. It is the api identifier for the order.
string, max chars=40
status
The status of this order.
optional, enumerated string, default=new
Possible values are
newOrder has been created. Applicable only if you are using Chargebee's legacy order management system.processingOrder is being processed. Applicable only if you are using Chargebee's legacy order management system.completeOrder has been processed successfully. Applicable only if you are using Chargebee's legacy order management system.cancelledOrder has been cancelled. Applicable only if you are using Chargebee's legacy order management system.voidedOrder has been voided. Applicable only if you are using Chargebee's legacy order management system.
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
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 without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
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
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 without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
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

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/v1/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/v1/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": "32", "customer_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484646503, "end_date": 1484646503, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646504, "object": "invoice", "first_invoice": true, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646503, "date_to": 1484646503, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "Support charge", "type": "charge", "entity_type": "adhoc" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YTUQ8YbQhP7O", "applied_amount": 1000, "applied_at": 1484646504, "txn_type": "payment", "txn_status": "success", "txn_date": 1484646504, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "object": "billing_address" } }}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices
customer_id
Identifier of the customer for which this invoice needs to be created.
required, string, max chars=50
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
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 without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
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
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
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
Resource object representing invoice.
always returned

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

Sample Response [ JSON ]

{"invoice": { "id": "33", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484646504, "end_date": 1484646504, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646504, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646504, "date_to": 1484646504, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "Support charge", "type": "charge", "entity_type": "adhoc" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YTUQ8YbQmD7U", "applied_amount": 1000, "applied_at": 1484646504, "txn_type": "payment", "txn_status": "success", "txn_date": 1484646504, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "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", "object": "shipping_address" } }}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/charge
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.(not applicable for consolidated invoice).
optional, string, max chars=50
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
Resource object representing invoice.
always returned

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/v1/invoices/charge_addon \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d addon_id="ssl"
copy
curl  https://{site}.chargebee.com/api/v1/invoices/charge_addon \
     -u {site_api_key}: \
     -d subscription_id="8avVGOkx8U1MX" \
     -d addon_id="ssl"

Sample Response [ JSON ]

{"invoice": { "id": "34", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484646504, "end_date": 1484646504, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646504, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646504, "date_to": 1484646504, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "Support Charge", "type": "charge", "entity_type": "addon", "entity_id": "support_charge" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YTUQ8YbQri7a", "applied_amount": 1000, "applied_at": 1484646504, "txn_type": "payment", "txn_status": "success", "txn_date": 1484646504, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "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", "object": "shipping_address" } }}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/charge_addon
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(not applicable for consolidated 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
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
Resource object representing invoice.
always returned
This API is used to stop dunning for "Payment Due" invoices that have been enabled for Auto Collection. When dunning is stopped, the status of the invoice will be changed to "Not Paid".
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/48/stop_dunning \
     -X POST  \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/invoices/48/stop_dunning \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

{"invoice": { "id": "36", "customer_id": "3Nl8YKPQ8YbQwM6h", "subscription_id": "3Nl8YKPQ8YbQwM6h", "recurring": true, "status": "not_paid", "price_type": "tax_exclusive", "start_date": 1484300904, "end_date": 1484394505, "amount": 1000, "amount_paid": 0, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 1000, "dunning_status": "stopped", "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484394505, "date_to": 1487072905, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "type": "charge", "entity_type": "plan", "entity_id": "no_trial" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YKPQ8YbSU173", "applied_amount": 1000, "applied_at": 1484394506, "txn_type": "payment", "txn_status": "failure", "txn_date": 1484394506, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "object": "billing_address" } }}

URL Format POST

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

Lists all the Invoices.

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

Sample Response [ JSON ]

{ "list": [ {"invoice": { "id": "34", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484646504, "end_date": 1484646504, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646504, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646504, "date_to": 1484646504, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "Support Charge", "type": "charge", "entity_type": "addon", "entity_id": "support_charge" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YTUQ8YbQri7a", "applied_amount": 1000, "applied_at": 1484646504, "txn_type": "payment", "txn_status": "success", "txn_date": 1484646504, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "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", "object": "shipping_address" } }}, {..} ], "next_offset": "[\"1484646504000\",\"113000000300\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/invoices
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
paid_on_after
Returns only the invoices that got paid at/after this time. Invoices list will be sorted by 'paid_on' in ascending order.
optional, timestamp(UTC) in seconds
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
Lists all the invoices (latest first) for the specified customer.
Sample Request
curl  https://{site}.chargebee.com/api/v1/customers/8avVGOkx8U1MX/invoices \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v1/customers/8avVGOkx8U1MX/invoices \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"invoice": { "id": "34", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484646504, "end_date": 1484646504, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646504, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646504, "date_to": 1484646504, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "Support Charge", "type": "charge", "entity_type": "addon", "entity_id": "support_charge" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YTUQ8YbQri7a", "applied_amount": 1000, "applied_at": 1484646504, "txn_type": "payment", "txn_status": "success", "txn_date": 1484646504, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "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", "object": "shipping_address" } }}, {..} ], "next_offset": "[\"1484646504000\",\"113000000300\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/customers/{customer_id}/invoices
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
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
Lists all the invoices (latest first) for the specified subscription.
Sample Request
curl  https://{site}.chargebee.com/api/v1/subscriptions/8avVGOkx8U1MX/invoices \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"
copy
curl  https://{site}.chargebee.com/api/v1/subscriptions/8avVGOkx8U1MX/invoices \
     -G  \
     -u {site_api_key}: \
     --data-urlencode limit="5"

Sample Response [ JSON ]

{ "list": [ {"invoice": { "id": "34", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "recurring": false, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484646504, "end_date": 1484646504, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646504, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646504, "date_to": 1484646504, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "Support Charge", "type": "charge", "entity_type": "addon", "entity_id": "support_charge" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YTUQ8YbQri7a", "applied_amount": 1000, "applied_at": 1484646504, "txn_type": "payment", "txn_status": "success", "txn_date": 1484646504, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "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", "object": "shipping_address" } }}, {..} ], "next_offset": "[\"1484646504000\",\"113000000300\"]" }

URL Format GET

https://{site}.chargebee.com/api/v1/subscriptions/{subscription_id}/invoices
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
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 the invoice for the specified invoice id.
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/1 \
     -u {site_api_key}:
copy
curl  https://{site}.chargebee.com/api/v1/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", "start_date": 1412101830, "end_date": 1414780230, "amount": 900, "amount_paid": 900, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1414780231, "object": "invoice", "first_invoice": true, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1414780230, "date_to": 1417372230, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "Basic", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 900, "linked_transactions": [ { "txn_id": "txn_3Nl8YKPQ8YayJEE", "applied_amount": 900, "applied_at": 1414780231, "txn_type": "payment", "txn_status": "success", "txn_date": 1414780231, "txn_amount": 900 }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1484646413 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "object": "billing_address" } }}

URL Format GET

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

Sample admin console URL

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

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

Related Tutorial

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

Sample Response [ JSON ]

{"download": { "download_url": "https://cb-downloads-dev.s3.amazonaws.com/yourapp/invoice/3Nl8YTUQ8YbVmE7f.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Finvoice%2F3Nl8YTUQ8YbVmE7f.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20170117T094848Z&X-Amz-SignedHeaders=host&X-Amz-Expires=59&X-Amz-Credential=AKIAJ3MOW2V2DPJQTCMQ%2F20170117%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=e96d4c974da509904e5eb9c54d81f4b953caa37c10996c4dcc5dc8e1480d56a3", "valid_till": 1484646588, "object": "download" }}

URL Format POST

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

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/v1/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/v1/invoices/12/add_charge \
     -u {site_api_key}: \
     -d amount="150" \
     -d description="$0.05 each for 30 messages"

Sample Response [ JSON ]

{"invoice": { "id": "38", "customer_id": "3Nl8YKPQ8YbX4t7K", "subscription_id": "3Nl8YKPQ8YbX4t7K", "recurring": true, "status": "pending", "price_type": "tax_exclusive", "start_date": 1484300928, "end_date": 1484646528, "amount": 934, "amount_paid": 0, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 934, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646528, "date_to": 1486979328, "unit_amount": 784, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 784, "description": "sample plan - Prorated Charges", "type": "prorated_charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 934, "linked_transactions": [], "linked_orders": [] }}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/add_charge
amount
The amount to be charged.
required, in cents, min=1
description
Detailed description about this lineitem.
required, string, max chars=250
Resource object representing invoice.
always returned

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/v1/invoices/12/add_addon_charge \
     -u {site_api_key}: \
     -d addon_id="ssl"
copy
curl  https://{site}.chargebee.com/api/v1/invoices/12/add_addon_charge \
     -u {site_api_key}: \
     -d addon_id="ssl"

Sample Response [ JSON ]

{"invoice": { "id": "40", "customer_id": "3Nl8YKPQ8YbXDR7W", "subscription_id": "3Nl8YKPQ8YbXDR7W", "recurring": true, "status": "pending", "price_type": "tax_exclusive", "start_date": 1484300929, "end_date": 1484646529, "amount": 1784, "amount_paid": 0, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 1784, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646529, "date_to": 1486979329, "unit_amount": 784, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 784, "description": "sample plan - Prorated Charges", "type": "prorated_charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 1784, "linked_transactions": [], "linked_orders": [] }}

URL Format POST

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

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

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

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

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

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

Related Tutorial

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

Sample Response [ JSON ]

{"invoice": { "id": "42", "customer_id": "3Nl8YKPQ8YbXMn7i", "subscription_id": "3Nl8YKPQ8YbXMn7i", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484300929, "end_date": 1484646529, "amount": 784, "amount_paid": 0, "amount_adjusted": 0, "credits_applied": 784, "amount_due": 0, "paid_on": 1484646530, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646529, "date_to": 1486979329, "unit_amount": 784, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 784, "description": "sample plan - Prorated Charges", "type": "prorated_charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 784, "linked_transactions": [], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "object": "billing_address" } }}

URL Format POST

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

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

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

Sample Response [ JSON ]

{ "invoice": { "id": "44", "customer_id": "3Nl8YKPQ8YbXZc7u", "subscription_id": "3Nl8YKPQ8YbXZc7u", "recurring": true, "status": "paid", "price_type": "tax_exclusive", "start_date": 1484300930, "end_date": 1484394530, "amount": 1000, "amount_paid": 1000, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1484646558, "dunning_status": "stopped", "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484394530, "date_to": 1487072930, "unit_amount": 1000, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 1000, "description": "No Trial", "type": "charge", "entity_type": "plan", "entity_id": "no_trial" }, {..} ], "sub_total": 1000, "linked_transactions": [ { "txn_id": "txn_3Nl8YKPQ8Ybcn68Y", "applied_amount": 1000, "applied_at": 1484394531, "txn_type": "payment", "txn_status": "failure", "txn_date": 1484394531, "txn_amount": 1000 }, {..} ], "linked_orders": [], "billing_address": { "first_name": "Rachel", "last_name": "Green", "object": "billing_address" } }, "transaction": { "id": "txn_3Nl8YTUQ8Ybevo86", "customer_id": "3Nl8YKPQ8YbXZc7u", "subscription_id": "3Nl8YKPQ8YbXZc7u", "payment_method": "card", "gateway": "chargebee", "type": "payment", "date": 1484646558, "amount": 1000, "id_at_gateway": "cb_3Nl8YTUQ8Ybew687", "status": "success", "object": "transaction", "masked_card_number": "************1111", "currency_code": "USD", "amount_unused": 0, "linked_invoices": [ { "invoice_id": "44", "applied_amount": 1000, "applied_at": 1484646558, "invoice_date": 1484394530, "invoice_amount": 1000 }, {..} ], "linked_refunds": [] } }

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/collect_payment
amount
Amount to be collected. If this parameter is not passed then the entire amount due will be collected.
optional, in cents, min=1
Resource object representing invoice.
always returned
Resource object representing transaction.
always returned

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

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

Read more on refunds in our docs.

Error will be thrown if you attempt to:

  • refund an offline invoice. To record refund for such invoices, use this API.
  • refund an entirely refunded invoice.
Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/1/refund \
     -u {site_api_key}: \
     -d refund_amount="200"
copy
curl  https://{site}.chargebee.com/api/v1/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", "start_date": 1412101830, "end_date": 1414780230, "amount": 900, "amount_paid": 900, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1414780231, "object": "invoice", "first_invoice": true, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1414780230, "date_to": 1417372230, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "Basic", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 900, "linked_transactions": [ { "txn_id": "txn_3Nl8YKPQ8YayJEE", "applied_amount": 900, "applied_at": 1414780231, "txn_type": "payment", "txn_status": "success", "txn_date": 1414780231, "txn_amount": 900 }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1484646413 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "object": "billing_address" } }, "transaction": { "id": "txn_3Nl8YTUQ8Ybf0e8A", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "payment_method": "card", "gateway": "chargebee", "type": "refund", "date": 1484646559, "amount": 200, "id_at_gateway": "cb_3Nl8YTUQ8Ybf0o8B", "status": "success", "object": "transaction", "masked_card_number": "************1111", "refunded_txn_id": "txn_3Nl8YKPQ8YayJEE", "linked_invoices": [ { "invoice_id": "1", "applied_amount": 200, "applied_at": 1484646559, "invoice_date": 1414780230, "invoice_amount": 900 }, {..} ], "currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/refund
refund_amount
Amount to be refunded. If not specified, the entire refundable amount for this invoice will be refunded.
optional, integer, min=1
memo
Comment, if any, on the refund.
optional, string, max chars=300
Resource object representing invoice.
always returned
Resource object representing transaction.
always returned

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

Read more on refunds in our docs.

Sample Request
curl  https://{site}.chargebee.com/api/v1/invoices/1/record_refund \
     -u {site_api_key}: \
     -d transaction[amount]="100" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d memo="Refunding as customer canceled the order."
copy
curl  https://{site}.chargebee.com/api/v1/invoices/1/record_refund \
     -u {site_api_key}: \
     -d transaction[amount]="100" \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]="1435054328" \
     -d memo="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", "start_date": 1412101830, "end_date": 1414780230, "amount": 900, "amount_paid": 900, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 0, "paid_on": 1414780231, "object": "invoice", "first_invoice": true, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1414780230, "date_to": 1417372230, "unit_amount": 900, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 900, "description": "Basic", "type": "charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 900, "linked_transactions": [ { "txn_id": "txn_3Nl8YKPQ8YayJEE", "applied_amount": 900, "applied_at": 1414780231, "txn_type": "payment", "txn_status": "success", "txn_date": 1414780231, "txn_amount": 900 }, {..} ], "linked_orders": [ { "id": "XpbG8t4OvwWgjzM", "status": "processing", "reference_id": "1002", "fulfillment_status": "Awaiting Shipment", "created_at": 1484646413 }, {..} ], "billing_address": { "first_name": "Benjamin", "last_name": "Ross", "object": "billing_address" } }, "transaction": { "id": "txn_3Nl8YTUQ8Ybf6e8G", "customer_id": "8avVGOkx8U1MX", "subscription_id": "8avVGOkx8U1MX", "payment_method": "bank_transfer", "gateway": "not_applicable", "description": "Refunding as customer canceled the order.", "type": "refund", "date": 1435054328, "amount": 100, "status": "success", "object": "transaction", "linked_invoices": [ { "invoice_id": "1", "applied_amount": 100, "applied_at": 1484646559, "invoice_date": 1414780230, "invoice_amount": 900 }, {..} ], "currency_code": "USD" } }

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/record_refund
memo
Remarks, if any, on the refund.
required, string, max chars=65k
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
Resource object representing invoice.
always returned
Resource object representing transaction.
always returned

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

Voiding an invoice is not possible

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

Notes

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

Sample Response [ JSON ]

{"invoice": { "id": "46", "customer_id": "3Nl8YKPQ8YbfCY94", "subscription_id": "3Nl8YKPQ8YbfCY94", "recurring": true, "status": "voided", "price_type": "tax_exclusive", "start_date": 1484300959, "end_date": 1484646560, "amount": 784, "amount_paid": 0, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 784, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646560, "date_to": 1486979359, "unit_amount": 784, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 784, "description": "sample plan - Prorated Charges", "type": "prorated_charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 784, "linked_transactions": [], "linked_orders": [] }}

URL Format POST

https://{site}.chargebee.com/api/v1/invoices/{invoice_id}/void
comment
Reason for voiding invoice. This comment will be added to the invoice.
optional, string, max chars=300
Resource object representing invoice.
always returned

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

Deleting an invoice is not possible

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

Notes

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

Sample Response [ JSON ]

{"invoice": { "id": "48", "customer_id": "3Nl8YKPQ8YbfOk9G", "subscription_id": "3Nl8YKPQ8YbfOk9G", "recurring": true, "status": "pending", "price_type": "tax_exclusive", "start_date": 1484300960, "end_date": 1484646560, "amount": 784, "amount_paid": 0, "amount_adjusted": 0, "credits_applied": 0, "amount_due": 784, "object": "invoice", "first_invoice": false, "currency_code": "USD", "tax": 0, "line_items": [ { "date_from": 1484646560, "date_to": 1486979360, "unit_amount": 784, "quantity": 1, "is_taxed": false, "tax": 0, "object": "line_item", "amount": 784, "description": "sample plan - Prorated Charges", "type": "prorated_charge", "entity_type": "plan", "entity_id": "basic" }, {..} ], "sub_total": 784, "linked_transactions": [], "linked_orders": [] }}

URL Format POST

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