Invoices

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

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

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

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

Sample invoice [ JSON ]

{
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 0,
    "amount_paid": 4000,
    "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__5SK0bLNFRFuFP0gjy",
    "date": 1517507499,
    "deleted": false,
    "due_date": 1517507499,
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__13",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [{
        "amount": 4000,
        "date_from": 1517507499,
        "date_to": 1517507499,
        "description": "non_recurring_addon",
        "discount_amount": 0,
        "entity_id": "non_recurring_addon",
        "entity_type": "addon",
        "id": "li___test__5SK0bLNFRFuFP1vk5",
        "is_taxed": false,
        "item_level_discount_amount": 0,
        "object": "line_item",
        "pricing_model": "per_unit",
        "quantity": 2,
        "tax_amount": 0,
        "tax_exempt_reason": "tax_not_configured",
        "unit_amount": 2000
    }],
    "linked_orders": [],
    "linked_payments": [{
        "applied_amount": 4000,
        "applied_at": 1517507499,
        "txn_amount": 4000,
        "txn_date": 1517507499,
        "txn_id": "txn___test__5SK0bLNFRFuFP2Ck6",
        "txn_status": "success"
    }],
    "net_term_days": 0,
    "new_sales_amount": 4000,
    "object": "invoice",
    "paid_at": 1517507499,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507499000,
    "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": 4000,
    "tax": 0,
    "term_finalized": true,
    "total": 4000,
    "updated_at": 1517507499,
    "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.pendingIndicates the invoice is not closed yet. New line items can be added when the invoice is in this state.

vat_number

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

price_type

The price type of the invoice.
enumerated string, default=tax_exclusive

Possible values are

tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.

date

Closing date of the invoice. Typically this is the date on which invoice is generated. If you have "wait & notify to send invoices enabled for usage based billing" this will not be the same as date on which invoice was actually sent to customer.
optional, timestamp(UTC) in seconds

due_date

Due date of the invoice.
optional, timestamp(UTC) in seconds

net_term_days

Number of days within which the invoice has to be paid.
optional, integer, default=0

currency_code

The currency code (ISO 4217 format) for the invoice.
string, max chars=3

total

Invoiced amount in cents.
optional, in cents, min=0

amount_paid

Total payments received for this invoice.
optional, in cents, min=0

amount_adjusted

Total adjustments made against this invoice.
optional, in cents, default=0, min=0

write_off_amount

Amount written off against this invoice.
optional, in cents, default=0, min=0

credits_applied

Total credits applied against this invoice.
optional, in cents, default=0, min=0

amount_due

Total amount to be collected. 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. This attribute will be present only if the resource has been updated after 2016-09-28.
optional, long

updated_at

Timestamp indicating when this invoice was last updated. This attribute will be present only if the resource has been updated after 2016-09-28.
Note: This value does not change when the following attributes are changed: next_retry_at, dunning_status, has_advance_charges.
optional, timestamp(UTC) in seconds

sub_total

The invoice sub-total.
in cents, min=0

tax

Total tax amount for this invoice.
in cents, min=0

first_invoice

Boolean indicating the first invoice raised for the subscription. In the case of a non-recurring invoice, it indicates the first invoice raised for the customer.
optional, boolean

has_advance_charges

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

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

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

deleted

Indicates that this resource has been deleted.
boolean

line_items
Show attributes[+]

The list of line items for this invoice.
optional, list of line_item

Line item attributes

id

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

subscription_id

A unique identifier for the subscription this lineitem belongs to.
optional, string, max chars=3

date_from

Start date of this lineitem.
timestamp(UTC) in seconds

date_to

End date of this lineitem.
timestamp(UTC) in seconds

unit_amount

Unit amount of the lineitem.
in cents

quantity

Quantity of the recurring item which is represented by this lineitem.
optional, integer, default=1

amount

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

pricing_model

Charges a single price for the plan/addon.
optional, enumerated string

Possible values are

flat_feeCharge a single price on recurring basis.per_unitCharge the price for each unit of the plan for the subscription on recurring basis.tieredCharges a different per unit price for the quantity purchased from every tier.volumeCharges the per unit price for the total quantity purchased based on the tier under which it falls.stairstepCharges a price for a range.

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

discount_amount

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

item_level_discount_amount

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

description

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

entity_type

Specifies the modelled entity (plan / addon etc) this lineitem is based on.
enumerated string

Possible values are

plan_setupIndicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id.planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.

tax_exempt_reason

The reason or category due to which the line item price/amount is excluded from taxable amount.
optional, enumerated string

Possible values are

tax_not_configuredIf tax is not enabled for the site.region_non_taxableIf the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdiction.exportIf the Merchant is not registered for Tax in this region, taxes will not be applied.customer_exemptIf the Customer is marked as Tax exempt.product_exemptIf the Plan or Addon is marked as Tax exempt.zero_ratedIf the rate of tax is 0% and no Sales/ GST tax is collectable for that line item.reverse_chargeIf the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU only.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 lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100

discounts
Show attributes[+]

The list of discounts applied for this invoice.
optional, list of discount

Discount attributes

amount

Discount amount.
in cents, min=0

description

Detailed description of this discount line item.
optional, string, max chars=250

entity_type

Type of this Discount lineitem.
enumerated string

Possible values are

item_level_couponRepresents the 'Item' level coupons applied to this invoice. Further the 'entity_id' attribute specifies the coupon id this discount is based on.document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'entity_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case.prorated_creditsRepresents the credit adjustment items in invoice. The 'entity_id' attribute will be null in this case.

entity_id

The identifier of the modelled entity this lineitem is bases on. Will be null for 'Prorated Credits' & 'Promotional Credits'.
optional, string, max chars=100

line_item_discounts
Show attributes[+]

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

Line item discount attributes

line_item_id

The unique reference id of the line item for which the discount is applicable.
string, max chars=50

discount_type

Type of this discount line item.
enumerated string

Possible values are

item_level_couponRepresents the 'Item' level coupons applied to this invoice. Further the 'coupon_id' attribute specifies the coupon id this discount is based on.document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'coupon_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'coupon_id' attribute will be null in this case.prorated_creditsRepresents the credit adjustment items in invoice. The 'coupon_id' attribute will be null in this case.

coupon_id

Coupon id.
optional, string, max chars=50

discount_amount

Discount amount.
in cents, min=0

taxes
Show attributes[+]

The list of taxes applied for this invoice.
optional, list of tax

Tax attributes

name

The name of the tax applied. E.g. GST.
string, max chars=100

amount

The tax amount.
in cents, min=0

description

Description of the tax item.
optional, string, max chars=250

line_item_taxes
Show attributes[+]

The list of taxes applied on line items.
optional, list of line_item_tax

Line item tax attributes

line_item_id

The unique reference id of the line item for which the tax is applicable.
optional, string, max chars=40

tax_name

The name of the tax applied.
string, max chars=100

tax_rate

The rate of tax used to calculate tax amount.
double, default=0.0, min=0.0, max=100.0

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

line_item_tiers
Show attributes[+]

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

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

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

linked_payments
Show attributes[+]

The list of transactions for this invoice.
optional, list of invoice_transaction

Linked payment attributes

txn_id

Uniquely identifies the transaction.
string, max chars=40

applied_amount

The transaction amount applied to this invoice.
in cents, min=0

applied_at

Timestamp at which the transaction is applied.
timestamp(UTC) in seconds

txn_status

The status of this transaction.
optional, enumerated string

Possible values are

in_progressTransaction is being processed via ACH.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

applied_credits
Show attributes[+]

Refundable Credits applied on this invoice.
optional, list of applied_credit

Applied credit attributes

cn_id

string, max chars=50

applied_amount

in cents, min=0

applied_at

timestamp(UTC) in seconds

cn_reason_code

Credit note reason code.
enumerated string, default=product_unsatisfactory

Possible values are

