Invoices

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

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

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

Auto-collection

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

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

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

Sample invoice [ JSON ]

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

API Index URL GET

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

id

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.postedIndicates the payment is not yet collected and will be in this state till the due date to indicate the due period.payment_dueIndicates the payment is not yet collected and is being retried as per retry settings.not_paidIndicates the payment is not made and all attempts to collect is failed.voidedIndicates a voided invoice.pendingThe invoice is yet to be closed (sent for payment collection). An invoice is generated with this status when it has line items that belong to items that are metered or when the subscription.create_pending_invoicesattribute is set to true.

vat_number

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.

date

The document date displayed on the invoice PDF. By default, it has the same value as the effective date of the action that created the invoice (subscription creation, update, or invoice creation). This date can be backdated (set to a value in the past) while performing the actions. Backdating an invoice is done for reasons such as booking revenue for a previous date or when the subscription or non-recurring charge is effective as of a past date. However, if the invoice is created as pending, and if the site is configured to set invoice dates to the date of closing, then upon invoice closure, this date is changed to the invoice closing date.
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

exchange_rate

Exchange rate used for base currency conversion.
optional, bigdecimal, min=1E-9, max=999999999.999999999

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. This includes invoice's payments in progress.
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.
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

sub_total_in_local_currency

Invoice subtotal in the currency of the place of supply.
optional, in cents, min=0

total_in_local_currency

Total invoice amount in the currency of the place of supply.
optional, in cents, min=0

local_currency_code

The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.
optional, string, max chars=null

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

new_sales_amount

The share of the invoice total due to new sales. When first_invoice is true, this attribute is the same as total. However, when the invoice is a consolidated one, then it is the sum of all line_items.amount belonging to a new.
optional, in cents, min=0

has_advance_charges

Boolean indicating any advance charge is present in this invoice.
optional, boolean

term_finalized

Boolean indicating this invoice line_items terms are finalized or not.
boolean, default=true

is_gifted

Boolean indicating this invoice is gifted or not.
boolean, default=false

generated_at

The date when the invoice is finalized. This is the date in the invoice lifecycle when its status becomes any one of the following for the first time: payment_due, posted, or paid. For an invoice with status as pending, this happens when it gets closed.
optional, timestamp(UTC) in seconds

expected_payment_date

Expected payment date recorded for this invoice.
optional, timestamp(UTC) in seconds

amount_to_collect

Total amount to be collected.
optional, in cents, min=0

round_off_amount

Indicates the rounded-off amount.
optional, in cents, min=0

payment_owner

Payment owner of an invoice.
optional, string, max chars=null

void_reason_code

Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive.
optional, string, max chars=100

deleted

Indicates that this resource has been deleted.
boolean

vat_number_prefix

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address country as XI (which is United Kingdom - Northern Ireland).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address country as XI. That’s the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.
optional, string, max chars=10

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 line item belongs to.
optional, string, max chars=3

date_from

Start date of this line item.
timestamp(UTC) in seconds

date_to

End date of this line item.
timestamp(UTC) in seconds

unit_amount

Unit amount of the line item.
in cents

quantity

Quantity of the recurring item which is represented by this line item. For metered line items, this value is updated from usages once when the invoice is generated as pending and finally when the invoice is closed.
optional, integer, default=1

amount

Total amount of this line item. Typically equals to unit amount x quantity.
optional, in cents

pricing_model

The pricing scheme for this item price.
optional, enumerated string

Possible values are

flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.

is_taxed

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

unit_amount_in_decimal

The decimal representation of the unit amount of the line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

quantity_in_decimal

The decimal representation of the quantity of this line_item. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

amount_in_decimal

The decimal representation of the amount for the line_item, in major units of the currency. Typically equals to unit_amount_in_decimal x quantity_in_decimal. Returned when multi-decimal pricing is enabled.
optional, string, max chars=33

discount_amount

Total discounts for this line.
optional, in cents, min=0

item_level_discount_amount

Line Item-level discounts for this line.
optional, in cents, min=0

description

Detailed description about this line item.
string, max chars=250

entity_description

Detailed description about this item.
string, max chars=500

entity_type

Specifies the modelled entity this line item is based on.
enumerated string

Possible values are

adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.plan_item_priceIndicates that this line item is based on plan Item Price.addon_item_priceIndicates that this line item is based on addon Item Price.charge_item_priceIndicates that this line item is based on charge Item Price.

tax_exempt_reason

The reason due to which the line item price/amount is exempted from tax.
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.exportYou are not registered for tax in the customer’s region. This is also the reason code when both billing_address and shipping_address have not been provided for the customer and subscription respectively.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.high_value_physical_goodsIf physical goods are sold from outside Australia to customers in Australia, and the price of all the physical good line items is greater than AUD 1000, then tax will not be applied.

entity_id

The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100

customer_id

A unique identifier for the customer this line item belongs to.
optional, string, max chars=100

discounts
Show attributes[+]

The list of all deductions applied to the invoice.
optional, list of discount

Discount attributes

amount

The amount deducted. The format of this value depends on the kind of currency.
in cents, min=0

description

Description for this deduction.
optional, string, max chars=250

line_item_id

The unique id of the line item that this deduction is for. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.
optional, string, max chars=40

entity_type

The type of deduction and the amount to which it is applied.
enumerated string

Possible values are

item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. .prorated_creditsThe deduction is due to a legacy adjustment credit applied to the invoice. The entity_id is null in this case. The legacy credits feature is superseded by adjustment_credit_notes.item_level_discount(Beta) The deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id.document_level_discount(Beta) The deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.

discount_type

The type of discount that is applied to the line item. Relevant only when discounts[entity_type] is one of item_level_discount , item_level_coupon, document_level_discount, or document_level_coupon.
optional, enumerated string

Possible values are

fixed_amountwhen amount is applied as discount.percentagewhen percentage is applied as discount.

entity_id

When the deduction is due to a coupon or a discount, then this is the id of the coupon or discount.
optional, string, max chars=100

line_item_discounts
Show attributes[+]

The list of deduction(s) applied for each line item of this invoice.
optional, list of line_item_discount

Line item discount attributes

line_item_id

The unique id of the line item that this deduction is for.
string, max chars=50

discount_type

The type of deduction and the amount to which it is applied.
enumerated string

Possible values are

item_level_couponThe deduction is due to a coupon applied to a line item of the invoice. The coupon id is available as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is available as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. The entity_id is null in this case.prorated_creditsThe deduction is due to a legacy adjustment credit applied to the invoice. The entity_id is null in this case. The legacy credits feature is superseded by adjustment_credit_notes.item_level_discount(Beta) The deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id.document_level_discount(Beta) The deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.

entity_id

When the deduction is due to a coupon or a discount, then this is the id of the coupon or discount.
optional, string, max chars=50