write_offThis reason will be set automatically for the Credit Notes created during invoice Write Off operation.subscription_changeThis reason will be set automatically for Credit Notes created during Change Subscription operation when proration is enabled.subscription_cancellationThis reason will be set automatically for Credit Notes created during cancel subscription operation.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_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.
enumerated string, default=product_unsatisfactory

Possible values are

Show all values[+]

cn_date

Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds

cn_total

Total amount of the credit note.
optional, in cents, default=0, min=0

cn_status

Credit note status.
enumerated string

Possible values are

issued_credit_notes
Show attributes[+]

Credit notes issued for this invoice.
optional, list of created_credit_note

Issued credit note attributes

cn_id

Credit-note id.
string, max chars=50

cn_reason_code

Credit note reason code.
enumerated string, default=product_unsatisfactory

Possible values are

Show all values[+]

cn_date

Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds

cn_total

Total amount of the credit note.
optional, in cents, default=0, min=0

cn_status

Credit note status.
enumerated string

Possible values are

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 associated with the invoice. If entity_type & entity_id are not present, then it is general notes (i.e Notes input provided under "Customize Invoice" action in Chargebee web interface).
optional, list of note

Note attributes

entity_type

Type of the entity for which this invoice notes belongs.
enumerated string

Possible values are

planEntity that represents a plan.addonEntity that represents an addon.couponEntity that represents a coupon.subscriptionEntity that represents a subscription of customer.customerEntity that represents a customer.

note

Actual note.
string, max chars=1000

entity_id

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

shipping_address
Show attributes[+]

Shipping address for the invoice.
optional, shipping_address

Shipping addres attributes

first_name

First name.
optional, string, max chars=150

last_name

Last name.
optional, string, max chars=150

email

Email.
optional, string, max chars=70

company

Company name.
optional, string, max chars=250

phone

Phone number.
optional, string, max chars=50

line1

Address line 1.
optional, string, max chars=180

line2

Address line 2.
optional, string, max chars=150

line3

Address line 3.
optional, string, max chars=150

city

City.
optional, string, max chars=50

state_code

The ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set the state_code as AZ (not US-AZ). or, for Tamil Nadu (India), set the state_code as TN (not IN-TN). or, for British Columbia (Canada), set the state_code as BC (not CA-BC).
Note: If the 'state_code' is specified, the 'state' attribute should not be provided as Chargebee will set the value automatically (for US, Canada, India).
optional, string, max chars=50

state

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

country

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

zip

Zip or Postal code.
optional, string, max chars=20

validation_status

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

billing_address
Show attributes[+]

Billing address for the invoice.
optional, billing_address

Billing addres attributes

first_name

First name.
optional, string, max chars=150

last_name

Last name.
optional, string, max chars=150

email

Email.
optional, string, max chars=70

company

Company name.
optional, string, max chars=250

phone

Phone number.
optional, string, max chars=50

line1

Address line 1.
optional, string, max chars=150

line2

Address line 2.
optional, string, max chars=150

line3

Address line 3.
optional, string, max chars=150

city

City.
optional, string, max chars=50

state_code

state

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

country

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

zip

Zip or Postal code.
optional, string, max chars=20

validation_status

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

Creates a one-off invoice for multiple 'Non Recurring' add-on & ad-hoc charges for a customer.

If the 'auto collection' has been turned 'on' for that customer then payment will be immediately collected using the payment method associated with the customer. The invoice will be generated upon successful collection of payments.

However, if the 'auto collection' is turned 'off', no collection attempt will be made and the invoice will be generated in the “Payment Due” status. Customer level auto collection property can be overridden by passing the auto_collection parameter.

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

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

You can pass the authorization_transaction_id to capture the already blocked funds to collect the payment. The excess payments will be applied to the invoice followed by the captured authorization payment.

If capturing authorization fails, the invoice will not be created. The invoice creation can be retried by passing the auto-collection as OFF. If the invoice due amount is greater than the authorization & excess payment amount collectively, the invoice status will be returned as payment_due. Collect payment for invoice API can be used to collect the remaining amount 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.
Passing auto_collection will not update the customer level property.
Available Credits and Excess Payments will automatically be applied to this invoice.

Sample Request

# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}:\
     -d customer_id="__test__5SK0bLNFRFuFP0gjy" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[unit_price][0]=2000 \
     -d addons[quantity][0]=2 \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US"

copy

# creates an invoice for 'Non Recurring' addon for a customer.
curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}:\
     -d customer_id="__test__5SK0bLNFRFuFP0gjy" \
     -d addons[id][0]="non_recurring_addon" \
     -d addons[unit_price][0]=2000 \
     -d addons[quantity][0]=2 \
     -d shipping_address[first_name]="John" \
     -d shipping_address[last_name]="Mathew" \
     -d shipping_address[city]="Walnut" \
     -d shipping_address[state]="California" \
     -d shipping_address[zip]="91789" \
     -d shipping_address[country]="US"

# creates an invoice for a one-time charge.
curl  https://{site}.chargebee.com/api/v2/invoices \
     -u {site_api_key}:\
     -d customer_id="__test__5SK0bLNFRFuFP3dkA" \
     -d charges[amount][0]=1000 \
     -d charges[description][0]="Support Charge"

Sample Response [ JSON ]

{"invoice": {
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 0,
    "amount_paid": 4000,
    "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__5SK0bLNFRFuFP0gjy",
    "date": 1517507499,
    "deleted": false,
    "due_date": 1517507499,
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__13",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 4000,
            "date_from": 1517507499,
            "date_to": 1517507499,
            "description": "non_recurring_addon",
            "discount_amount": 0,
            "entity_id": "non_recurring_addon",
            "entity_type": "addon",
            "id": "li___test__5SK0bLNFRFuFP1vk5",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 2,
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 2000
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 4000,
            "applied_at": 1517507499,
            "txn_amount": 4000,
            "txn_date": 1517507499,
            "txn_id": "txn___test__5SK0bLNFRFuFP2Ck6",
            "txn_status": "success"
        },
        {..}
    ],
    "net_term_days": 0,
    "new_sales_amount": 4000,
    "object": "invoice",
    "paid_at": 1517507499,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507499000,
    "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": 4000,
    "tax": 0,
    "term_finalized": true,
    "total": 4000,
    "updated_at": 1517507499,
    "write_off_amount": 0
}}

{"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__5SK0bLNFRFuFP3dkA",
    "date": 1517507499,
    "deleted": false,
    "due_date": 1517507499,
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__14",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 1000,
            "date_from": 1517507499,
            "date_to": 1517507499,
            "description": "Support Charge",
            "discount_amount": 0,
            "entity_type": "adhoc",
            "id": "li___test__5SK0bLNFRFuFP51kH",
            "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": 1000
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 1000,
            "applied_at": 1517507499,
            "txn_amount": 1000,
            "txn_date": 1517507499,
            "txn_id": "txn___test__5SK0bLNFRFuFP5NkI",
            "txn_status": "success"
        },
        {..}
    ],
    "net_term_days": 0,
    "new_sales_amount": 1000,
    "object": "invoice",
    "paid_at": 1517507499,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507499000,
    "round_off_amount": 0,
    "status": "paid",
    "sub_total": 1000,
    "tax": 0,
    "term_finalized": true,
    "total": 1000,
    "updated_at": 1517507499,
    "write_off_amount": 0
}}

URL Format POST

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

customer_id

Identifier of the customer for which this invoice needs to be created.
required, string, max chars=50

currency_code

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

coupon

The 'One Time' coupon to be applied.
optional, string, max chars=50

po_number

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

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.

shipping_address

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

shipping_address[first_name]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

Phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

addons

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

addons[id][0..n]

Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100

addons[quantity][0..n]

Addon quantity. Applicable only for the quantity based addons. Should be passed with the same index as that of associated addon id.
optional, integer, default=1, min=1

addons[unit_price][0..n]

Amount that will override the Addon's default price. The Plan's billing frequency will not be considered for overriding. E.g. If the Plan's billing frequency is every 3 months, and if the price override amount is $10, $10 will be used, and not $30 (i.e $10*3).
optional, in cents, min=0

charges

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

charges[amount][0..n]

The amount to be charged.
optional, in cents, min=1

charges[description][0..n]

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

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

invoice

Resource object representing invoice.
always returned

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

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

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

Notes

Available Credits and Excess Payments will automatically be applied to this invoice.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/charge \
     -u {site_api_key}:\
     -d subscription_id="__test__5SK0bLNFRFuFPBqkg" \
     -d amount=1000 \
     -d description="Support Charge"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/charge \
     -u {site_api_key}:\
     -d subscription_id="__test__5SK0bLNFRFuFPBqkg" \
     -d amount=1000 \
     -d description="Support Charge"

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",
    "credits_applied": 0,
    "currency_code": "USD",
    "customer_id": "__test__5SK0bLNFRFuFPBqkg",
    "date": 1517507499,
    "deleted": false,
    "due_date": 1517507499,
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__18",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 1000,
            "date_from": 1517507499,
            "date_to": 1517507499,
            "description": "Support Charge",
            "discount_amount": 0,
            "entity_type": "adhoc",
            "id": "li___test__5SK0bLNFRFuFPERkv",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "flat_fee",
            "quantity": 1,
            "subscription_id": "__test__5SK0bLNFRFuFPBqkg",
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 1000
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 1000,
            "applied_at": 1517507500,
            "txn_amount": 1000,
            "txn_date": 1517507500,
            "txn_id": "txn___test__5SK0bLNFRFuFPEqkw",
            "txn_status": "success"
        },
        {..}
    ],
    "net_term_days": 0,
    "new_sales_amount": 1000,
    "object": "invoice",
    "paid_at": 1517507500,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507500000,
    "round_off_amount": 0,
    "status": "paid",
    "sub_total": 1000,
    "subscription_id": "__test__5SK0bLNFRFuFPBqkg",
    "tax": 0,
    "term_finalized": true,
    "total": 1000,
    "updated_at": 1517507500,
    "write_off_amount": 0
}}

URL Format POST

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

customer_id

Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
optional, string, max chars=50

subscription_id

Identifier of the subscription for which this invoice needs to be created. Should be specified if 'customer_id' is not specified.(not applicable for consolidated invoice).
optional, string, max chars=50

currency_code

The currency code (ISO 4217 format) of the invoice amount. Applicable only while creating an invoice for a customer (by specifying customer_id).
required if Multicurrency is enabled, string, max chars=3

amount

The amount to be charged.
required, in cents, min=1

description

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

coupon

The 'One Time' coupon to be applied. Supported only if this one-off invoice is associated with a Customer(i.e customer_id is specified).
optional, string, max chars=50

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

po_number

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

payment_source_id

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

invoice

Resource object representing invoice.
always returned

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

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

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

Notes

Available Credits and Excess Payments will automatically be applied to this invoice.

Sample Request

curl  https://{site}.chargebee.com/api/v2/invoices/charge_addon \
     -u {site_api_key}:\
     -d subscription_id="__test__5SK0bLNFRFuFP6tkM" \
     -d addon_id="non_recurring_addon" \
     -d addon_unit_price=2000 \
     -d addon_quantity=2

copy

curl  https://{site}.chargebee.com/api/v2/invoices/charge_addon \
     -u {site_api_key}:\
     -d subscription_id="__test__5SK0bLNFRFuFP6tkM" \
     -d addon_id="non_recurring_addon" \
     -d addon_unit_price=2000 \
     -d addon_quantity=2

Sample Response [ JSON ]

{"invoice": {
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 0,
    "amount_paid": 4000,
    "amount_to_collect": 0,
    "applied_credits": [],
    "base_currency_code": "USD",
    "credits_applied": 0,
    "currency_code": "USD",
    "customer_id": "__test__5SK0bLNFRFuFP6tkM",
    "date": 1517507499,
    "deleted": false,
    "due_date": 1517507499,
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__16",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 4000,
            "date_from": 1517507499,
            "date_to": 1517507499,
            "description": "non_recurring_addon",
            "discount_amount": 0,
            "entity_id": "non_recurring_addon",
            "entity_type": "addon",
            "id": "li___test__5SK0bLNFRFuFP9Wkb",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 2,
            "subscription_id": "__test__5SK0bLNFRFuFP6tkM",
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 2000
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 4000,
            "applied_at": 1517507499,
            "txn_amount": 4000,
            "txn_date": 1517507499,
            "txn_id": "txn___test__5SK0bLNFRFuFP9tkc",
            "txn_status": "success"
        },
        {..}
    ],
    "net_term_days": 0,
    "new_sales_amount": 4000,
    "object": "invoice",
    "paid_at": 1517507499,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507499000,
    "round_off_amount": 0,
    "status": "paid",
    "sub_total": 4000,
    "subscription_id": "__test__5SK0bLNFRFuFP6tkM",
    "tax": 0,
    "term_finalized": true,
    "total": 4000,
    "updated_at": 1517507499,
    "write_off_amount": 0
}}

URL Format POST

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

customer_id

Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.
optional, string, max chars=50

subscription_id

Identifier of the subscription for which this invoice(not applicable for consolidated invoice) needs to be created. Should be specified if 'customer_id' is not specified.
optional, string, max chars=50

addon_id

The ID of the non-recurring addon to be charged.
required, string, max chars=100

addon_quantity

The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1

addon_unit_price

Amount that will override the Addon's default price.
optional, in cents, min=0

coupon

The 'One Time' coupon to be applied. Supported only if this one-off invoice is associated with a Customer(i.e customer_id is specified).
optional, string, max chars=50

po_number

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

payment_source_id

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

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

copy

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

Sample Response [ JSON ]

{"invoice": {
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 895,
    "amount_paid": 0,
    "amount_to_collect": 895,
    "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__KyVnTyRFuFS9H8I",
    "date": 1547927511,
    "deleted": false,
    "due_date": 1547927511,
    "dunning_status": "stopped",
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "__demo_inv__37",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 895,
            "date_from": 1547927511,
            "date_to": 1550605911,
            "description": "No Trial",
            "discount_amount": 0,
            "entity_id": "no_trial",
            "entity_type": "plan",
            "id": "li___test__KyVnTyRFuFSHv8l",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__KyVnTyRFuFS9H8I",
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 895
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 895,
            "applied_at": 1547927512,
            "txn_amount": 895,
            "txn_date": 1547927512,
            "txn_id": "txn___test__KyVnTyRFuFSIG8m",
            "txn_status": "failure"
        },
        {..}
    ],
    "net_term_days": 0,
    "object": "invoice",
    "price_type": "tax_exclusive",
    "recurring": true,
    "resource_version": 1517507512000,
    "round_off_amount": 0,
    "status": "not_paid",
    "sub_total": 895,
    "subscription_id": "__test__KyVnTyRFuFS9H8I",
    "tax": 0,
    "term_finalized": true,
    "total": 895,
    "updated_at": 1517507512,
    "write_off_amount": 0
}}

URL Format POST

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

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__5SK0bLNFRFuFPNolB" \
     -d subscription_id="__test__5SK0bLNFRFuFPNolB" \
     -d date=1517507500 \
     -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]=1517507500 \
     -d line_items[date_to][1]=1519926700 \
     -d line_items[description][1]="Support Charge" \
     -d line_items[unit_amount][1]=4900 \
     -d line_items[quantity][1]=1 \
     -d line_items[entity_type][1]="plan" \
     -d line_items[entity_id][1]="plan1"

copy