discount_amount

The amount deducted. The format of this value depends on the kind of currency.
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

is_partial_tax_applied

Indicates if tax is applied only on a portion of the line item amount.
optional, boolean

is_non_compliance_tax

Indicates the non-compliance tax that should not be reported to the jurisdiction.
optional, boolean

taxable_amount

Indicates the actual portion of the line item amount that is taxable.
in cents, min=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.federalThe tax jurisdiction is a federal.stateThe tax jurisdiction is a state.countyThe tax jurisdiction is a county.cityThe tax jurisdiction is a city.specialSpecial tax jurisdiction.unincorporatedCombined tax of state and county.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

tax_amount_in_local_currency

Total tax amount in the currency of the place of supply. This is applicable only for Invoice and Credit Notes API.
optional, in cents, min=0

local_currency_code

The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.
optional, string, max chars=null

line_item_tiers
Show attributes[+]

The list of tiers applicable for this line item.
optional, list of line_item_tier

Line item tier attributes

line_item_id

Uniquely identifies a line_item.
optional, string, max chars=40

starting_unit

The lower limit of a range of units for the tier.
integer, min=0

ending_unit

The upper limit of a range of units for the tier.
optional, integer

quantity_used

The number of units purchased in a range.
integer, min=0

unit_amount

The price of the tier if the charge model is a stairtstep pricing , or the price of each unit in the tier if the charge model is tiered/volume pricing.
in cents, min=0

starting_unit_in_decimal

The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the line_items.pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33

ending_unit_in_decimal

The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the line_items.pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33

quantity_used_in_decimal

The decimal representation of the quantity purchased from this tier. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

unit_amount_in_decimal

The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for line_item. The value is in major units of the currency. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=40

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 by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for 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

dunning_attempts
Show attributes[+]

The list of dunning_attempts for this invoice.
optional, list of dunning_attempt

Dunning attempt attributes

attempt

Dunning attempt number.
integer

transaction_id

Transaction associated with attempt.
optional, string, max chars=40

dunning_type

Types of dunning.
enumerated string, default=auto_collect

Possible values are

auto_collectDunning type is auto collection.offlineDunning type is offline.direct_debitDunning type is direct debit.

created_at

Timestamp at which the attempt was made.
optional, timestamp(UTC) in seconds

txn_status

The status of this transaction.
optional, enumerated string

Possible values are

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. Deprecated; use the cn_create_reason_code parameter instead.
optional, enumerated string

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.subscription_pauseThis reason will be automatically set to credit notes created during pause/resume 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.fraudulentFRAUDULENT.

Show all values[+]

cn_create_reason_code

Credit note reason code.
optional, string, max chars=100

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 cancelled.

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. Deprecated; use the cn_create_reason_code parameter instead.
optional, enumerated string

Possible values are

Show all values[+]

cn_create_reason_code

Credit note reason code.
optional, string, max chars=100

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

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. Deprecated; use the cn_create_reason_code parameter instead.
optional, enumerated string

Possible values are

Show all values[+]

cn_create_reason_code

Credit note reason code.
optional, string, max chars=100

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

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

document_number

The order's serial number.
optional, string, max chars=50

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.queuedOrder is yet to be processed by any system, these are scheduled orders created by Chargebee.awaiting_shipmentThe order has been picked up by an integration system, and synced to a shipping management platform.on_holdThe order is paused from being processed.deliveredThe order has been delivered to the customer.shippedThe order has moved from order management system to a shipping system.partially_deliveredThe order has been partially delivered to the customer.returnedThe order has been returned after delivery.

Show all values[+]

order_type

Order type.
optional, enumerated string

Possible values are

manualThe order has been created by the the user using Chargebee's legacy order management system.system_generatedThe order has been created by Chargebee automatically based on the preferences set by the user.

reference_id

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 that appear on the invoice PDF sent to the customer. Invoice notes are defined in Chargebee at various levels given by the entity_type attribute of this array. There are two more types of invoice notes that can be part of this array.

Invoice-specific note:It is the invoice_note parameter for the analogous endpoints for creating the invoice and closing a pending invoice.
General note: This note is added to all invoices of the Chargebee site. You can add/edit this note in the Chargebee admin console.

For the invoice-specific and general note, entity_type and entity_id are not present.
optional, list of note

Note attributes

entity_type

Type of entity to which the note belongs. .
enumerated string

Possible values are

couponEntity that represents a coupon.subscriptionEntity that represents a subscription of customer.customerEntity that represents a customer.plan_item_priceIndicates that this line item is based on plan Item Price.addon_item_priceIndicates that this line item is based on addon Item Price.charge_item_priceIndicates that this line item is based on charge Item Price.

note

Actual note.
string, max chars=2000

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 address attributes

first_name

The first name of the contact.
optional, string, max chars=150

last_name

The last name of the contact.
optional, string, max chars=150

email

The email address.
optional, string, max chars=70

company

The company name.
optional, string, max chars=250

phone

The 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

The name of the 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 state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
optional, string, max chars=50

state

The state/province name.
optional, string, max chars=50

country

ISO 3166 alpha-2 country code.

Note: if you enter an invalid country code, the system will output an error.

If you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, then XI (the code for United Kingdom – Northern Ireland) is available as an option.
optional, string, max chars=50

zip

Zip or postal code. The number of characters is validated according to the rules specified here.
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 address attributes

first_name

The first name of the billing contact.
optional, string, max chars=150

last_name

The last name of the billing contact.
optional, string, max chars=150

email

The email address.
optional, string, max chars=70

company

The company name.
optional, string, max chars=250

phone

The 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

The name of the city.
optional, string, max chars=50

state_code

state

State or Province.
optional, string, max chars=50

country

zip

Zip or postal code. The number of characters is validated according to the rules specified here.
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.

linked_taxes_withheld
Show attributes[+]

Details of tax_withheld against this invoice.
optional, list of linked_tax_withheld

Linked taxes withheld attributes

id

An auto-generated unique identifier for the tax withheld. The value starts with the prefix tax_wh_. For example, tax_wh_16BdDXSlbu4uV1Ee6.
string, max chars=40

amount

The amount withheld by the customer as tax from the invoice. The unit depends on the type of currency.
optional, in cents, min=1

description

The description for this tax withheld.
optional, string, max chars=65k

date

Date or time associated with the tax withheld.
optional, timestamp(UTC) in seconds

reference_number

A unique external reference number for the tax withheld. Typically, this is the reference number used by the system you are integrating the API with. Depending on your integration, this could be the reference number issued by the taxation authority to identify the customer or the specific tax transaction. .
optional, string, max chars=100

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

Notes

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

Sample Request

# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges \
     -u {site_api_key}:\
     -d customer_id="__test__KyVkkWS1xLskm8" \
     -d item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US"

copy

# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v2/invoices/create_for_charge_items_and_charges \
     -u {site_api_key}:\
     -d customer_id="__test__KyVkkWS1xLskm8" \
     -d item_prices[item_price_id][0]="ssl-charge-USD" \
     -d item_prices[unit_price][0]=2000 \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US"

Sample Response [ JSON ]

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

URL Format POST

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

customer_id

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

currency_code

The currency code (ISO 4217 format) of the invoice amount.
required if Multicurrency is enabled, string, max chars=3

invoice_note

A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
optional, string, max chars=2000

remove_general_note

Set as true to remove the general note from this invoice.
optional, boolean, default=false

po_number

Purchase Order Number for this invoice.
optional, string, max chars=100

coupon_ids[0..n]

List of Coupons to be added.
optional, list of string

authorization_transaction_id

Authorization transaction to be captured.
optional, string, max chars=40

payment_source_id

Payment source to be used for this payment.
optional, string, max chars=40

auto_collection

The customer level auto collection will be override if specified.
optional, enumerated string

Possible values are

onWhenever an invoice is created, an automatic attempt will be made to charge.offWhenever an invoice is created as payment due.

invoice_date

The document date displayed on the invoice PDF. By default, it is the date of creation of the invoice or, when Metered Billing is enabled, it can be the date of closing the invoice. Provide this value to backdate the invoice (set the invoice date to a value in the past). Backdating an invoice is done for reasons such as booking revenue for a previous date or when the non-recurring charge is effective as of a past date. taxes and line_item_taxes are computed based on the tax configuration as of this date. The date should not be more than one calendar month into the past. For example, if today is 13th January, then you cannot pass a value that is earlier than 13th December.
optional, timestamp(UTC) in seconds

token_id

Token generated by Chargebee JS representing payment method details.
optional, string, max chars=40

replace_primary_payment_source

Indicates whether the primary payment source should be replaced with this payment source. In case of Create Subscription for Customer endpoint, the default value is True. Otherwise, the default value is False.
optional, boolean, default=false

retain_payment_source

Indicates whether the payment source should be retained for the customer.
optional, boolean, default=true

shipping_address

Parameters for shipping_address
pass parameters as shipping_address[<param name>]

shipping_address[first_name]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The 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]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or postal code. The number of characters is validated according to the rules specified here.
optional, string, max chars=20

shipping_address[country]

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.

card

Parameters for card
pass parameters as card[<param name>]