curl  https://{site}.chargebee.com/api/v2/invoices/import_invoice \
     -u {site_api_key}:\
     -d id="old_inv_001" \
     -d customer_id="__test__5SK0bLNFRFuFPNolB" \
     -d subscription_id="__test__5SK0bLNFRFuFPNolB" \
     -d date=1517507500 \
     -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]=1517507500 \
     -d line_items[date_to][1]=1519926700 \
     -d line_items[description][1]="Support Charge" \
     -d line_items[unit_amount][1]=4900 \
     -d line_items[quantity][1]=1 \
     -d line_items[entity_type][1]="plan" \
     -d line_items[entity_id][1]="plan1"

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__5SK0bLNFRFuFPNolB",
    "date": 1517507500,
    "deleted": false,
    "due_date": 1517507500,
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "old_inv_001",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 4900,
            "date_from": 1517507500,
            "date_to": 1519926700,
            "description": "Support Charge",
            "discount_amount": 0,
            "entity_id": "plan1",
            "entity_type": "plan",
            "id": "li___test__5SK0bLNFRFuFPRblP",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__5SK0bLNFRFuFPNolB",
            "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": 1517507500000,
    "round_off_amount": 0,
    "status": "payment_due",
    "sub_total": 4900,
    "subscription_id": "__test__5SK0bLNFRFuFPNolB",
    "tax": 0,
    "term_finalized": true,
    "total": 4900,
    "updated_at": 1517507500,
    "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

Applicbale for exempted (VAT exemption, Customer exemption etc) invoices.
optional, enumerated string

Possible values are

id_exemptVat Exempt.customer_exemptCustomer exemption from tax.exportTax exempted, if the customer is from non taxable region.

vat_number

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

date

Date when invoice raised.
required, timestamp(UTC) in seconds

total

Invoice total amount.
required, in cents, min=0

round_off

Round off amount.
optional, in cents, min=-99, max=99

status

Current status of this invoice.
optional, enumerated string, default=payment_due

Possible values are

due_date

Invoice Due Date.
optional, timestamp(UTC) in seconds

net_term_days

Invoice net term days.
optional, integer, default=0

use_for_proration

If the invoice falls within the subscription current term will be used for proration.
optional, boolean, default=false

billing_address

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

billing_address[first_name]

First name.
optional, string, max chars=150

billing_address[last_name]

Last name.
optional, string, max chars=150

billing_address[email]

Email.
optional, string, max chars=70

billing_address[company]

Company name.
optional, string, max chars=250

billing_address[phone]

Phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

City.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

shipping_address

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

shipping_address[first_name]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

Phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

line_items

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

line_items[id][0..n]

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

line_items[date_from][0..n]

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

line_items[date_to][0..n]

End date of this lineitem.
optional, timestamp(UTC) in seconds

line_items[description][0..n]

Description for this line item.
required, string, max chars=250

line_items[unit_amount][0..n]

Unit amount of the lineitem.
optional, in cents

line_items[quantity][0..n]

Quantity of the recurring item which is represented by this lineitem.
optional, integer, default=1

line_items[amount][0..n]

Total amount of this lineitem. Not required if the line_items[unit_amount] param is passed.
optional, in cents

line_items[entity_type][0..n]

Specifies the modelled entity (plan / addon etc) this lineitem is based on.
optional, enumerated string, default=adhoc

Possible values are

line_items[entity_id][0..n]

The identifier of the modelled entity this lineitem is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=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_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.
required, integer, min=1

line_item_tiers[ending_unit][0..n]

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

line_item_tiers[quantity_used][0..n]

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

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.
required, in cents, min=0

discounts

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

discounts[entity_type][0..n]

Type of this Discount lineitem.
required, enumerated string

Possible values are

document_level_couponRepresents the 'Document' level coupons applied to this document. Further the 'entity_id' attribute specifies the coupon id this discount is based on.promotional_creditsRepresents the Promotional Credits item in invoice. The 'entity_id' attribute will be null in this case.

discounts[entity_id][0..n]

Coupon Id. Required, if the entity type is document level coupon.
optional, string, max chars=100

discounts[description][0..n]

Description of discount.
optional, string, max chars=250

discounts[amount][0..n]

Discount amount.
required, in cents, min=0

taxes

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

taxes[name][0..n]

The name of the tax applied.
required, string, max chars=100

taxes[rate][0..n]

The rate of tax used to calculate tax amount.
required, double, default=0.0, min=0.0, max=100.0

taxes[amount][0..n]

Total tax amount charged for this invoice.
optional, in cents, min=0

taxes[description][0..n]

Description of tax.
optional, string, max chars=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 the entity for which this invoice notes belongs.
optional, enumerated string

Possible values are

planEntity that represents a plan.addonEntity that represents an addon.couponEntity that represents a coupon.

notes[entity_id][0..n]

Id of the mentioned entity type.
optional, string, max chars=50

notes[note][0..n]

Actual note.
optional, string, max chars=1000

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__8/apply_payments \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{"invoice": {
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 0,
    "amount_paid": 895,
    "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__KyVnTyRFuFODb4w",
    "date": 1547927496,
    "deleted": false,
    "due_date": 1547927496,
    "dunning_status": "stopped",
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "__demo_inv__8",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 895,
            "date_from": 1547927496,
            "date_to": 1550605896,
            "description": "No Trial",
            "discount_amount": 0,
            "entity_id": "no_trial",
            "entity_type": "plan",
            "id": "li___test__KyVnTyRFuFONM5P",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__KyVnTyRFuFODb4w",
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 895
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 895,
            "applied_at": 1517507497,
            "txn_amount": 895,
            "txn_date": 1517507497,
            "txn_id": "txn___test__5SK0bLNFRFuFOVnjR",
            "txn_status": "success"
        },
        {..}
    ],
    "net_term_days": 0,
    "object": "invoice",
    "paid_at": 1517507497,
    "price_type": "tax_exclusive",
    "recurring": true,
    "resource_version": 1517507497000,
    "round_off_amount": 0,
    "status": "paid",
    "sub_total": 895,
    "subscription_id": "__test__KyVnTyRFuFODb4w",
    "tax": 0,
    "term_finalized": true,
    "total": 895,
    "updated_at": 1517507497,
    "write_off_amount": 0
}}

URL Format POST

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

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__6/apply_credits \
     -X POST  \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__6/apply_credits \
     -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": [
        {
            "applied_amount": 1000,
            "applied_at": 1517507495,
            "cn_date": 1517507495,
            "cn_id": "__demo_cn__3",
            "cn_reason_code": "service_unsatisfactory",
            "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__5SK0bLNFRFuFO6Yis",
    "date": 1517507495,
    "deleted": false,
    "due_date": 1517507495,
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "__demo_inv__6",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 2000,
            "date_from": 1517507495,
            "date_to": 1517507495,
            "description": "Service Charge",
            "discount_amount": 0,
            "entity_type": "adhoc",
            "id": "li___test__5SK0bLNFRFuFOALjA",
            "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": [],
    "net_term_days": 0,
    "object": "invoice",
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507496000,
    "round_off_amount": 0,
    "status": "not_paid",
    "sub_total": 2000,
    "tax": 0,
    "term_finalized": true,
    "total": 2000,
    "updated_at": 1517507496,
    "write_off_amount": 0
}}

URL Format POST

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

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=3 \
     --data-urlencode status[in]="["paid","not_paid"]" \
     --data-urlencode sort_by[asc]="date"

copy

curl  https://{site}.chargebee.com/api/v2/invoices \
     -G  \
     -u {site_api_key}:\
     --data-urlencode limit=3 \
     --data-urlencode status[in]="["paid","not_paid"]" \
     --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__5SK0bLNFRFuFO6Yis",
            "date": 1517507495,
            "deleted": false,
            "due_date": 1517507495,
            "exchange_rate": 1,
            "first_invoice": true,
            "has_advance_charges": false,
            "id": "__demo_inv__5",
            "is_gifted": false,
            "issued_credit_notes": [
                {
                    "cn_date": 1517507495,
                    "cn_id": "__demo_cn__3",
                    "cn_reason_code": "service_unsatisfactory",
                    "cn_status": "refunded",
                    "cn_total": 1000
                },
                {..}
            ],
            "line_items": [
                {
                    "amount": 1000,
                    "date_from": 1517507495,
                    "date_to": 1517507495,
                    "description": "Support Charge",
                    "discount_amount": 0,
                    "entity_type": "adhoc",
                    "id": "li___test__5SK0bLNFRFuFO7ciz",
                    "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": 1000
                },
                {..}
            ],
            "linked_orders": [],
            "linked_payments": [
                {
                    "applied_amount": 1000,
                    "applied_at": 1517507495,
                    "txn_amount": 1000,
                    "txn_date": 1517507495,
                    "txn_id": "txn___test__5SK0bLNFRFuFO7tj0",
                    "txn_status": "success"
                },
                {..}
            ],
            "net_term_days": 0,
            "new_sales_amount": 1000,
            "object": "invoice",
            "paid_at": 1517507495,
            "price_type": "tax_exclusive",
            "recurring": false,
            "resource_version": 1517507495000,
            "round_off_amount": 0,
            "status": "paid",
            "sub_total": 1000,
            "tax": 0,
            "term_finalized": true,
            "total": 1000,
            "updated_at": 1517507495,
            "write_off_amount": 0
        }},
        {..}
    ],
    "next_offset": "[\"1517507499000\",\"192000000463\"]"
}

URL Format GET

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

limit

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

offset

Allows you to fetch the next set of resources. The value used for this parameter must be the value returned for next_offset parameter in the previous API call.
optional, string, max chars=1000

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

To filter based on Invoice Id.
Supported operators : is, is_not, starts_with, in, not_in

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

subscription_id[<operator>]

To filter based on 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>]

To filter based on Invoice Customer Id.
Supported operators : is, is_not, starts_with, in, not_in

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

recurring[<operator>]

To filter based on Invoice Recurring. Possible values are : true, false
Supported operators : is

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

status[<operator>]

To filter based on Invoice Status. Possible values are : paid, posted, payment_due, not_paid, voided, pending.
Supported operators : is, is_not, in, not_in

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

price_type[<operator>]

To filter based on Invoice Price Type. Possible values are : tax_exclusive, tax_inclusive.
Supported operators : is, is_not, in, not_in

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

date[<operator>]

To filter based on Invoice End Date.
Supported operators : after, before, on, between

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

paid_at[<operator>]

To filter based on Invoice Paid On.
Supported operators : after, before, on, between

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

total[<operator>]

To filter based on Invoice Amount.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

amount_paid[<operator>]

To filter based on Invoice Amount Paid.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

amount_adjusted[<operator>]

To filter based on Invoice Amount Adjusted.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

credits_applied[<operator>]

To filter based on Invoice Amount Credited.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

amount_due[<operator>]

To filter based on Invoice Amount Due.
Supported operators : is, is_not, lt, lte, gt, gte, between

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

dunning_status[<operator>]

To filter based on Invoice Dunning Status. Possible values are : in_progress, exhausted, stopped, success.
Supported operators : is, is_not, in, not_in, is_present

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

updated_at[<operator>]

To filter based on updated at. This attribute will be present only if the resource has been updated after 2016-09-28.
Supported operators : after, before, on, between

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

voided_at[<operator>]

To filter based on Voided At.
Supported operators : after, before, on, between

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

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__34 \
     -u {site_api_key}:

copy

curl  https://{site}.chargebee.com/api/v2/invoices/__demo_inv__34 \
     -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": "Duncan",
        "last_name": "Walpole",
        "object": "billing_address",
        "validation_status": "not_validated"
    },
    "credits_applied": 0,
    "currency_code": "USD",
    "customer_id": "__test__5SK0bLNFRFuFQUKnW",
    "date": 1517507504,
    "deleted": false,
    "due_date": 1517507504,
    "exchange_rate": 1,
    "first_invoice": true,
    "has_advance_charges": false,
    "id": "__demo_inv__34",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 1000,
            "date_from": 1517507504,
            "date_to": 1517507504,
            "description": "Support Charge",
            "discount_amount": 0,
            "entity_type": "adhoc",
            "id": "li___test__5SK0bLNFRFuFQVRnd",
            "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": 1000
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 1000,
            "applied_at": 1517507504,
            "txn_amount": 1000,
            "txn_date": 1517507504,
            "txn_id": "txn___test__5SK0bLNFRFuFQVjne",
            "txn_status": "success"
        },
        {..}
    ],
    "net_term_days": 0,
    "new_sales_amount": 1000,
    "object": "invoice",
    "paid_at": 1517507504,
    "price_type": "tax_exclusive",
    "recurring": false,
    "resource_version": 1517507504000,
    "round_off_amount": 0,
    "status": "paid",
    "sub_total": 1000,
    "tax": 0,
    "term_finalized": true,
    "total": 1000,
    "updated_at": 1517507504,
    "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-downloads-dev.s3.amazonaws.com/yourapp/invoice/__test__5SK0bLNFRFuFR9bnu.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Finvoice%2F__test__5SK0bLNFRFuFR9bnu.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20190122T175151Z&X-Amz-SignedHeaders=host&X-Amz-Expires=-30671940&X-Amz-Credential=AKIAJ3MOW2V2DPJQTCMQ%2F20190122%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=a21f89c4d059c63aebd8cb57fb981aff147838989b34d74753c26cf7d7b2e19d",
    "object": "download",
    "valid_till": 1517507571
}}

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

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

Sample Response [ JSON ]

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

URL Format POST

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

amount

The amount to be charged.
required, in cents, min=1

description

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

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

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

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

Sample Response [ JSON ]

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

URL Format POST

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

addon_id

The ID of the non-recurring addon to be charged.
required, string, max chars=100

addon_quantity

The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1

addon_unit_price

Amount that will override the Addon's default price.
optional, in cents, min=0

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 addon starts.
optional, timestamp(UTC) in seconds

line_item[date_to]

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

invoice

Resource object representing invoice.
always returned

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

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

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

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

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

Sample Response [ JSON ]

{"invoice": {
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 11428,
    "amount_paid": 0,
    "amount_to_collect": 11428,
    "applied_credits": [
        {
            "applied_amount": 895,
            "applied_at": 1517507497,
            "cn_date": 1517507497,
            "cn_id": "__demo_cn__4",
            "cn_reason_code": "subscription_change",
            "cn_status": "refunded"
        },
        {..}
    ],
    "base_currency_code": "USD",
    "billing_address": {
        "first_name": "Rachel",
        "last_name": "Green",
        "object": "billing_address",
        "validation_status": "not_validated"
    },
    "credits_applied": 895,
    "currency_code": "USD",
    "customer_id": "__test__KyVnTyRFuFOZQ5f",
    "date": 1517507497,
    "deleted": false,
    "due_date": 1517507497,
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "__demo_inv__10",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 12323,
            "date_from": 1517507497,
            "date_to": 1550512297,
            "description": "Basic - Prorated Charges",
            "discount_amount": 0,
            "entity_id": "basic",
            "entity_type": "plan",
            "id": "li___test__5SK0bLNFRFuFOcMjc",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__KyVnTyRFuFOZQ5f",
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 12323
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [],
    "net_term_days": 0,
    "next_retry_at": 1517507502,
    "object": "invoice",
    "price_type": "tax_exclusive",
    "recurring": true,
    "resource_version": 1517507497000,
    "round_off_amount": 0,
    "status": "payment_due",
    "sub_total": 12323,
    "subscription_id": "__test__KyVnTyRFuFOZQ5f",
    "tax": 0,
    "term_finalized": true,
    "total": 12323,
    "updated_at": 1517507497,
    "write_off_amount": 0
}}

URL Format POST

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

invoice

Resource object representing invoice.
always returned

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

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__12/collect_payment \
     -X POST  \
     -u {site_api_key}:\
     -d payment_source_id="pm___test__5SK0bLNFRFuFOy1jr"

copy

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

Sample Response [ JSON ]