card[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

card[first_name]

Cardholder's first name.
optional, string, max chars=50

card[last_name]

Cardholder's last name.
optional, string, max chars=50

card[number]

The credit card number without any format. If you are using Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500

card[expiry_month]

Card expiry month.
required if card provided, integer, min=1, max=12

card[expiry_year]

Card expiry year.
required if card provided, integer

card[cvv]

The card verification value (CVV). If you are using Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520

card[billing_addr1]

Address line 1, as available in card billing address.
optional, string, max chars=150

card[billing_addr2]

Address line 2, as available in card billing address.
optional, string, max chars=150

card[billing_city]

City, as available in card billing address.
optional, string, max chars=50

card[billing_state_code]

card[billing_state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

card[billing_zip]

Postal or Zip code, as available in card billing address.
optional, string, max chars=20

card[billing_country]

card[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

bank_account

Parameters for bank_account
pass parameters as bank_account[<param name>]

bank_account[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

bank_account[iban]

Account holder’s International Bank Account Number. For the GoCardless platform, this can be the local bank details .
optional, string, min chars=10, max chars=50

bank_account[first_name]

Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150

bank_account[last_name]

Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150

bank_account[company]

Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=250

bank_account[email]

Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
optional, string, max chars=70

bank_account[bank_name]

Name of account holder’s bank.
optional, string, max chars=100

bank_account[account_number]

Account holder’s bank account number.
optional, string, min chars=4, max chars=17

bank_account[routing_number]

Bank account routing number.
optional, string, min chars=3, max chars=9

bank_account[bank_code]

Indicates the bank code.
optional, string, max chars=20

bank_account[account_type]

For Authorize.net ACH users only. Indicates the type of account.
optional, enumerated string

Possible values are

checkingChecking Account.savingsSavings Account.business_checkingBusiness Checking Account.

bank_account[account_holder_type]

For Stripe ACH users only. Indicates the account holder type.
optional, enumerated string

Possible values are

individualIndividual.companyCompany.

bank_account[echeck_type]

For Authorize.net ACH users only. Indicates the type of eCheck.
optional, enumerated string

Possible values are

webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.

bank_account[issuing_country]

2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
optional, string, max chars=50

bank_account[swedish_identity_number]

For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
optional, string, min chars=10, max chars=12

bank_account[billing_address]

The billing address associated with the bank account. The value is a JSON object with the following keys and their values:

first_name:(string, max chars=150) The first name of the contact.
last_name:(string, max chars=150) The last name of the contact.
company_name:(string, max chars=250) The company name for the address.
line1:(string, max chars=180) The first line of the address.
line2:(string, max chars=180) The second line of the address.
country:(string) The name of the country for the address.
country_code:(string, max chars=50) The two-letter, ISO 3166 alpha-2 country code for the address.
state:(string, max chars=50) The name of the state or province for the address. When not provided, this is set automatically for US, Canada, and India.
state_code:(string, max chars=50) The ISO 3166-2 state/province code without the country prefix. This is supported for USA, Canada, and India. For instance, for Arizona (USA), set state_code as AZ (not US-AZ). For Tamil Nadu (India), set as TN (not IN-TN). For British Columbia (Canada), set as BC (not CA-BC).
city:(string, max chars=50) The city name for the address.
postal_code:(string, max chars=20) The postal or ZIP code for the address.
phone:(string, max chars=50) The contact phone number for the address.
email:(string, max chars=70) The contact email address for the address.

optional, jsonobject

payment_method

Parameters for payment_method
pass parameters as payment_method[<param name>]

payment_method[type]

The type of payment method. For more details refer Update payment method for a customer API under Customer resource.
optional, enumerated string

Possible values are

cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.

genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.

Show all values[+]

payment_method[gateway_account_id]

The gateway account in which this payment source is stored.
optional, string, max chars=50

payment_method[reference_id]

The reference id. In the case of Amazon and PayPal this will be the billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource. Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer Update payment method for a customer API under Customer resource.
optional, string, max chars=200

payment_method[tmp_token]

Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k

payment_method[issuing_country]

payment_method[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

payment_intent

Parameters for payment_intent
pass parameters as payment_intent[<param name>]

payment_intent[id]

Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150

payment_intent[gateway_account_id]

The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50

payment_intent[gw_token]

Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer 3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[reference_id]

Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k

payment_intent[additional_information]

checkout_com: While adding a new payment method using permanent token or passing raw card details to Checkout.com, document ID and country_of_residence are required to support payments through dLocal.
- payer: User related information.
  - country_of_residence: This is required since the billing country associated with the user’s payment method may not be the same as their country of residence. Hence the user’s country of residence needs to be specified. The country code should be a two-character ISO code.
  - document: Document ID is the user’s identification number based on their country.
bluesnap: While passing raw card details to BlueSnap, if fraud_session_id is added, additional validation is performed to avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - fraud_session_id: Your BlueSnap fraud session ID required to perform anti-fraud validation.
braintree: While passing raw card details to Braintree, your fraud_merchant_id and the user’s device_session_id can be added to perform additional validation and avoid fraudulent transactions.
- fraud: Fraud identification related information.
  - device_session_id: Session ID associated with the user's device.
  - fraud_merchant_id: Your merchant ID for fraud detection.

.
optional, jsonobject

item_prices

Parameters for item_prices. Multiple item_prices can be passed by specifying unique indices.
pass parameters as item_prices[<param name>][<idx:0..n>]

item_prices[item_price_id][0..n]

A unique ID for your system to identify the item price.
optional, string, max chars=100

item_prices[quantity][0..n]

Item price quantity.
optional, integer, min=1

item_prices[quantity_in_decimal][0..n]

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, string, max chars=33

item_prices[unit_price][0..n]

The price or per-unit-price of the item price. By default, it is the value set for the item_price. This is only applicable when the pricing_model of the item_price is flat_fee or per_unit. The value depends on the type of currency.
optional, in cents, min=0

item_prices[unit_price_in_decimal][0..n]

The decimal representation of the price or per-unit price of the plan. The value is in major units of the currency. Always returned when multi-decimal pricing is enabled.
optional, string, max chars=33

item_prices[date_from][0..n]

The time when the service period for the item starts.
optional, timestamp(UTC) in seconds

item_prices[date_to][0..n]

The time when the service period for the item ends.
optional, timestamp(UTC) in seconds

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[item_price_id][0..n]

The id of the item price to which this tier belongs.
optional, string, max chars=100

item_tiers[starting_unit][0..n]

The lowest value in the quantity tier.
optional, integer, min=1

item_tiers[ending_unit][0..n]

The highest value in the quantity tier.
optional, integer

item_tiers[price][0..n]

The per-unit price for the tier when the pricing_model is tiered or volume. The total cost for the item price when the pricing_model is stairstep. The value is in the minor unit of the currency.
optional, in cents, default=0, min=0

item_tiers[starting_unit_in_decimal][0..n]

The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

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. The unit depends on the type of currency.
optional, in cents, min=1

charges[amount_in_decimal][0..n]

The decimal representation of the amount for the one-time charge. Provide the value in major units of the currency. Can be provided only when multi-decimal pricing is enabled.
optional, string, max chars=33

charges[description][0..n]

Description for this charge.
optional, string, max chars=250

charges[taxable][0..n]

optional, boolean, default=true

charges[tax_profile_id][0..n]

Tax profile of the charge.
optional, string, max chars=50

charges[avalara_tax_code][0..n]

The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's AvaTax for Sales integration.
optional, string, max chars=50

charges[taxjar_product_code][0..n]

The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's TaxJar integration.
optional, string, max chars=50

charges[avalara_sale_type][0..n]

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

wholesaleTransaction is a sale to another company that will resell your product or service to another consumer.retailTransaction is a sale to an end user.consumedTransaction is for an item that is consumed directly.vendor_useTransaction is for an item that is subject to vendor use tax.

charges[avalara_transaction_type][0..n]

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

charges[avalara_service_type][0..n]

Indicates the type of service for the product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

charges[date_from][0..n]

The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds

charges[date_to][0..n]

The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds

charges[discount_amount][0..n]

The value of the discount. The format of this value depends on the kind of currency. Either this parameter or charges[discount_percentage] should be passed.
optional, in cents, min=0

charges[discount_percentage][0..n]

The percentage of the original amount that should be deducted from it. Either this parameter or charges[discount_amount] should be passed.
optional, double, min=0.01, max=100.0

notes_to_remove

Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]

notes_to_remove[entity_type][0..n]

Type of entity to which the note belongs. To remove the general note, use the remove_general_note parameter.
optional, enumerated string

Possible values are

customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Price.addon_item_priceIndicates that this line item is based on addon Item Price.charge_item_priceIndicates that this line item is based on charge Item Price.

notes_to_remove[entity_id][0..n]

Unique identifier of the note.
optional, string, max chars=100

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[percentage][0..n]

The percentage of the original amount that should be deducted from it. Only applicable when discount.type is percentage.
optional, double, min=0.01, max=100.0

discounts[amount][0..n]

The value of the discount. The format of this value depends on the kind of currency. This is only applicable when discount.type is fixed_amount.
optional, in cents, min=0

discounts[apply_on][0..n]

The amount on the invoice to which the discount is applied.
required, enumerated string

Possible values are

invoice_amountThe discount is applied to the invoice sub_total.specific_item_priceThe discount is applied to the invoice.line_item.amount that corresponds to the item price specified by item_price_id.

discounts[item_price_id][0..n]

The id of the item price in the subscription to which the discount is to be applied. Relevant only when apply_on = specific_item_price.
optional, string, max chars=100

invoice

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/v2/invoices/__demo_inv__4/stop_dunning \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/stop_dunning \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

comment

An internal comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing Hosted Page or any document such as the Invoice PDF.
optional, string, max chars=300

invoice

Resource object representing invoice.
always returned

This API is not enabled for live sites by default. Please contact support@chargebee.com to get this enabled.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}:\
     -d id="old_inv_001" \
     -d customer_id="__test__8asyKSOcTJGo2N" \
     -d subscription_id="__test__8asyKSOcTJMw2U" \
     -d date=1517490271 \
     -d total=4900 \
     -d status="payment_due" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d line_items[date_from][1]=1517490271 \
     -d line_items[date_to][1]=1519909471 \
     -d line_items[description][1]="Standard" \
     -d line_items[unit_amount][1]=4900 \
     -d line_items[quantity][1]=1 \
     -d line_items[entity_type][1]="plan_item_price" \
     -d line_items[entity_id][1]="standard-USD"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}:\
     -d id="old_inv_001" \
     -d customer_id="__test__8asyKSOcTJGo2N" \
     -d subscription_id="__test__8asyKSOcTJMw2U" \
     -d date=1517490271 \
     -d total=4900 \
     -d status="payment_due" \
     -d billing_address[first_name]="John" \
     -d billing_address[last_name]="Doe" \
     -d billing_address[line1]="PO Box 9999" \
     -d billing_address[city]="Walnut" \
     -d billing_address[state]="California" \
     -d billing_address[zip]="91789" \
     -d billing_address[country]="US" \
     -d line_items[date_from][1]=1517490271 \
     -d line_items[date_to][1]=1519909471 \
     -d line_items[description][1]="Standard" \
     -d line_items[unit_amount][1]=4900 \
     -d line_items[quantity][1]=1 \
     -d line_items[entity_type][1]="plan_item_price" \
     -d line_items[entity_id][1]="standard-USD"

Sample Response [ JSON ]

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

URL Format POST

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

id

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

The reason for exempting the invoice from tax. (Applicable only for exempted invoices.).
optional, enumerated string

Possible values are

id_exemptThe customer is from a different country than your business and they have a valid VAT number or, the customer is a business entity. (This reason is only applicable when EU VAT or UK VAT is enabled.).customer_exemptThe customer is exempted from tax.exportThe customer is from a non-taxable region or the billing address and shipping address are unavailable.

vat_number

Vat Number. Required if this invoice is VAT exempted.
optional, string, max chars=20

vat_number_prefix

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=-99, max=99

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.pendingThe invoice is yet to be closed (sent for payment collection). An invoice is generated with this status when it has line items that belong to items that are metered or when the subscription.create_pending_invoicesattribute is set to true.

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]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The 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]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or postal code. The number of characters is validated according to the rules specified here.
optional, string, max chars=20