{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 0,
        "amount_paid": 895,
        "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__KyVnTyRFuFOh15t",
        "date": 1547927498,
        "deleted": false,
        "due_date": 1547927498,
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__12",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "date_from": 1547927498,
                "date_to": 1550605898,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnTyRFuFOqo6M",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnTyRFuFOh15t",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 895,
                "applied_at": 1517507499,
                "txn_amount": 895,
                "txn_date": 1517507499,
                "txn_id": "txn___test__5SK0bLNFRFuFOyxju",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517507499,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517507499000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 895,
        "subscription_id": "__test__KyVnTyRFuFOh15t",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517507499,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 895,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnTyRFuFOh15t",
        "date": 1517507499,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnTyRFuFNjZ4H",
        "id": "txn___test__5SK0bLNFRFuFOyxju",
        "id_at_gateway": "cb___test__5SK0bLNFRFuFOz1jv",
        "linked_invoices": [
            {
                "applied_amount": 895,
                "applied_at": 1517507499,
                "invoice_date": 1547927498,
                "invoice_id": "__demo_inv__12",
                "invoice_status": "paid",
                "invoice_total": 895
            },
            {..}
        ],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__5SK0bLNFRFuFOy1jr",
        "resource_version": 1517507499000,
        "status": "success",
        "subscription_id": "__test__KyVnTyRFuFOh15t",
        "type": "payment",
        "updated_at": 1517507499
    }
}

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

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's due amoumt, the remaining transaction amount will be added to the customer's Excess Payments balance to be used against other invoices.

Sample Request

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

copy

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

Sample Response [ JSON ]

{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 695,
        "amount_paid": 200,
        "amount_to_collect": 695,
        "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__KyVnTyRFuFPdV6q",
        "date": 1547927501,
        "deleted": false,
        "due_date": 1547927501,
        "dunning_status": "in_progress",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__27",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "date_from": 1547927501,
                "date_to": 1550605901,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnTyRFuFPls7J",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnTyRFuFPdV6q",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 895,
                "applied_at": 1547927502,
                "txn_amount": 895,
                "txn_date": 1547927502,
                "txn_id": "txn___test__KyVnTyRFuFPmG7K",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "next_retry_at": 1548273103,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517507502000,
        "round_off_amount": 0,
        "status": "payment_due",
        "sub_total": 895,
        "subscription_id": "__test__KyVnTyRFuFPdV6q",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517507502,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 200,
        "amount_unused": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnTyRFuFPdV6q",
        "date": 1548017501,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__5SK0bLNFRFuFPrim3",
        "linked_invoices": [
            {
                "applied_amount": 200,
                "applied_at": 1517507502,
                "invoice_date": 1547927501,
                "invoice_id": "__demo_inv__27",
                "invoice_status": "payment_due",
                "invoice_total": 895
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "resource_version": 1517507502000,
        "status": "success",
        "subscription_id": "__test__KyVnTyRFuFPdV6q",
        "type": "payment",
        "updated_at": 1517507502
    }
}

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

This API is used for issuing a automatic 'refund' from a invoice to a customer. The refund request will be processed via the payment gateway that was originally used to charge the customer.

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

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 0,
        "amount_refunded": 1000,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuFPxwmQ",
        "date": 1517507503,
        "deleted": false,
        "exchange_rate": 1,
        "id": "__demo_cn__7",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517507503,
                "date_to": 1517507503,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__5SK0bLNFRFuFQ1ume",
                "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": 1000
            },
            {..}
        ],
        "linked_refunds": [
            {
                "applied_amount": 1000,
                "applied_at": 1517507503,
                "txn_amount": 1000,
                "txn_date": 1517507503,
                "txn_id": "txn___test__5SK0bLNFRFuFQ1Tmc",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "service_unsatisfactory",
        "reference_invoice_id": "__demo_inv__29",
        "refunded_at": 1517507503,
        "resource_version": 1517507503000,
        "round_off_amount": 0,
        "status": "refunded",
        "sub_total": 1000,
        "taxes": [],
        "total": 1000,
        "type": "refundable",
        "updated_at": 1517507503
    },
    "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__5SK0bLNFRFuFPxwmQ",
        "date": 1517507502,
        "deleted": false,
        "due_date": 1517507502,
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__29",
        "is_gifted": false,
        "issued_credit_notes": [
            {
                "cn_date": 1517507503,
                "cn_id": "__demo_cn__7",
                "cn_reason_code": "service_unsatisfactory",
                "cn_status": "refunded",
                "cn_total": 1000
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517507502,
                "date_to": 1517507502,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__5SK0bLNFRFuFPz3mX",
                "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": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517507502,
                "txn_amount": 1000,
                "txn_date": 1517507502,
                "txn_id": "txn___test__5SK0bLNFRFuFPzQmY",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 1000,
        "object": "invoice",
        "paid_at": 1517507502,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517507503000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517507503,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 1000,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuFPxwmQ",
        "date": 1517507503,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnTyRFuFNjZ4H",
        "id": "txn___test__5SK0bLNFRFuFQ1Tmc",
        "id_at_gateway": "cb___test__5SK0bLNFRFuFPzVmZ",
        "linked_credit_notes": [
            {
                "applied_amount": 1000,
                "applied_at": 1517507503,
                "cn_date": 1517507503,
                "cn_id": "__demo_cn__7",
                "cn_reason_code": "service_unsatisfactory",
                "cn_reference_invoice_id": "__demo_inv__29",
                "cn_status": "refunded",
                "cn_total": 1000
            },
            {..}
        ],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__5SK0bLNFRFuFPyCmS",
        "refunded_txn_id": "txn___test__5SK0bLNFRFuFPzQmY",
        "resource_version": 1517507503000,
        "status": "success",
        "type": "refund",
        "updated_at": 1517507503
    }
}

URL Format POST

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

refund_amount

Amount to be refunded. If not specified, the entire refundable amount for this invoice will be refunded.
optional, integer, min=1

comment

Comment, if any, on the refund.
optional, string, max chars=300

customer_notes

The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
optional, string, max chars=1000

credit_note

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

credit_note[reason_code]

The reason for issuing this Credit Note. The following reason codes are supported now.
optional, enumerated string, default=other

Possible values are

product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.

Show all values[+]

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
always returned

credit_note

Resource object representing credit_note.
optional

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

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 0,
        "amount_refunded": 100,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuFPtKm7",
        "date": 1517507502,
        "deleted": false,
        "exchange_rate": 1,
        "id": "__demo_cn__6",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 100,
                "date_from": 1517507502,
                "date_to": 1517507502,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__5SK0bLNFRFuFPvnmL",
                "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": 1517507502,
                "txn_amount": 100,
                "txn_date": 1517507502,
                "txn_id": "txn___test__5SK0bLNFRFuFPvimJ",
                "txn_status": "success"
            },
            {..}
        ],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "other",
        "reference_invoice_id": "__demo_inv__28",
        "refunded_at": 1517507502,
        "resource_version": 1517507502000,
        "round_off_amount": 0,
        "status": "refunded",
        "sub_total": 100,
        "taxes": [],
        "total": 100,
        "type": "refundable",
        "updated_at": 1517507502
    },
    "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__5SK0bLNFRFuFPtKm7",
        "date": 1517507502,
        "deleted": false,
        "due_date": 1517507502,
        "exchange_rate": 1,
        "first_invoice": true,
        "has_advance_charges": false,
        "id": "__demo_inv__28",
        "is_gifted": false,
        "issued_credit_notes": [
            {
                "cn_date": 1517507502,
                "cn_id": "__demo_cn__6",
                "cn_reason_code": "other",
                "cn_status": "refunded",
                "cn_total": 100
            },
            {..}
        ],
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517507502,
                "date_to": 1517507502,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__5SK0bLNFRFuFPuKmE",
                "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": 1000
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 1000,
                "applied_at": 1517507502,
                "txn_amount": 1000,
                "txn_date": 1517507502,
                "txn_id": "txn___test__5SK0bLNFRFuFPubmF",
                "txn_status": "success"
            },
            {..}
        ],
        "net_term_days": 0,
        "new_sales_amount": 1000,
        "object": "invoice",
        "paid_at": 1517507502,
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517507502000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 1000,
        "tax": 0,
        "term_finalized": true,
        "total": 1000,
        "updated_at": 1517507502,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 100,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuFPtKm7",
        "date": 1517507502,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "not_applicable",
        "id": "txn___test__5SK0bLNFRFuFPvimJ",
        "linked_credit_notes": [
            {
                "applied_amount": 100,
                "applied_at": 1517507502,
                "cn_date": 1517507502,
                "cn_id": "__demo_cn__6",
                "cn_reason_code": "other",
                "cn_reference_invoice_id": "__demo_inv__28",
                "cn_status": "refunded",
                "cn_total": 100
            },
            {..}
        ],
        "object": "transaction",
        "payment_method": "bank_transfer",
        "resource_version": 1517507502000,
        "status": "success",
        "type": "refund",
        "updated_at": 1517507502
    }
}

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

transaction

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

transaction[amount]

Amount to be recorded as refunded. If this parameter is not passed then the entire refundable amount will be recorded as refunded.
optional, in cents, min=1

transaction[payment_method]

The Payment Method of this transaction.
required, enumerated string, default=card

Possible values are

cashCash.checkCheck.chargebackChargeback.

bank_transferBank Transfer.otherPayment Methods other than the above types.

Show all values[+]

transaction[reference_number]

The reference number for this transaction. e.g check number in case of 'check' payments.
optional, string, max chars=100

transaction[date]

Indicates when this transaction occurred.
required, timestamp(UTC) in seconds

credit_note

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

credit_note[reason_code]

The reason for issuing this Credit Note. The following reason codes are supported now.
optional, enumerated string, default=other

Possible values are

Show all values[+]

invoice

Resource object representing invoice.
always returned

transaction

Resource object representing transaction.
always returned

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__33/remove_payment \
     -X POST  \
     -u {site_api_key}:\
     -d transaction[id]="txn___test__5SK0bLNFRFuFQRbnO"

copy

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

Sample Response [ JSON ]

{
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 895,
        "amount_paid": 0,
        "amount_to_collect": 895,
        "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__KyVnTyRFuFQBr7Z",
        "date": 1547927503,
        "deleted": false,
        "due_date": 1547927503,
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__33",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "date_from": 1547927503,
                "date_to": 1550605903,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnTyRFuFQK582",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnTyRFuFQBr7Z",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 895,
                "applied_at": 1547927504,
                "txn_amount": 895,
                "txn_date": 1547927504,
                "txn_id": "txn___test__KyVnTyRFuFQKQ83",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517507504000,
        "round_off_amount": 0,
        "status": "posted",
        "sub_total": 895,
        "subscription_id": "__test__KyVnTyRFuFQBr7Z",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517507504,
        "write_off_amount": 0
    },
    "transaction": {
        "amount": 895,
        "amount_unused": 895,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnTyRFuFQBr7Z",
        "date": 1517507504,
        "deleted": false,
        "exchange_rate": 1,
        "gateway": "chargebee",
        "gateway_account_id": "gw___test__KyVnTyRFuFNjZ4H",
        "id": "txn___test__5SK0bLNFRFuFQRbnO",
        "id_at_gateway": "cb___test__5SK0bLNFRFuFQRfnP",
        "linked_invoices": [],
        "linked_refunds": [],
        "masked_card_number": "***********0005",
        "object": "transaction",
        "payment_method": "card",
        "payment_source_id": "pm___test__5SK0bLNFRFuFQQlnL",
        "resource_version": 1517507504000,
        "status": "success",
        "type": "payment",
        "updated_at": 1517507504
    }
}

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__31/remove_credit_note \
     -X POST  \
     -u {site_api_key}:\
     -d credit_note[id]="__demo_cn__8"