billing_address[country]

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]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The 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]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or postal code. The number of characters is validated according to the rules specified here.
optional, string, max chars=20

shipping_address[country]

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[id][0..n]

Uniquely identifies a line_item.
optional, string, max chars=40

line_items[date_from][0..n]

Start date of this line item.
optional, timestamp(UTC) in seconds

line_items[date_to][0..n]

End date of this line item.
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 line item.
optional, in cents

line_items[quantity][0..n]

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[unit_amount_in_decimal][0..n]

line_items[quantity_in_decimal][0..n]

The decimal representation of the quantity of this line_item. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

line_items[amount_in_decimal][0..n]

line_items[entity_type][0..n]

Specifies the modelled entity this line item is based on.
optional, enumerated string, default=adhoc

Possible values are

line_items[entity_id][0..n]

The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100

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

line_items[tax5_name][0..n]

Fifth tax name.
optional, string, max chars=50

line_items[tax5_amount][0..n]

Fifth tax amount.
optional, in cents, min=0

line_items[tax6_name][0..n]

Sixth tax name.
optional, string, max chars=50

line_items[tax6_amount][0..n]

Sixth tax amount.
optional, in cents, min=0

line_items[tax7_name][0..n]

Seventh tax name.
optional, string, max chars=50

line_items[tax7_amount][0..n]

Seventh tax amount.
optional, in cents, min=0

line_items[tax8_name][0..n]

Eighth tax name.
optional, string, max chars=50

line_items[tax8_amount][0..n]

Eighth tax amount.
optional, in cents, min=0

line_items[tax9_name][0..n]

Ninth tax name.
optional, string, max chars=50

line_items[tax9_amount][0..n]

Ninth tax amount.
optional, in cents, min=0

line_items[tax10_name][0..n]

Tenth tax name.
optional, string, max chars=50

line_items[tax10_amount][0..n]

Tenth tax amount.
optional, in cents, min=0

line_item_tiers

Parameters for line_item_tiers. Multiple line_item_tiers can be passed by specifying unique indices.
pass parameters as line_item_tiers[<param name>][<idx:0..n>]

line_item_tiers[line_item_id][0..n]

Uniquely identifies a line_item.
required, string, max chars=40

line_item_tiers[starting_unit][0..n]

The lower limit of a range of units for the tier.
optional, integer, min=0

line_item_tiers[ending_unit][0..n]

The upper limit of a range of units for the tier.
optional, integer

line_item_tiers[quantity_used][0..n]

The number of units purchased in a range.
optional, integer, min=0

line_item_tiers[unit_amount][0..n]

The price of the tier if the charge model is a stairtstep pricing , or the price of each unit in the tier if the charge model is tiered/volume pricing.
optional, in cents, min=0

line_item_tiers[starting_unit_in_decimal][0..n]

line_item_tiers[ending_unit_in_decimal][0..n]

line_item_tiers[quantity_used_in_decimal][0..n]

The decimal representation of the quantity purchased from this tier. Returned when the line_item is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

line_item_tiers[unit_amount_in_decimal][0..n]

discounts

Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]

discounts[line_item_id][0..n]

The unique id of the line item that this deduction is for. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.
optional, string, max chars=40

discounts[entity_type][0..n]

The type of deduction and the amount to which it is applied.
required, enumerated string

Possible values are

item_level_couponThe deduction is due to a coupon applied to line item. The coupon id is passed as entity_id.document_level_couponThe deduction is due to a coupon applied to the invoice sub_total. The coupon id is passed as entity_id.promotional_creditsThe deduction is due to a promotional credit applied to the invoice. .item_level_discount(Beta) The deduction is due to a discount applied to a line item of the invoice. The discount id is available as the entity_id.document_level_discount(Beta) The deduction is due to a discount applied to the invoice sub_total. The discount id is available as the entity_id.

discounts[entity_id][0..n]

When the deduction is due to a coupon, then this is the id of the coupon. Is required when discounts[entity_type] is item_level_coupon or document_level_coupon.
optional, string, max chars=100

discounts[description][0..n]

Description for this deduction.
optional, string, max chars=250

discounts[amount][0..n]

The amount deducted. The format of this value depends on the kind of currency.
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=50

taxes[juris_type][0..n]

The type of tax jurisdiction.
optional, enumerated string, default=other

Possible values are

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 entity to which the note belongs. .
optional, enumerated string

Possible values are

couponEntity that represents a coupon.plan_item_priceIndicates that this line item is based on plan Item Price.addon_item_priceIndicates that this line item is based on addon Item Price.charge_item_priceIndicates that this line item is based on charge Item Price.

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=2000

invoice

Resource object representing invoice.
always returned

The API will apply payments to an invoice. On applying payments, the invoice amount due will be recalculated. The invoice' status will change to PAID or PAYMENT DUE, depending on the amount of payments applied.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_payments \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_payments \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

comment

transactions

Parameters for transactions. Multiple transactions can be passed by specifying unique indices.
pass parameters as transactions[<param name>][<idx:0..n>]

transactions[id][0..n]

Uniquely identifies the transaction. Excess payments available with the customer will be applied against this invoice if this parameter is not passed.
optional, string, max chars=40

invoice

Resource object representing invoice.
always returned

The API will apply available credits to an invoice. On applying credits, the invoice amount due will be recalculated. The invoice' status will change to PAID or PAYMENT DUE, depending on the amount of credits applied.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/apply_credits \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/apply_credits \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

comment

credit_notes

Parameters for credit_notes. Multiple credit_notes can be passed by specifying unique indices.
pass parameters as credit_notes[<param name>][<idx:0..n>]