copy

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

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [],
        "amount_allocated": 0,
        "amount_available": 1000,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__5SK0bLNFRFuFQ3kmj",
        "date": 1517507503,
        "deleted": false,
        "exchange_rate": 1,
        "id": "__demo_cn__8",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 1000,
                "date_from": 1517507503,
                "date_to": 1517507503,
                "description": "Support Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__5SK0bLNFRFuFQ6Bmw",
                "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": 1000
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "service_unsatisfactory",
        "reference_invoice_id": "__demo_inv__30",
        "resource_version": 1517507503000,
        "round_off_amount": 0,
        "status": "refund_due",
        "sub_total": 1000,
        "taxes": [],
        "total": 1000,
        "type": "refundable",
        "updated_at": 1517507503
    },
    "invoice": {
        "adjustment_credit_notes": [],
        "amount_adjusted": 0,
        "amount_due": 2000,
        "amount_paid": 0,
        "amount_to_collect": 2000,
        "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__5SK0bLNFRFuFQ3kmj",
        "date": 1517507503,
        "deleted": false,
        "due_date": 1517507503,
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__31",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 2000,
                "date_from": 1517507503,
                "date_to": 1517507503,
                "description": "Service Charge",
                "discount_amount": 0,
                "entity_type": "adhoc",
                "id": "li___test__5SK0bLNFRFuFQ7cn1",
                "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": [],
        "net_term_days": 0,
        "object": "invoice",
        "price_type": "tax_exclusive",
        "recurring": false,
        "resource_version": 1517507503000,
        "round_off_amount": 0,
        "status": "not_paid",
        "sub_total": 2000,
        "tax": 0,
        "term_finalized": true,
        "total": 2000,
        "updated_at": 1517507503,
        "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

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

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

Notes

If the invoice having charges for the 'current term' is voided and the subscription is changed subsequently with 'proration' enabled, the pro-rated credits will not be issued for the current-term charges (as its invoice became void)
Once voided, any Promotional Credits and Prorated Credits applied to this invoice would be reclaimed.

Sample Request

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

copy

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

Sample Response [ JSON ]

{"invoice": {
    "adjustment_credit_notes": [],
    "amount_adjusted": 0,
    "amount_due": 12323,
    "amount_paid": 0,
    "amount_to_collect": 12323,
    "applied_credits": [],
    "base_currency_code": "USD",
    "credits_applied": 0,
    "currency_code": "USD",
    "customer_id": "__test__KyVnTyRFuFSdc9k",
    "date": 1517507513,
    "deleted": false,
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "__demo_inv__41",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 12323,
            "date_from": 1517507513,
            "date_to": 1550512313,
            "description": "Basic - Prorated Charges",
            "discount_amount": 0,
            "entity_id": "basic",
            "entity_type": "plan",
            "id": "li___test__5SK0bLNFRFuFSh8nx",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__KyVnTyRFuFSdc9k",
            "tax_amount": 0,
            "unit_amount": 12323
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [],
    "net_term_days": 0,
    "object": "invoice",
    "price_type": "tax_exclusive",
    "recurring": true,
    "resource_version": 1517507513000,
    "round_off_amount": 0,
    "status": "voided",
    "sub_total": 12323,
    "subscription_id": "__test__KyVnTyRFuFSdc9k",
    "tax": 0,
    "term_finalized": true,
    "total": 12323,
    "updated_at": 1517507513,
    "voided_at": 1517507513,
    "write_off_amount": 0
}}

URL Format POST

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

comment

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

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__43/write_off \
     -X POST  \
     -u {site_api_key}:

copy

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

Sample Response [ JSON ]

{
    "credit_note": {
        "allocations": [
            {
                "allocated_amount": 895,
                "allocated_at": 1517507514,
                "invoice_date": 1547927513,
                "invoice_id": "__demo_inv__43",
                "invoice_status": "paid"
            },
            {..}
        ],
        "amount_allocated": 895,
        "amount_available": 0,
        "amount_refunded": 0,
        "base_currency_code": "USD",
        "currency_code": "USD",
        "customer_id": "__test__KyVnTyRFuFSkW9y",
        "date": 1517507514,
        "deleted": false,
        "exchange_rate": 1,
        "id": "__demo_cn__10",
        "line_item_discounts": [],
        "line_item_taxes": [],
        "line_items": [
            {
                "amount": 895,
                "date_from": 1517507514,
                "date_to": 1517507514,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__5SK0bLNFRFuFSy4o8",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnTyRFuFSkW9y",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_refunds": [],
        "object": "credit_note",
        "price_type": "tax_exclusive",
        "reason_code": "write_off",
        "reference_invoice_id": "__demo_inv__43",
        "refunded_at": 1517507514,
        "resource_version": 1517507514000,
        "round_off_amount": 0,
        "status": "adjusted",
        "sub_total": 895,
        "subscription_id": "__test__KyVnTyRFuFSkW9y",
        "taxes": [],
        "total": 895,
        "type": "adjustment",
        "updated_at": 1517507514
    },
    "invoice": {
        "adjustment_credit_notes": [
            {
                "cn_date": 1517507514,
                "cn_id": "__demo_cn__10",
                "cn_reason_code": "write_off",
                "cn_status": "adjusted",
                "cn_total": 895
            },
            {..}
        ],
        "amount_adjusted": 895,
        "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__KyVnTyRFuFSkW9y",
        "date": 1547927513,
        "deleted": false,
        "due_date": 1547927513,
        "dunning_status": "stopped",
        "exchange_rate": 1,
        "first_invoice": false,
        "has_advance_charges": false,
        "id": "__demo_inv__43",
        "is_gifted": false,
        "issued_credit_notes": [],
        "line_items": [
            {
                "amount": 895,
                "date_from": 1547927513,
                "date_to": 1550605913,
                "description": "No Trial",
                "discount_amount": 0,
                "entity_id": "no_trial",
                "entity_type": "plan",
                "id": "li___test__KyVnTyRFuFSsCAR",
                "is_taxed": false,
                "item_level_discount_amount": 0,
                "object": "line_item",
                "pricing_model": "per_unit",
                "quantity": 1,
                "subscription_id": "__test__KyVnTyRFuFSkW9y",
                "tax_amount": 0,
                "tax_exempt_reason": "tax_not_configured",
                "unit_amount": 895
            },
            {..}
        ],
        "linked_orders": [],
        "linked_payments": [
            {
                "applied_amount": 895,
                "applied_at": 1547927514,
                "txn_amount": 895,
                "txn_date": 1547927514,
                "txn_id": "txn___test__KyVnTyRFuFSsXAS",
                "txn_status": "failure"
            },
            {..}
        ],
        "net_term_days": 0,
        "object": "invoice",
        "paid_at": 1517507514,
        "price_type": "tax_exclusive",
        "recurring": true,
        "resource_version": 1517507514000,
        "round_off_amount": 0,
        "status": "paid",
        "sub_total": 895,
        "subscription_id": "__test__KyVnTyRFuFSkW9y",
        "tax": 0,
        "term_finalized": true,
        "total": 895,
        "updated_at": 1517507514,
        "write_off_amount": 895
    }
}

URL Format POST

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

comment

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

invoice

Resource object representing invoice.
always returned

credit_note

Resource object representing credit_note.
always returned

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

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

Notes

If the invoice having charges for the 'current term' is deleted and the subscription is changed subsequently with 'proration' enabled, the pro-rated credits will not be issued for the current-term charges (as its invoice got deleted)
During deletetion, any Promotional Credits and Prorated Credits applied to this invoice would be reclaimed.

Sample Request

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

copy

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

Sample Response [ JSON ]

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

URL Format POST

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

comment

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

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__39/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__39/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": 895,
    "amount_paid": 0,
    "amount_to_collect": 895,
    "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__KyVnTyRFuFSOY91",
    "date": 1547927512,
    "deleted": false,
    "due_date": 1547927512,
    "dunning_status": "in_progress",
    "exchange_rate": 1,
    "first_invoice": false,
    "has_advance_charges": false,
    "id": "__demo_inv__39",
    "is_gifted": false,
    "issued_credit_notes": [],
    "line_items": [
        {
            "amount": 895,
            "date_from": 1547927512,
            "date_to": 1550605912,
            "description": "No Trial",
            "discount_amount": 0,
            "entity_id": "no_trial",
            "entity_type": "plan",
            "id": "li___test__KyVnTyRFuFSWj9U",
            "is_taxed": false,
            "item_level_discount_amount": 0,
            "object": "line_item",
            "pricing_model": "per_unit",
            "quantity": 1,
            "subscription_id": "__test__KyVnTyRFuFSOY91",
            "tax_amount": 0,
            "tax_exempt_reason": "tax_not_configured",
            "unit_amount": 895
        },
        {..}
    ],
    "linked_orders": [],
    "linked_payments": [
        {
            "applied_amount": 895,
            "applied_at": 1547927513,
            "txn_amount": 895,
            "txn_date": 1547927513,
            "txn_id": "txn___test__KyVnTyRFuFSX49V",
            "txn_status": "failure"
        },
        {..}
    ],
    "net_term_days": 0,
    "next_retry_at": 1548273114,
    "object": "invoice",
    "price_type": "tax_exclusive",
    "recurring": true,
    "resource_version": 1517507513000,
    "round_off_amount": 0,
    "status": "payment_due",
    "sub_total": 895,
    "subscription_id": "__test__KyVnTyRFuFSOY91",
    "tax": 0,
    "term_finalized": true,
    "total": 895,
    "updated_at": 1517507513,
    "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

po_number

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

billing_address

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

billing_address[first_name]

First name.
optional, string, max chars=150

billing_address[last_name]

Last name.
optional, string, max chars=150

billing_address[email]

Email.
optional, string, max chars=70

billing_address[company]

Company name.
optional, string, max chars=250

billing_address[phone]

Phone number.
optional, string, max chars=50

billing_address[line1]

Address line 1.
optional, string, max chars=150

billing_address[line2]

Address line 2.
optional, string, max chars=150

billing_address[line3]

Address line 3.
optional, string, max chars=150

billing_address[city]

City.
optional, string, max chars=50

billing_address[state_code]

billing_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50

billing_address[zip]

Zip or Postal code.
optional, string, max chars=20

billing_address[country]

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

billing_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

shipping_address

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

shipping_address[first_name]

First name.
optional, string, max chars=150

shipping_address[last_name]

Last name.
optional, string, max chars=150

shipping_address[email]

Email.
optional, string, max chars=70

shipping_address[company]

Company name.
optional, string, max chars=250

shipping_address[phone]

Phone number.
optional, string, max chars=50

shipping_address[line1]

Address line 1.
optional, string, max chars=180

shipping_address[line2]

Address line 2.
optional, string, max chars=150

shipping_address[line3]

Address line 3.
optional, string, max chars=150

shipping_address[city]

City.
optional, string, max chars=50

shipping_address[state_code]

shipping_address[state]

The state/province name. Use this to pass the state/province information for cases where 'state_code' is not supported or cannot be passed.
optional, string, max chars=50

shipping_address[zip]

Zip or Postal code.
optional, string, max chars=20

shipping_address[country]

2-letter ISO 3166 alpha-2 country code.
optional, string, max chars=50

shipping_address[validation_status]

The address verification status.
optional, enumerated string, default=not_validated

Possible values are

not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.

invoice

Resource object representing invoice.
always returned

Sample invoice [ JSON ]

API Index URL GET

Invoice attributes

Create an invoice¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Create invoice for charge¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Create invoice for addon¶

Notes

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Stop dunning for invoice¶

Sample Response [ JSON ]

URL Format POST

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 charge item to pending invoice¶

Related Tutorial

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Add addon item to pending invoice¶

Related Tutorial

Sample Response [ JSON ]

URL Format POST

Input Parameters

Returns

Close a pending invoice¶

Related Tutorial

Sample Response [ JSON ]

URL Format POST

Returns

Collect payment for an invoice¶

Notes

Sample Response [ JSON ]

URL Format POST