credit_notes[id][0..n]

The Credit Note number acts as an identifier for Credit Notes and is typically generated sequentially. Available refundable credits with the customer will be applied against this invoice if this paramenter is not passed.
optional, string, max chars=50

invoice

Resource object representing invoice.
always returned

Lists all the Invoices.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode status[in]="["paid","payment_due"]" \
     --data-urlencode sort_by[asc]="date"

copy

curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=5 \
     --data-urlencode status[in]="["paid","payment_due"]" \
     --data-urlencode sort_by[asc]="date"

Sample Response [ JSON ]

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

URL Format GET

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

limit

The number of resources to be returned.
optional, integer, default=10, min=1, max=100

offset

Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset to the value of next_offset obtained in the previous iteration of the API call.
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, updated_at
Supported sort-orders : asc, desc

Example → sort_by[asc] = "date"
This will sort the result based on the 'date' attribute in ascending(earliest first) order.
optional, string filter

Filter Params

For operator usages, see the Pagination and Filtering section.

id[<operator>]

The invoice number. Acts as a identifier for invoice and typically generated sequentially.
Supported operators : is, is_not, starts_with, in, not_in

Example → id[is] = "INVOICE_654"
optional, string filter

subscription_id[<operator>]

To filter based on subscription_id.
NOTE: Not to be used if consolidated invoicing is enabled.
Supported operators : is, is_not, starts_with, is_present, in, not_in

Example → subscription_id[is] = "3bdjnDnsdQn"
optional, string filter

customer_id[<operator>]

The identifier of the customer this invoice belongs to.
Supported operators : is, is_not, starts_with, in, not_in

Example → customer_id[is] = "3bdjnDnsdQn"
optional, string filter

recurring[<operator>]

Boolean indicating whether this invoice belongs to a subscription. Possible values are : true, false
Supported operators : is

Example → recurring[is] = "true"
optional, boolean filter

status[<operator>]

Current status of this invoice. Possible values are : paid, posted, payment_due, not_paid, voided, pending.
Supported operators : is, is_not, in, not_in

Example → status[is] = "paid"
optional, enumerated string filter

price_type[<operator>]

The price type of the invoice. Possible values are : tax_exclusive, tax_inclusive.
Supported operators : is, is_not, in, not_in

Example → price_type[is] = "tax_exclusive"
optional, enumerated string filter

date[<operator>]

The document date displayed on the invoice PDF.
Supported operators : after, before, on, between

Example → date[after] = "1394532759"
optional, timestamp(UTC) in seconds filter

paid_at[<operator>]

Timestamp indicating the date & time this invoice got paid.
Supported operators : after, before, on, between

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

total[<operator>]

Invoiced amount in cents.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → total[gt] = "1000"
optional, in cents filter

amount_paid[<operator>]

Total payments received for this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_paid[lt] = "800"
optional, in cents filter

amount_adjusted[<operator>]

Total adjustments made against this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_adjusted[is] = "100"
optional, in cents filter

credits_applied[<operator>]

Total credits applied against this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → credits_applied[is] = "100"
optional, in cents filter

amount_due[<operator>]

Total amount to be collected. This includes invoice's payments in progress.
Supported operators : is, is_not, lt, lte, gt, gte, between

Example → amount_due[gte] = "200"
optional, in cents filter

dunning_status[<operator>]

Current dunning status of the invoice. Possible values are : in_progress, exhausted, stopped, success.
Supported operators : is, is_not, in, not_in, is_present

Example → dunning_status[is] = "in_progress"
optional, enumerated string filter

payment_owner[<operator>]

Payment owner of an invoice.
Supported operators : is, is_not, starts_with, in, not_in

Example → payment_owner[is] = "payment_customer"
optional, string 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. It is advisable when using this filter, to pass the sort_by input parameter as updated_at for a faster response.
Supported operators : after, before, on, between

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

channel[<operator>]

Specifies the channel where the related subscription purchase was made. Possible values are : web, app_store, play_store.
Supported operators : is, is_not, in, not_in

Example → channel[is] = "null"
optional, enumerated string filter

voided_at[<operator>]

Timestamp indicating the date & time this invoice got voided.
Supported operators : after, before, on, between

Example → voided_at[after] = "1394532759"
optional, timestamp(UTC) in seconds filter

void_reason_code[<operator>]

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 the invoice for the specified invoice id.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__17 \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__17 \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format GET

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

invoice

Resource object representing invoice.
always returned

Sample admin console URL

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

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

Sample Response [ JSON ]

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

URL Format POST

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

disposition_type

Determines the pdf should be rendered as inline or attachment in the browser.
optional, enumerated string, default=attachment

Possible values are

attachmentpdf is rendered as attachment in the browser.inlinepdf is rendered as inline in the browser.

download

Resource object representing download.
always returned

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \
     -u {site_api_key}:\
     -d amount=150 \
     -d description="$0.05 each for 30 messages"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \
     -u {site_api_key}:\
     -d amount=150 \
     -d description="$0.05 each for 30 messages"

Sample Response [ JSON ]

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

URL Format POST

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

amount

The amount to be charged. The unit depends on the type of currency.
required, in cents, min=1

description

Detailed description about this lineitem.
required, string, max chars=250

avalara_sale_type

Indicates the type of sale carried out. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, enumerated string

Possible values are

avalara_transaction_type

Indicates the type of product to be taxed. Values for this field can be taken from Avalara. This is applicable only if you use Chargebee’s AvaTax for Communications integration.
optional, integer

avalara_service_type

comment

subscription_id

Identifier of the subscription for which this charge needs to be created. Applicable for consolidated invoice.
optional, string, max chars=50

line_item

Parameters for line_item
pass parameters as line_item[<param name>]

line_item[date_from]

The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds

line_item[date_to]

The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds

invoice

Resource object representing invoice.
always returned

This endpoint is used when metered billing is enabled and it adds a charge-item price to a pending invoice. To collect the accumulated charges by closing the invoice, call Close a pending invoice.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_charge_item \
     -u {site_api_key}:\
     -d item_price[item_price_id]="ssl-charge-USD" \
     -d item_price[unit_price]=495

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_charge_item \
     -u {site_api_key}:\
     -d item_price[item_price_id]="ssl-charge-USD" \
     -d item_price[unit_price]=495

Sample Response [ JSON ]

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

URL Format POST

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

comment

subscription_id

Identifier of the subscription for which this addon needs to be created. Applicable for consolidated invoice.
optional, string, max chars=50

item_price

Parameters for item_price
pass parameters as item_price[<param name>]

item_price[item_price_id]

A unique ID for your system to identify the item price.
required, string, max chars=100

item_price[quantity]

Item price quantity.
optional, integer, min=1

item_price[quantity_in_decimal]

The decimal representation of the quantity of the item purchased. Can be provided for quantity-based item prices and only when multi-decimal pricing is enabled.
optional, string, max chars=33

item_price[unit_price]

item_price[unit_price_in_decimal]

item_price[date_from]

The time when the service period for the item starts.
optional, timestamp(UTC) in seconds

item_price[date_to]

The time when the service period for the item ends.
optional, timestamp(UTC) in seconds

item_tiers

Parameters for item_tiers. Multiple item_tiers can be passed by specifying unique indices.
pass parameters as item_tiers[<param name>][<idx:0..n>]

item_tiers[starting_unit][0..n]

The lowest value in the quantity tier.
optional, integer, min=1

item_tiers[ending_unit][0..n]

The highest value in the quantity tier.
optional, integer

item_tiers[price][0..n]

item_tiers[starting_unit_in_decimal][0..n]

The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as ending_unit_in_decimal of the next lower tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33

item_tiers[ending_unit_in_decimal][0..n]

The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the starting_unit_in_decimal of the next higher tier. Returned only when the pricing_model is tiered, volume or stairstep and multi-decimal pricing is enabled.
optional, string, max chars=33

item_tiers[price_in_decimal][0..n]

The decimal representation of the per-unit price for the tier when the pricing_model is tiered or volume. When the pricing_model is stairstep, it is the decimal representation of the total price for the item. The value is in major units of the currency. Returned when the plan is quantity-based and multi-decimal pricing is enabled.
optional, string, max chars=33

invoice

Resource object representing invoice.
always returned

Invoices for a subscription are created with a pending status when the subscription has create_pending_invoices attribute set to true. This API call finalizes a pending invoice. Any refundable_credits and excess_payments for the customer are applied to the invoice, and any payment due is collected automatically if auto_collection is on for the customer.

Automation

This operation can be automated by using a site setting. Moreover, the automation can be overridden at the customer and subscription level.

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

comment

invoice_note

A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.
optional, string, max chars=2000

remove_general_note

Set as true to remove the general note from this invoice.
optional, boolean, default=false

invoice_date

Set the invoice date. Must lie between the date when the invoice was generated and current date. Can only be passed when the site setting to allow overriding is enabled. If not passed, then the default value set at the site level is used.
optional, timestamp(UTC) in seconds

notes_to_remove

Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]

notes_to_remove[entity_type][0..n]

Type of entity to which the note belongs. To remove the general note, use the remove_general_note parameter.
optional, enumerated string

Possible values are

notes_to_remove[entity_id][0..n]

Unique identifier of the note.
optional, string, max chars=100

invoice

Resource object representing invoice.
always returned

Storing card after successful 3DS completion is not supported in this API. Use create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.

This API 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.

Pass authorization_transaction_id to capture the already blocked funds to collect the payment. If the invoice due amount is greater than the authorization the invoice status will be returned as payment_due.

Notes

The authorization transaction will not be captured if the fraud status is found as suspicious. This api will result in invalid_state_for_request error. Read more on fraud management using Stripe Radar.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__8asyKSOcU2Zm5P"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__8asyKSOcU2Zm5P"

Sample Response [ JSON ]

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

URL Format POST

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

amount

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

authorization_transaction_id

Authorization transaction to be captured.
optional, string, max chars=40

payment_source_id

Payment source to be used for this payment.
optional, string, max chars=40

comment

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
always returned

To record a offline payment for an invoice.

The invoice status will be marked as 'paid' if its amount due becomes 0 because of this recorded payment.

Note: If the payment transaction amount is more than the invoice due amount, the remaining transaction amount will be added to the customer's Excess Payments balance to be used against other invoices.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_payment \
     -u {site_api_key}:\
     -d comment="Payment received" \
     -d transaction[amount]=200 \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]=1612800517

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_payment \
     -u {site_api_key}:\
     -d comment="Payment received" \
     -d transaction[amount]=200 \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]=1612800517

Sample Response [ JSON ]

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

URL Format POST

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

comment

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

successThe transaction is successful.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

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
always returned

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

Tax Amount Withheld is enabled.
The invoice does not have a linked_taxes_withheld record associated with it already.
invoice.amount_due is greater than zero.
invoice.status is one of the following: payment_due, not_paid, or posted.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_tax_withheld \
     -u {site_api_key}:\
     -d tax_withheld[amount]=200 \
     -d tax_withheld[date]=1635080065

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/record_tax_withheld \
     -u {site_api_key}:\
     -d tax_withheld[amount]=200 \
     -d tax_withheld[date]=1635080065

Sample Response [ JSON ]

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

URL Format POST

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

tax_withheld

Parameters for tax_withheld
pass parameters as tax_withheld[<param name>]

tax_withheld[amount]

The amount withheld by the customer as tax from the invoice. This must not exceed invoice.amount_due. The unit depends on the type of currency.
required, in cents, min=1

tax_withheld[reference_number]

tax_withheld[date]

Date or time associated with this tax amount withheld. The default value is the time of invoking this operation.
optional, timestamp(UTC) in seconds

tax_withheld[description]

The description for this tax withheld.
optional, string, max chars=65k

invoice

Resource object representing invoice.
always returned

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

invoice.status is one of the following: payment_due, not_paid, or posted.
There are no adjustment_credit_notes associated with the invoice.
There are no issued_credit_notes associated with the invoice.

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

tax_withheld

Parameters for tax_withheld
pass parameters as tax_withheld[<param name>]

tax_withheld[id]

An auto-generated unique identifier for the tax withheld. The value starts with the prefix tax_wh_. For example, tax_wh_16BdDXSlbu4uV1Ee6.
required, string, max chars=40

invoice

Resource object representing invoice.
always returned

Refunds the invoice. The refund request is processed via the payment gateway originally used to charge the customer. You can choose to either make a full refund for the entire amount or make many partial refunds until you reach the total amount charged for the invoice. The API returns an error if an attempt is made to:

Refund an offline invoice. For such invoices, use the Record refund API.
Refund a fully refunded invoice.

If the refund transaction succeeds, a credit_note capturing this refund detail is created for the invoice.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__14/refund \
     -u {site_api_key}:\
     -d refund_amount=500 \
     -d credit_note[reason_code]="service_unsatisfactory"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__14/refund \
     -u {site_api_key}:\
     -d refund_amount=500 \
     -d credit_note[reason_code]="service_unsatisfactory"

Sample Response [ JSON ]

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

URL Format POST

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

refund_amount

The amount to be refunded. If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid via online transactions, and not already refunded. Note: Any linked_taxes_withheld associated with the invoice cannot be refunded via this operation.
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=2000

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[Deprecated; use the create_reason_code parameter instead].
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[+]

credit_note[create_reason_code]

Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. The codes are case-sensitive .
optional, string, max chars=100

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
always returned

credit_note

Resource object representing credit_note.
optional

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

Example

Consider an invoice with the following payments and tax withheld.

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

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

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

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

Tip

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

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__13/record_refund \
     -u {site_api_key}:\
     -d transaction[amount]=100 \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]=1517490274

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__13/record_refund \
     -u {site_api_key}:\
     -d transaction[amount]=100 \
     -d transaction[payment_method]="bank_transfer" \
     -d transaction[date]=1517490274

Sample Response [ JSON ]

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

URL Format POST

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

comment

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=2000

transaction

Parameters for transaction
pass parameters as transaction[<param name>]

transaction[amount]

The amount to be refunded (for online payments) or recorded as refunded (for offline payments). If not specified, the entire refundable amount for this invoice is refunded. The refundable amount is the total amount paid (and not already refunded) for the invoice. Note: Any linked_taxes_withheld associated with the invoice can also be recorded as refunded via this operation.
optional, in cents, min=1

transaction[payment_method]

The payment method of this transaction.
required, enumerated string, default=card

Possible values are

cashCash.checkCheck.chargebackOnly applicable for a transaction of type = refund. This value is set by Chargebee when an automated chargeback occurs. You can also set this explicitly when recording a refund.

bank_transferBank Transfer.otherPayment Methods other than the above types.

Show all values[+]

transaction[reference_number]

The reference number for this transaction. For example, the check number when payment_method = check.
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[Deprecated; use the create_reason_code parameter instead].
optional, enumerated string, default=other

Possible values are

Show all values[+]

credit_note[create_reason_code]

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
optional

credit_note

Resource object representing credit_note.
optional

This API removes payments applied to an invoice. Once payments applied are removed, the invoice’ status will return to NOT PAID or PAYMENT DUE. The removed payment will be added to customer's excess payment balance.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_payment \
     -X POST  \
     -u {site_api_key}:\
     -d transaction[id]="txn___test__8asyKSOcUWoQ6y"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/remove_payment \
     -X POST  \
     -u {site_api_key}:\
     -d transaction[id]="txn___test__8asyKSOcUWoQ6y"

Sample Response [ JSON ]

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

URL Format POST

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

transaction

Parameters for transaction
pass parameters as transaction[<param name>]

transaction[id]

Uniquely identifies the transaction.
required, string, max chars=40

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
always returned

This API removes a credit note attached to an invoice. When you remove a credit note from an invoice, the invoice’ status returns to NOT PAID.

Note: You cannot remove a credit note from an invoice if it has already been refunded.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__16/remove_credit_note \
     -X POST  \
     -u {site_api_key}:\
     -d credit_note[id]="__demo_cn__5"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__16/remove_credit_note \
     -X POST  \
     -u {site_api_key}:\
     -d credit_note[id]="__demo_cn__5"

Sample Response [ JSON ]

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

URL Format POST

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

credit_note

Parameters for credit_note
pass parameters as credit_note[<param name>]

credit_note[id]

Credit-note id.
required, string, max chars=50

invoice

Resource object representing invoice.
always returned

credit_note

Resource object representing credit_note.
always returned

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

Any promotional credits or credit notes applied to the invoice are removed.
If an invoice for the current term of a subscription is voided and the subscription is changed later with proration enabled, no prorated credits are issued.
Any usages associated with item prices in the invoice are delinked from the invoice. This is done by clearing the invoice_id field of said usages. However, before this is done, a usage PDF is generated and saved to the invoice as an attachment.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/void \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/void \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

comment

void_reason_code

invoice

Resource object representing invoice.
always returned

This API writes off an Invoice.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/write_off \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/write_off \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

comment

invoice

Resource object representing invoice.
always returned

credit_note

Resource object representing credit_note.
always returned

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

Caution

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

Any promotional credits or credit notes applied to the invoice are removed.
If an invoice for the current term of a subscription is deleted and the subscription is changed later with proration enabled, no prorated credits are issued.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/delete \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/delete \
     -X POST  \
     -u {site_api_key}:

Sample Response [ JSON ]

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

URL Format POST

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

comment

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

claim_credits

Indicates whether to put prorated credits back to the subscription or ignore while deleting the invoice.
optional, boolean, default=false

invoice

Resource object representing invoice.
always returned

This API allows you to update the invoice Billing/Shipping address, VAT and PO number. During this operation if Billing Info (Billing Address, vat_number), Shipping info and PO number are not already present in the system the data will be added. If data is already present, the existing values will be replaced.If info is present in the system, but not passed as part of the request, the info will not be removed from the system.

Note: Incase, tax is already applied will now vary due to address change, you cannot update the address. You cannot update the VAT Number if the billing address is not present in the API request.This will update the invoice only, it won't change the corresponding customer/subscription details.

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

vat_number

VAT/ Tax registration number of the customer. Learn more.
optional, string, max chars=20

vat_number_prefix

po_number

Purchase Order Number for this invoice.
optional, string, max chars=100

comment

billing_address

Parameters for billing_address
pass parameters as billing_address[<param name>]

billing_address[first_name]

The first name of the billing contact.
optional, string, max chars=150

billing_address[last_name]

The last name of the billing contact.
optional, string, max chars=150

billing_address[email]

The email address.
optional, string, max chars=70

billing_address[company]

The company name.
optional, string, max chars=250

billing_address[phone]

The 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]

The name of the city.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

billing_address[zip]

Zip or postal code. The number of characters is validated according to the rules specified here.
optional, string, max chars=20

billing_address[country]

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]

The first name of the contact.
optional, string, max chars=150

shipping_address[last_name]

The last name of the contact.
optional, string, max chars=150

shipping_address[email]

The email address.
optional, string, max chars=70

shipping_address[company]

The company name.
optional, string, max chars=250

shipping_address[phone]

The 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]

The name of the city.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code is provided.
optional, string, max chars=50

shipping_address[zip]

Zip or postal code. The number of characters is validated according to the rules specified here.
optional, string, max chars=20

shipping_address[country]

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.

invoice

Resource object representing invoice.
always returned

Auto-collection

Sample invoice [ JSON ]

API Index URL GET

Invoice attributes

Create invoice for items and one-time charges¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Stop dunning for invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Import invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Apply payments for an invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Apply credits for an invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

List invoices¶

Sample Response [ JSON ]

URL Format GET

Input Parameters

Filter Params

For operator usages, see the Pagination and Filtering section.

Returns

Retrieve an invoice¶

Sample Response [ JSON ]

URL Format GET

Returns

Sample admin console URL

Retrieve Invoice as PDF¶

Related Tutorial

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add one-time charge to a pending invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add a charge-item to a pending invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Close a pending invoice¶

Automation

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Collect payment for an invoice¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Record an invoice payment¶

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Record tax withheld for an invoice¶

Sample Response [ JSON ]

URL Format POST

Input Parameters