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__XpbBxQiS4HD18hX5",
"date": 1517429428,
"deleted": false,
"due_date": 1517429428,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__13",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [{
"amount": 4000,
"customer_id": "__test__XpbBxQiS4HD18hX5",
"date_from": 1517429428,
"date_to": 1517429428,
"description": "non_recurring_addon",
"discount_amount": 0,
"entity_id": "non_recurring_addon",
"entity_type": "addon",
"id": "li___test__XpbBxQiS4HD1AUXC",
"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": 1517429428,
"txn_amount": 4000,
"txn_date": 1517429428,
"txn_id": "txn___test__XpbBxQiS4HD1ArXD",
"txn_status": "success"
}],
"net_term_days": 0,
"new_sales_amount": 4000,
"object": "invoice",
"paid_at": 1517429428,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429428000,
"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": 1517429428,
"write_off_amount": 0
}
API Index URL GET
https://{site}.chargebee.com/api/v2/invoices
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
string, max chars=50
Purchase Order Number for this invoice.
optional, string, max chars=100
The identifier of the customer this invoice belongs to.
string, max chars=50
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
Boolean indicating whether this invoice belongs to a subscription.
boolean, default=true
Current status of this invoice.
enumerated stringPossible 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.pending- Product Catalog 2.0: The invoice is
yet to be closed (sent for payment collection). An invoice is generated with this
status
when it has line items that
belong to items that are metered
or when the subscription.create_pending_invoices
attribute is set to true
.
- Product Catalog 1.0:
The invoice is yet to be
closed (sent for payment collection). All invoices are generated with this status
when Metered
Billing is enabled for the site.
.
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
The price type of the invoice.
enumerated string, default=tax_exclusivePossible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
Date indicated on the invoice. When
metered billing is disabled, this value is the date of generation of the invoice. When metered billing is enabled,
you can select from one of the following:
- date of invoice generation.
- date of closing the invoice
.
optional, timestamp(UTC) in seconds
Due date of the invoice.
optional, timestamp(UTC) in seconds
Number of days within which the invoice has to be paid.
optional, integer, default=0
The currency code (ISO 4217 format) for the invoice.
string, max chars=3
Invoiced amount in cents.
optional, in cents, min=0
Total payments received for this invoice.
optional, in cents, min=0
Total adjustments made against this invoice.
optional, in cents, default=0, min=0
Amount written off against this invoice.
optional, in cents, default=0, min=0
Total credits applied against this invoice.
optional, in cents, default=0, min=0
Total amount to be collected. This includes invoice's payments in progress.
optional, in cents, min=0
Timestamp indicating the date & time this invoice got paid.
optional, timestamp(UTC) in seconds
Current dunning status of the invoice.
optional, enumerated stringPossible 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.
Timestamp indicating when will the next attempt to collect payment for this invoice occur.
optional, timestamp(UTC) in seconds
Timestamp indicating the date & time this invoice got voided.
optional, timestamp(UTC) in seconds
Version number of this resource. Each update of this resource results in incremental change of this number.
optional, long
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
The invoice sub-total.
in cents, min=0
sub_total_in_local_currency
Invoice subtotal in the currency of the place of supply.
optional, in cents, min=0
Total invoice amount in the currency of the place of supply.
optional, in cents, min=0
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed.
optional, string, max chars=null
Total tax amount for this invoice.
in cents, min=0
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
Boolean indicating any advance charge is present in this invoice.
optional, boolean
Boolean indicating this invoice line_items terms are finalized or not.
boolean, default=true
Boolean indicating this invoice is gifted or not.
boolean, default=false
Expected payment date recorded for this invoice.
optional, timestamp(UTC) in seconds
Total amount to be collected.
optional, in cents, min=0
Indicates the rounded-off amount.
optional, in cents, min=0
Payment owner of an invoice.
optional, string, max chars=null
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive.
optional, string, max chars=100
Indicates that this resource has been deleted.
boolean
The list of line items for this invoice.
optional, list of line_item
Uniquely identifies a line_item.
optional, string, max chars=40
A unique identifier for the subscription this line item belongs to.
optional, string, max chars=3
Start date of this line item.
timestamp(UTC) in seconds
End date of this line item.
timestamp(UTC) in seconds
Unit amount of the line item.
in cents
- Product Catalog 2.0: Quantity of the recurring item which is represented by this line item. For
metered
line
items, this value is updated from usages once when the invoice is generated as pending
and finally when the
invoice is closed.
- Product Catalog 1.0: Quantity of the recurring item which is represented by this line item.
.
optional, integer, default=1
Total amount of this line item. Typically equals to unit amount x quantity.
optional, in cents
The
pricing scheme for this item. In Product Catalog v2, the
pricing scheme for this item price.
optional, enumerated stringPossible values are
flat_feeA fixed price that is not quantity-based.per_unitA fixed price per unit quantity.tieredThe per unit price is based on the tier that the total quantity falls in.volumeThere are quantity tiers for which per unit prices are set. Quantities are purchased from successive tiers.stairstepA quantity-based pricing scheme. The item is charged a fixed price based on the tier that the total quantity falls in.
Specifies whether this line item is taxed or not.
boolean, default=false
The tax amount charged for this item.
optional, in cents, default=0, min=0
Rate of tax used to calculate tax for this lineitem.
optional, double, min=0.0, max=100.0
The decimal representation of the unit amount of the
line_item
. The value is in major units of the currency. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
The decimal representation of the quantity of this line_item. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
The decimal representation of the amount for the
line_item
, in major units of the currency. Typically equals to
unit_amount_in_decimal
x
quantity_in_decimal
. Returned when
multi-decimal pricing is enabled.
optional, string, max chars=33
Total discounts for this line.
optional, in cents, min=0
item_level_discount_amount
Line Item-level discounts for this line.
optional, in cents, min=0
Detailed description about this line item.
string, max chars=250
Detailed description about this item.
string, max chars=500
Specifies the modelled entity this line item is based on.
enumerated stringPossible 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.
The reason due to which the line item price/amount is exempted from tax.
optional, enumerated stringPossible values are
tax_not_configuredIf tax is not enabled for the site.region_non_taxableIf the product sold is not taxable in this region, but it is taxable in other regions, hence this region is not part of the Taxable jurisdiction.exportYou are not registered for tax in the customer’s region. This is also the reason code when both billing_address
and shipping_address
have not been provided for the customer and subscription respectively.customer_exemptIf the Customer is marked as Tax exempt.product_exemptIf the Plan or Addon is marked as Tax exempt.zero_ratedIf the rate of tax is 0% and no Sales/ GST tax is collectable for that line item.reverse_chargeIf the Customer is identified as B2B customer (when VAT Number is entered), applicable for EU only.high_value_physical_goodsIf physical goods are sold from outside Australia to customers in Australia, and the price of all the physical good line items is greater than AUD 1000, then tax will not be applied.
The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100
A unique identifier for the customer this line item belongs to.
optional, string, max chars=100
The list of discounts applied for this invoice.
optional, list of discount
Discount amount.
in cents, min=0
Detailed description of this discount line item.
optional, string, max chars=250
Type of this Discount line item.
enumerated stringPossible 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.
The identifier of the modelled entity this line item is based on. Will be null for 'Prorated Credits' & 'Promotional Credits'.
optional, string, max chars=100
The list of discount(s) applied for each line item of this invoice.
optional, list of line_item_discount
Line item discount attributes
The unique reference id of the line item for which the discount is applicable.
string, max chars=50
Type of this discount line item.
enumerated stringPossible 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.
optional, string, max chars=50
Discount amount.
in cents, min=0
The list of taxes applied for this invoice.
optional, list of tax
The name of the tax applied. E.g. GST.
string, max chars=100
The tax amount.
in cents, min=0
Description of the tax item.
optional, string, max chars=250
The list of taxes applied on line items.
optional, list of line_item_tax
The unique reference id of the line item for which the tax is applicable.
optional, string, max chars=40
The name of the tax applied.
string, max chars=100
The rate of tax used to calculate tax amount.
double, default=0.0, min=0.0, max=100.0
Indicates if tax is applied only on a portion of the line item amount.
optional, boolean
Indicates the non-compliance tax that should not be reported to the jurisdiction.
optional, boolean
Indicates the actual portion of the line item amount that is taxable.
in cents, min=0
The tax amount.
in cents, min=0
The type of tax jurisdiction.
optional, enumerated stringPossible 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.
The name of the tax jurisdiction.
optional, string, max chars=250
The tax jurisdiction code.
optional, string, max chars=250
tax_amount_in_local_currency
Total tax amount in the currency of the place of supply. This is applicable only for Invoice and Credit Notes API.
optional, in cents, min=0
The currency code (ISO 4217 format) of the place of supply in which VAT needs to be converted and displayed. This is applicable only for Invoice and Credit Notes API.
optional, string, max chars=null
The list of tiers applicable for this line item.
optional, list of line_item_tier
Line item tier attributes
Uniquely identifies a line_item.
optional, string, max chars=40
The lower limit of a range of units for the tier.
integer, min=0
The upper limit of a range of units for the tier.
optional, integer
The number of units purchased in a range.
integer, min=0
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
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as
ending_unit_in_decimal
of the next lower tier. Returned only when the
line_items.pricing_model
is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
optional, string, max chars=33
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the
starting_unit_in_decimal
of the next higher tier. Returned only when the
line_items.pricing_model
is
tiered
,
volume
or stairstep and
multi-decimal pricing is enabled.
optional, string, max chars=33
The decimal representation of the quantity purchased from this tier. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
The decimal representation of the per-unit price for the tier when the
pricing_model
is
tiered
or
volume
. When the
pricing_model
is
stairstep
, it is the decimal representation of the total price for
line_item
. The value is in major units of the currency. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=40
The list of transactions for this invoice.
optional, list of invoice_transaction
Linked payment attributes
Uniquely identifies the transaction.
string, max chars=40
The transaction amount applied to this invoice.
in cents, min=0
Timestamp at which the transaction is applied.
timestamp(UTC) in seconds
The status of this transaction.
optional, enumerated stringPossible values are
in_progressTransaction is being processed by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.timeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually.
Indicates when this transaction occurred.
optional, timestamp(UTC) in seconds
Total amount of the transaction.
optional, in cents, min=1
The list of dunning_attempts for this invoice.
optional, list of dunning_attempt
Dunning attempt attributes
Dunning attempt number.
integer
Transaction associated with attempt.
optional, string, max chars=40
Types of dunning.
enumerated string, default=auto_collectPossible values are
auto_collectDunning type is auto collection.offlineDunning type is offline.direct_debitDunning type is direct debit.
Timestamp at which the attempt was made.
optional, timestamp(UTC) in seconds
The status of this transaction.
optional, enumerated stringPossible values are
in_progressTransaction is being processed by the gateway. This typically happens for direct debit transactions or, in case of cards, refund transactions. Such transactions can take 2-7 days to complete, depending on the gateway and payment method.successThe transaction is successful.voidedThe transaction got voided or authorization expired at gateway.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.timeoutTransaction failed because of Gateway not accepting the connection.needs_attentionConnection with Gateway got terminated abruptly. So, status of this transaction needs to be resolved manually.
Total amount of the transaction.
optional, in cents, min=1
Refundable Credits applied on this invoice.
optional, list of applied_credit
Applied credit attributes
timestamp(UTC) in seconds
Credit note reason code. Deprecated; use the cn_create_reason_code parameter instead.
optional, enumerated stringPossible 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[+]
Credit note reason code.
optional, string, max chars=100
Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds
Credit note status.
enumerated stringPossible 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.
Adjustments created for this invoice.
optional, list of created_credit_note
Adjustment credit note attributes
Credit-note id.
string, max chars=50
Credit note reason code. Deprecated; use the cn_create_reason_code parameter instead.
optional, enumerated stringPossible 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[+]
Credit note reason code.
optional, string, max chars=100
Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds
Total amount of the credit note.
optional, in cents, default=0, min=0
Credit note status.
enumerated stringPossible 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.
Credit notes issued for this invoice.
optional, list of created_credit_note
Issued credit note attributes
Credit-note id.
string, max chars=50
Credit note reason code. Deprecated; use the cn_create_reason_code parameter instead.
optional, enumerated stringPossible 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[+]
Credit note reason code.
optional, string, max chars=100
Indicates the date at which this credit note is created.
optional, timestamp(UTC) in seconds
Total amount of the credit note.
optional, in cents, default=0, min=0
Credit note status.
enumerated stringPossible 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.
The list of orders for this invoice.
optional, list of linked_order
Uniquely identifies the order. It is the api identifier for the order.
string, max chars=40
The order's serial number.
optional, string, max chars=50
The status of this order.
optional, enumerated string, default=newPossible 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.
optional, enumerated stringPossible 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 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
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
Unique id to identify a group of orders.
optional, string, max chars=50
The time at which the order was created.
timestamp(UTC) in seconds
The list of notes associated with the invoice. If entity_type & entity_id are not present, then it is general notes (i.e Notes input provided under "Customize Invoice" action in Chargebee web interface).
optional, list of note
Type of entity to which the note belongs. .
enumerated stringPossible 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.
Actual note.
string, max chars=2000
Unique identifier of the entity.
optional, string, max chars=100
Shipping address for the invoice.
optional, shipping_address
Shipping addres attributes
The first name of the contact.
optional, string, max chars=150
The last name of the contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=180
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Billing address for the invoice.
optional, billing_address
Billing addres attributes
The first name of the billing contact.
optional, string, max chars=150
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
State or Province.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
This operation supports 3DS verification flow. To achieve the same, create the
Payment Intent and pass it as input parameter to this API.
Creates a one-off invoice for multiple 'Non Recurring' 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__XpbBxQiS4HD18hX5" \
-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__XpbBxQiS4HD18hX5" \
-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__XpbBxQiS4HD1DPXH" \
-d charges[amount][0]=1000 \
-d charges[description][0]="Support Charge"
Sample Response [ JSON ]
Show more...
{"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__XpbBxQiS4HD18hX5",
"date": 1517429428,
"deleted": false,
"due_date": 1517429428,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__13",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 4000,
"customer_id": "__test__XpbBxQiS4HD18hX5",
"date_from": 1517429428,
"date_to": 1517429428,
"description": "non_recurring_addon",
"discount_amount": 0,
"entity_id": "non_recurring_addon",
"entity_type": "addon",
"id": "li___test__XpbBxQiS4HD1AUXC",
"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": 1517429428,
"txn_amount": 4000,
"txn_date": 1517429428,
"txn_id": "txn___test__XpbBxQiS4HD1ArXD",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 4000,
"object": "invoice",
"paid_at": 1517429428,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429428000,
"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": 1517429428,
"write_off_amount": 0
}}
Show more...
{"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__XpbBxQiS4HD1DPXH",
"date": 1517429428,
"deleted": false,
"due_date": 1517429428,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__14",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD1DPXH",
"date_from": 1517429428,
"date_to": 1517429428,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD1EzXO",
"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": 1517429428,
"txn_amount": 1000,
"txn_date": 1517429428,
"txn_id": "txn___test__XpbBxQiS4HD1FIXP",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1517429428,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429428000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"tax": 0,
"term_finalized": true,
"total": 1000,
"updated_at": 1517429428,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices
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
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
The currency code (ISO 4217 format) of the invoice amount.
required if Multicurrency is enabled, string, max chars=3
Add a
note to this invoice.
optional, string, max chars=2000
Set as
false
to show general notes on the invoice.
General note is a site-level note that’s added to all invoices and configured via the Chargebee UI under
Settings > Configure Chargebee > Invoices, credit notes, and quotes > Invoices.
optional, boolean, default=false
Purchase Order Number for this invoice.
optional, string, max chars=100
List of Coupons to be .
optional, list of string
authorization_transaction_id
Authorization transaction to be captured.
optional, string, max chars=40
Payment source to be used for this payment.
optional, string, max chars=40
The customer level auto collection will be override if specified.
optional, enumerated stringPossible values are
onWhenever an invoice is created, an automatic attempt will be made to charge.offWhenever an invoice is created as payment due.
Token generated by Chargebee JS representing payment method details.
optional, string, max chars=40
replace_primary_payment_source
Indicates whether the primary payment source should be replaced with this payment source.
optional, boolean, default=false
Indicates whether the payment source should be retained for the customer.
optional, boolean, default=true
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=180
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for card
pass parameters as card[<param name>]
The gateway account in which this payment source is stored.
optional, string, max chars=50
Cardholder's first name.
optional, string, max chars=50
Cardholder's last name.
optional, string, max chars=50
The credit card number without any format. If you are using
Braintree.js, you can specify the Braintree encrypted card number here.
required if card provided, string, max chars=1500
Card expiry month.
required if card provided, integer, min=1, max=12
Card expiry year.
required if card provided, integer
The card verification value (CVV). If you are using
Braintree.js, you can specify the Braintree encrypted CVV here.
optional, string, max chars=520
Address line 1, as available in card billing address.
optional, string, max chars=150
Address line 2, as available in card billing address.
optional, string, max chars=150
City, as available in card billing address.
optional, string, max chars=50
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Postal or Zip code, as available in card billing address.
optional, string, max chars=20
Parameters for bank_account
pass parameters as bank_account[<param name>]
bank_account[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
Account holder’s International Bank Account Number. For the
GoCardless platform, this can be the
local bank details
.
optional, string, min chars=10, max chars=50
Account holder’s first name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150
Account holder’s last name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=150
Account holder’s company name as per bank account. If not passed, details from customer details will be considered.
optional, string, max chars=250
Account holder’s email address. If not passed, details from customer details will be considered. All Direct Debit compliant emails will be sent to this email address.
optional, string, max chars=70
Name of account holder’s bank.
optional, string, max chars=100
bank_account[account_number]
Account holder’s bank account number.
optional, string, min chars=4, max chars=17
bank_account[routing_number]
Bank account routing number.
optional, string, min chars=3, max chars=9
Indicates the bank code.
optional, string, max chars=20
bank_account[account_type]
For Authorize.net ACH users only. Indicates the type of account.
optional, enumerated stringPossible values are
checkingChecking Account.savingsSavings Account.business_checkingBusiness Checking Account.
bank_account[account_holder_type]
For Stripe ACH users only. Indicates the account holder type.
optional, enumerated stringPossible values are
individualIndividual.companyCompany.
bank_account[echeck_type]
For Authorize.net ACH users only. Indicates the type of eCheck.
optional, enumerated stringPossible values are
webPayment Authorization obtained from the customer via the internet.ppdPayment Authorization is prearranged between the customer and the merchant.ccdPayment Authorization agreement from the corporate customer is required. Applicable for business_checking account_type.
bank_account[issuing_country]
2-letter(alpha2) ISO country code. Required when local bank details are provided, and not IBAN.
optional, string, max chars=50
bank_account[swedish_identity_number]
For GoCardless Autogiro users only. The civic/company number (personnummer, samordningsnummer, or organisationsnummer) of the customer. Must be supplied if the customer’s bank account is denominated in Swedish krona (SEK). This field cannot be changed once it has been set.
optional, string, min chars=10, max chars=12
Parameters for payment_method
pass parameters as payment_method[<param name>]
The type of payment method. For more details refer
Update payment method for a customer API under Customer resource.
optional, enumerated stringPossible values are
cardCard based payment including credit cards and debit cards. Details about the card can be obtained from the card resource.paypal_express_checkoutPayments made via PayPal Express Checkout.amazon_paymentsPayments made via Amazon Payments.direct_debitRepresents bank account for which the direct debit or ACH agreement/mandate is created.genericGeneric Payment Method.alipayAlipay Payments.unionpayUnionPay Payments.apple_payApple Pay Payments.wechat_payWeChat Pay Payments.idealiDEAL Payments.google_payGoogle Pay Payments.sofortSofort Payments.bancontactBancontact Card Payments.giropaygiropay Payments.dotpayDotpay Payments.
Show all values[+]
payment_method[gateway_account_id]
The gateway account in which this payment source is stored.
optional, string, max chars=50
payment_method[reference_id]
The reference id. In the case of Amazon and PayPal this will be the
billing agreement id. For GoCardless direct debit this will be 'mandate id'. In the case of card this will be the identifier provided by the gateway/card vault for the specific payment method resource.
Note: This is not the one-time temporary token provided by gateways like Stripe.
For more details refer
Update payment method for a customer API under Customer resource.
optional, string, max chars=200
payment_method[tmp_token]
Single-use tokens created by payment gateways. In Stripe, a single-use token is created for Apple Pay Wallet, card details or direct debit. In Braintree, a nonce is created for Apple Pay Wallet, PayPal, or card details. In Authorize.Net, a nonce is created for card details. In Adyen, an encrypted data is created from the card details.
required if reference_id not provided, string, max chars=65k
payment_method[issuing_country]
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
Identifier for PaymentIntent generated by Chargebee.js. Applicable only when you are using Chargebee.js for completing the 3DS flow. The PaymentIntent should be in 'authorized' state while passing it here. You need not pass other PaymentIntent parameters if this is passed.
optional, string, max chars=150
payment_intent[gateway_account_id]
The gateway account used for performing the 3DS flow.
required if payment intent token provided, string, max chars=50
Identifier for 3DS transaction/verification object at the gateway. Can be passed only after successfully completing the 3DS flow. Refer
3DS implementation in Chargebee to find out the gateway-specific gw_token format. Applicable when you are using gateway APIs directly for completing the 3DS flow.
optional, string, max chars=65k
payment_intent[reference_id]
Identifier for Braintree permanent token. Applicable when you are using Braintree APIs for completing the 3DS flow.
optional, string, max chars=65k
payment_intent[additional_info]
Applicable only for Braintree gateway. Can be used only for Braintree’s
Advance Fraud Management feature. Pass a stringified JSON containing the
device_session_id
and
fraud_merchant_id
as an input to
fingerprint
. Here’s a
sample to it.
optional, jsonobject
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
Identifier of the addon. Multiple addons can be passed.
optional, string, max chars=100
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
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
addons[quantity_in_decimal][0..n]
The decimal representation of the quantity of the
non-recurring addon. Provide the value in major units of the currency. Must be provided when the addon is quantity-based. This parameter can only be passed when
multi-decimal pricing is enabled.
optional, string, max chars=33
addons[unit_price_in_decimal][0..n]
The time when the service period for the addon starts.
optional, timestamp(UTC) in seconds
The time when the service period for the addon ends.
optional, timestamp(UTC) in seconds
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
The amount to be charged.
optional, in cents, min=1
charges[amount_in_decimal][0..n]
The decimal representation of the amount for the
one-time charge. Provide the value in major units of the currency. Can be provided only when
multi-decimal pricing is enabled.
optional, string, max chars=33
charges[description][0..n]
Description for this charge.
optional, string, max chars=250
charges[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 stringPossible 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
The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds
Set as false
if the charge is non-taxable.
optional, boolean, default=true
charges[tax_profile_id][0..n]
Tax profile of the charge.
optional, string, max chars=50
charges[avalara_tax_code][0..n]
The Avalara tax codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
AvaTax for Sales integration.
optional, string, max chars=50
charges[taxjar_product_code][0..n]
The TaxJar product codes to which items are mapped to should be provided here. Applicable only if you use Chargebee's
TaxJar integration.
optional, string, max chars=50
Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]
notes_to_remove[entity_type][0..n]
Type of entity to which the note belongs. To remove the general note, use the remove_general_note parameter.
optional, enumerated stringPossible values are
planEntity that represents a plan.addonEntity that represents an addon.customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.
notes_to_remove[entity_id][0..n]
Unique identifier of the
note.
optional, string, max chars=100
Resource object representing invoice.
always returned
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/charge \
-u {site_api_key}:\
-d subscription_id="__test__KyVnHhSBWlaML2hj" \
-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__KyVnHhSBWlaML2hj" \
-d amount=1000 \
-d description="Support Charge"
Sample Response [ JSON ]
Show more...
{"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__XpbBxQiS4HD1QKXn",
"date": 1517429429,
"deleted": false,
"due_date": 1517429429,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__18",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD1QKXn",
"date_from": 1517429429,
"date_to": 1517429429,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD1TtY2",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "flat_fee",
"quantity": 1,
"subscription_id": "__test__XpbBxQiS4HD1QKXn",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 1000
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 1000,
"applied_at": 1517429429,
"txn_amount": 1000,
"txn_date": 1517429429,
"txn_id": "txn___test__XpbBxQiS4HD1UAY3",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1517429429,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429429000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"subscription_id": "__test__XpbBxQiS4HD1QKXn",
"tax": 0,
"term_finalized": true,
"total": 1000,
"updated_at": 1517429429,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/charge
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
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
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
The amount to be charged.
optional, in cents, min=1
The decimal representation of the amount for the
one-time charge. Provide the value in major units of the currency. Can be provided only when
multi-decimal pricing is enabled.
optional, string, max chars=33
Description for this charge.
required, string, max chars=250
The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds
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
Indicates the type of sale carried out. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible 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.
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
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
Purchase Order Number for this invoice.
optional, string, max chars=100
Payment source to be used for this payment.
optional, string, max chars=40
Resource object representing invoice.
always returned
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/charge_addon \
-u {site_api_key}:\
-d subscription_id="__test__XpbBxQiS4HD1ImXT" \
-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__XpbBxQiS4HD1ImXT" \
-d addon_id="non_recurring_addon" \
-d addon_unit_price=2000 \
-d addon_quantity=2
Sample Response [ JSON ]
Show more...
{"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__XpbBxQiS4HD1ImXT",
"date": 1517429428,
"deleted": false,
"due_date": 1517429428,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__16",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 4000,
"customer_id": "__test__XpbBxQiS4HD1ImXT",
"date_from": 1517429428,
"date_to": 1517429428,
"description": "non_recurring_addon",
"discount_amount": 0,
"entity_id": "non_recurring_addon",
"entity_type": "addon",
"id": "li___test__XpbBxQiS4HD1MQXi",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 2,
"subscription_id": "__test__XpbBxQiS4HD1ImXT",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 2000
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 4000,
"applied_at": 1517429428,
"txn_amount": 4000,
"txn_date": 1517429428,
"txn_id": "txn___test__XpbBxQiS4HD1MkXj",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 4000,
"object": "invoice",
"paid_at": 1517429428,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429428000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 4000,
"subscription_id": "__test__XpbBxQiS4HD1ImXT",
"tax": 0,
"term_finalized": true,
"total": 4000,
"updated_at": 1517429428,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/charge_addon
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
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
The ID of the non-recurring addon to be charged.
required, string, max chars=100
The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
addon_quantity_in_decimal
optional, string, max chars=33
addon_unit_price_in_decimal
Addon Amount in Decimal.
optional, string, max chars=33
The time when the service period for the addon starts.
optional, timestamp(UTC) in seconds
The time when the service period for the addon ends.
optional, timestamp(UTC) in seconds
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
Purchase Order Number for this invoice.
optional, string, max chars=100
Payment source to be used for this payment.
optional, string, max chars=40
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__38/stop_dunning \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__38/stop_dunning \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"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__XpbBxViS4HD5Bt6p",
"date": 1594073443,
"deleted": false,
"due_date": 1594073443,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073444,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD5MK7N",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"dunning_status": "stopped",
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__38",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__XpbBxViS4HD5Bt6p",
"date_from": 1594073443,
"date_to": 1596751843,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD5Lx7M",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD5Bt6p",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1594073444,
"txn_amount": 895,
"txn_date": 1594073444,
"txn_id": "txn___test__XpbBxViS4HD5MK7N",
"txn_status": "failure"
},
{..}
],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429444000,
"round_off_amount": 0,
"status": "not_paid",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD5Bt6p",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429444,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/stop_dunning
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
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__XpbBxQiS4HD1nWYL" \
-d subscription_id="__test__XpbBxQiS4HD1nWYL" \
-d date=1517429430 \
-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]=1517429430 \
-d line_items[date_to][1]=1519848630 \
-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__XpbBxQiS4HD1nWYL" \
-d subscription_id="__test__XpbBxQiS4HD1nWYL" \
-d date=1517429430 \
-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]=1517429430 \
-d line_items[date_to][1]=1519848630 \
-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 ]
Show more...
{"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__XpbBxQiS4HD1nWYL",
"date": 1517429430,
"deleted": false,
"due_date": 1517429430,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "old_inv_001",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 4900,
"customer_id": "__test__XpbBxQiS4HD1nWYL",
"date_from": 1517429430,
"date_to": 1519848630,
"description": "Support Charge",
"discount_amount": 0,
"entity_id": "plan1",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HD1rZYZ",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxQiS4HD1nWYL",
"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": 1517429430000,
"round_off_amount": 0,
"status": "payment_due",
"sub_total": 4900,
"subscription_id": "__test__XpbBxQiS4HD1nWYL",
"tax": 0,
"term_finalized": true,
"total": 4900,
"updated_at": 1517429430,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/import_invoice
Invoice Number.
required, string, max chars=50
The currency code (ISO 4217 format) for the invoice.
required if Multicurrency is enabled, string, max chars=3
Identifier of the customer for which this invoice needs to be created.
optional, string, max chars=50
If recurring items are present in line items then subscription id is required.
optional, string, max chars=50
Purchase Order Number for this invoice.
optional, string, max chars=100
The price type of the invoice.
optional, enumerated string, default=tax_exclusivePossible values are
tax_exclusiveAll amounts in the document are exclusive of tax.tax_inclusiveAll amounts in the document are inclusive of tax.
The reason for exempting the invoice from tax. (Applicable only for exempted invoices.).
optional, enumerated stringPossible values are
id_exemptThe customer is from a different country than your business and they have a valid VAT number or, the customer is a business entity. (This reason is only applicable when EU VAT or UK VAT is enabled.).customer_exemptThe customer is exempted from tax.exportThe customer is from a non-taxable region or the billing address and shipping address are unavailable.
Vat Number. Required if this invoice is VAT exempted.
optional, string, max chars=20
Date when invoice raised.
required, timestamp(UTC) in seconds
Invoice total amount.
required, in cents, min=0
Round off amount.
optional, in cents, min=-99, max=99
Current status of this invoice.
optional, enumerated string, default=payment_duePossible 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.pending- Product Catalog 2.0: The invoice is
yet to be closed (sent for payment collection). An invoice is generated with this
status
when it has line items that
belong to items that are metered
or when the subscription.create_pending_invoices
attribute is set to true
.
- Product Catalog 1.0:
The invoice is yet to be
closed (sent for payment collection). All invoices are generated with this status
when Metered
Billing is enabled for the site.
.
Invoice Due Date.
optional, timestamp(UTC) in seconds
Invoice net term days.
optional, integer, default=0
If the invoice falls within the subscription current term will be used for proration.
optional, boolean, default=false
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
billing_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=180
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for line_items. Multiple line_items can be passed by specifying unique indices.
pass parameters as line_items[<param name>][<idx:0..n>]
Uniquely identifies a line_item.
optional, string, max chars=40
line_items[date_from][0..n]
Start date of this line item.
optional, timestamp(UTC) in seconds
line_items[date_to][0..n]
End date of this line item.
optional, timestamp(UTC) in seconds
line_items[description][0..n]
Description for this line item.
required, string, max chars=250
line_items[unit_amount][0..n]
Unit amount of the line item.
optional, in cents
line_items[quantity][0..n]
- Product Catalog 2.0: Quantity of the recurring item which is represented by this line item. For
metered
line
items, this value is updated from usages once when the invoice is generated as pending
and finally when the
invoice is closed.
- Product Catalog 1.0: Quantity of the recurring item which is represented by this line item.
.
optional, integer, default=1
Total amount of this lineitem. Not required if the line_items[unit_amount] param is passed.
optional, in cents
line_items[unit_amount_in_decimal][0..n]
The decimal representation of the unit amount of the
line_item
. The value is in major units of the currency. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
line_items[quantity_in_decimal][0..n]
The decimal representation of the quantity of this line_item. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
line_items[amount_in_decimal][0..n]
The decimal representation of the amount for the
line_item
, in major units of the currency. Typically equals to
unit_amount_in_decimal
x
quantity_in_decimal
. Returned when
multi-decimal pricing is enabled.
optional, string, max chars=33
line_items[entity_type][0..n]
Specifies the modelled entity this line item is based on.
optional, enumerated string, default=adhocPossible values are
plan_setupIndicates that this lineitem is based on 'Plan Setup' charge. The 'entity_id' attribute specifies the plan id.planIndicates that this lineitem is based on 'Plan' entity. The 'entity_id' attribute specifies the plan id.addonIndicates that this lineitem is based on 'Addon' entity. The 'entity_id' attribute specifies the addon id.adhocIndicates that this lineitem is not modelled. i.e created adhoc. So the 'entity_id' attribute will be null in this case.
line_items[entity_id][0..n]
The identifier of the modelled entity this line item is based on. Will be null for 'adhoc' entity type.
optional, string, max chars=100
line_items[item_level_discount1_entity_id][0..n]
First item level discount entity id.
optional, string, max chars=50
line_items[item_level_discount1_amount][0..n]
First item level discount amount.
optional, in cents, min=0
line_items[item_level_discount2_entity_id][0..n]
Second item level discount entity id.
optional, string, max chars=50
line_items[item_level_discount2_amount][0..n]
Second item level discount amount.
optional, in cents, min=0
line_items[tax1_name][0..n]
First tax name.
optional, string, max chars=50
line_items[tax1_amount][0..n]
First tax amount.
optional, in cents, min=0
line_items[tax2_name][0..n]
Second tax name.
optional, string, max chars=50
line_items[tax2_amount][0..n]
Second tax amount.
optional, in cents, min=0
line_items[tax3_name][0..n]
Third tax name.
optional, string, max chars=50
line_items[tax3_amount][0..n]
Third tax amount.
optional, in cents, min=0
line_items[tax4_name][0..n]
Fourth tax name.
optional, string, max chars=50
line_items[tax4_amount][0..n]
Fourth tax amount.
optional, in cents, min=0
Parameters for line_item_tiers. Multiple line_item_tiers can be passed by specifying unique indices.
pass parameters as line_item_tiers[<param name>][<idx:0..n>]
line_item_tiers[line_item_id][0..n]
Uniquely identifies a line_item.
required, string, max chars=40
line_item_tiers[starting_unit][0..n]
The lower limit of a range of units for the tier.
optional, integer, min=0
line_item_tiers[ending_unit][0..n]
The upper limit of a range of units for the tier.
optional, integer
line_item_tiers[quantity_used][0..n]
The number of units purchased in a range.
optional, integer, min=0
line_item_tiers[unit_amount][0..n]
The price of the tier if the charge model is a stairtstep
pricing , or the price of each unit in the tier if the charge model is tiered
/volume
pricing.
optional, in cents, min=0
line_item_tiers[starting_unit_in_decimal][0..n]
The decimal representation of the the lowest value of quantity in this tier. This is zero for the lowest tier. For all other tiers, it is the same as
ending_unit_in_decimal
of the next lower tier. Returned only when the
line_items.pricing_model
is
tiered
,
volume
or
stairstep
and
multi-decimal pricing is enabled.
optional, string, max chars=33
line_item_tiers[ending_unit_in_decimal][0..n]
The decimal representation of the highest value of quantity in this tier. This attribute is not applicable for the highest tier. For all other tiers, it must be equal to the
starting_unit_in_decimal
of the next higher tier. Returned only when the
line_items.pricing_model
is
tiered
,
volume
or stairstep and
multi-decimal pricing is enabled.
optional, string, max chars=33
line_item_tiers[quantity_used_in_decimal][0..n]
The decimal representation of the quantity purchased from this tier. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=33
line_item_tiers[unit_amount_in_decimal][0..n]
The decimal representation of the per-unit price for the tier when the
pricing_model
is
tiered
or
volume
. When the
pricing_model
is
stairstep
, it is the decimal representation of the total price for
line_item
. The value is in major units of the currency. Returned when the
line_item
is quantity-based and
multi-decimal pricing is enabled.
optional, string, max chars=40
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 line item.
required, enumerated stringPossible 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
Discount amount.
required, in cents, min=0
Parameters for taxes. Multiple taxes can be passed by specifying unique indices.
pass parameters as taxes[<param name>][<idx:0..n>]
The name of the tax applied.
required, string, max chars=100
The rate of tax used to calculate tax amount.
required, double, default=0.0, min=0.0, max=100.0
Total tax amount charged for this invoice.
optional, in cents, min=0
Description of tax.
optional, string, max chars=50
The type of tax jurisdiction.
optional, enumerated string, default=otherPossible 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.
The name of the tax jurisdiction.
optional, string, max chars=250
The tax jurisdiction code.
optional, string, max chars=250
Parameters for payments. Multiple payments can be passed by specifying unique indices.
pass parameters as payments[<param name>][<idx:0..n>]
Payment made for this invoice.
required, in cents, min=1
payments[payment_method][0..n]
Mode of payment.
required, enumerated stringPossible values are
cashCash.checkCheck.bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
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
Parameters for notes. Multiple notes can be passed by specifying unique indices.
pass parameters as notes[<param name>][<idx:0..n>]
Type of entity to which the note belongs. .
optional, enumerated stringPossible values are
planEntity that represents a plan.addonEntity that represents an addon.couponEntity that represents a coupon.
Id of the mentioned entity type.
optional, string, max chars=50
Actual note.
optional, string, max chars=2000
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 ]
Show more...
{"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__XpbBxViS4HD07H2t",
"date": 1594073424,
"deleted": false,
"due_date": 1594073424,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073425,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD0Rx3R",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"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,
"customer_id": "__test__XpbBxViS4HD07H2t",
"date_from": 1594073424,
"date_to": 1596751824,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD0RI3Q",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD07H2t",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1517429426,
"txn_amount": 895,
"txn_date": 1517429425,
"txn_id": "txn___test__XpbBxQiS4HD0aIWV",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"object": "invoice",
"paid_at": 1517429426,
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429426000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD07H2t",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429426,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/apply_payments
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Parameters for transactions. Multiple transactions can be passed by specifying unique indices.
pass parameters as transactions[<param name>][<idx: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
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 ]
Show more...
{"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 1000,
"amount_paid": 0,
"amount_to_collect": 1000,
"applied_credits": [
{
"applied_amount": 1000,
"applied_at": 1517429423,
"cn_create_reason_code": "Service Unsatisfactory",
"cn_date": 1517429423,
"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__XpbBxQiS4HCzzMVt",
"date": 1517429423,
"deleted": false,
"due_date": 1517429423,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__6",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 2000,
"customer_id": "__test__XpbBxQiS4HCzzMVt",
"date_from": 1517429423,
"date_to": 1517429423,
"description": "Service Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD03vWB",
"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": 1517429423000,
"round_off_amount": 0,
"status": "not_paid",
"sub_total": 2000,
"tax": 0,
"term_finalized": true,
"total": 2000,
"updated_at": 1517429423,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/apply_credits
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Parameters for credit_notes. Multiple credit_notes can be passed by specifying unique indices.
pass parameters as credit_notes[<param name>][<idx: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
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 ]
Show more...
{
"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__XpbBxQiS4HCzzMVt",
"date": 1517429423,
"deleted": false,
"due_date": 1517429423,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__5",
"is_gifted": false,
"issued_credit_notes": [
{
"cn_create_reason_code": "Service Unsatisfactory",
"cn_date": 1517429423,
"cn_id": "__demo_cn__3",
"cn_reason_code": "service_unsatisfactory",
"cn_status": "refunded",
"cn_total": 1000
},
{..}
],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HCzzMVt",
"date_from": 1517429423,
"date_to": 1517429423,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD015W0",
"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": 1517429423,
"txn_amount": 1000,
"txn_date": 1517429423,
"txn_id": "txn___test__XpbBxQiS4HD01NW1",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1517429423,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429423000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"tax": 0,
"term_finalized": true,
"total": 1000,
"updated_at": 1517429423,
"write_off_amount": 0
}},
{..}
],
"next_offset": "[\"1517429428000\",\"234000000383\"]"
}
URL Format GET
https://{site}.chargebee.com/api/v2/invoices
The number of resources to be returned.
optional, integer, default=10, min=1, max=100
Determines your position in the list for pagination. To ensure that the next page is retrieved correctly, always set offset
to the value of next_offset
obtained in the previous iteration of the API call.
optional, string, max chars=1000
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
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
The invoice number. Acts as a identifier for invoice and typically generated sequentially.
Supported operators : is, is_not, starts_with, in, not_in
Example → id[is] = "INVOICE_654"
optional, string filter
subscription_id[<operator>]
To filter based on subscription_id. NOTE: Not to be used if consolidated invoicing is enabled.
Supported operators : is, is_not, starts_with, is_present, in, not_in
Example → subscription_id[is] = "3bdjnDnsdQn"
optional, string filter
The identifier of the customer this invoice belongs to.
Supported operators : is, is_not, starts_with, in, not_in
Example → customer_id[is] = "3bdjnDnsdQn"
optional, string filter
Boolean indicating whether this invoice belongs to a subscription. Possible values are : true, false
Supported operators : is
Example → recurring[is] = "true"
optional, boolean filter
Current status of this invoice. Possible values are : paid, posted, payment_due, not_paid, voided, pending.
Supported operators : is, is_not, in, not_in
Example → status[is] = "paid"
optional, enumerated string filter
The price type of the invoice. Possible values are : tax_exclusive, tax_inclusive.
Supported operators : is, is_not, in, not_in
Example → price_type[is_not] = "tax_exclusive"
optional, enumerated string filter
Date indicated on the invoice. When
metered billing is disabled, this value is the date of generation of the invoice. When metered billing is enabled,
you can select from one of the following:
- date of invoice generation.
- date of closing the invoice
.
Supported operators : after, before, on, between
Example → date[before] = "1394532759"optional, timestamp(UTC) in seconds filter
Timestamp indicating the date & time this invoice got paid.
Supported operators : after, before, on, between
Example → paid_at[after] = "1394532759"
optional, timestamp(UTC) in seconds filter
Invoiced amount in cents.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → total[lte] = "1000"
optional, in cents filter
Total payments received for this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → amount_paid[is] = "800"
optional, in cents filter
amount_adjusted[<operator>]
Total adjustments made against this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → amount_adjusted[is] = "100"
optional, in cents filter
credits_applied[<operator>]
Total credits applied against this invoice.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → credits_applied[is_not] = "100"
optional, in cents filter
Total amount to be collected. This includes invoice's payments in progress.
Supported operators : is, is_not, lt, lte, gt, gte, between
Example → amount_due[gt] = "200"
optional, in cents filter
dunning_status[<operator>]
Current dunning status of the invoice. Possible values are : in_progress, exhausted, stopped, success.
Supported operators : is, is_not, in, not_in, is_present
Example → dunning_status[is_not] = "in_progress"
optional, enumerated string filter
payment_owner[<operator>]
Payment owner of an invoice.
Supported operators : is, is_not, starts_with, in, not_in
Example → payment_owner[is] = "payment_customer"
optional, string filter
To filter based on updated_at
. This attribute will be present only if the resource has been updated after 2016-09-28. It is advisable when using this filter, to pass the sort_by
input parameter as updated_at
for a faster response.
Supported operators : after, before, on, between
Example → updated_at[on] = "1243545465"
optional, timestamp(UTC) in seconds filter
Timestamp indicating the date & time this invoice got voided.
Supported operators : after, before, on, between
Example → voided_at[on] = "1394532759"
optional, timestamp(UTC) in seconds filter
void_reason_code[<operator>]
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive.
Supported operators : is, is_not, starts_with, in, not_in
Example → void_reason_code[is] = "Other"
optional, string filter
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__35 \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__35 \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"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__XpbBxQiS4HD33aaj",
"date": 1517429435,
"deleted": false,
"due_date": 1517429435,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__35",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD33aaj",
"date_from": 1517429435,
"date_to": 1517429435,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD359aq",
"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": 1517429435,
"txn_amount": 1000,
"txn_date": 1517429435,
"txn_id": "txn___test__XpbBxQiS4HD35Qar",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1517429435,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429435000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"tax": 0,
"term_finalized": true,
"total": 1000,
"updated_at": 1517429435,
"write_off_amount": 0
}}
URL Format GET
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}
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.
Related Tutorial
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__36/pdf \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__36/pdf \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"download": {
"download_url": "https://cb-local-downloads.s3.amazonaws.com/yourapp/invoice/__test__XpbBxQiS4HD3vFb7.pdf?response-content-disposition=attachment%3Bfilename%3Dyourapp%2Finvoice%2F__test__XpbBxQiS4HD3vFb7.pdf&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20200709T201043Z&X-Amz-SignedHeaders=host&X-Amz-Expires=-76895940&X-Amz-Credential=AKIAJI4SN7ONHAOGLOGA%2F20200709%2Fus-east-1%2Fs3%2Faws4_request&X-Amz-Signature=4120072325876f249fb620209a1d4570c13f3867d5cc995873bb39e8b3661430",
"object": "download",
"valid_till": 1517429503
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/pdf
Determines the pdf should be rendered as inline or attachment in the browser.
optional, enumerated string, default=attachmentPossible values are
attachmentpdf is rendered as attachment in the browser.inlinepdf is rendered as inline in the browser.
Resource object representing download.
always returned
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \
-u {site_api_key}:\
-d amount=150 \
-d description="$0.05 each for 30 messages"
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__4/add_charge \
-u {site_api_key}:\
-d amount=150 \
-d description="$0.05 each for 30 messages"
Sample Response [ JSON ]
Show more...
{"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 29731,
"amount_paid": 0,
"amount_to_collect": 29731,
"applied_credits": [],
"base_currency_code": "USD",
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HCzob2f",
"date": 1517429423,
"deleted": false,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__4",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 29581,
"customer_id": "__test__XpbBxViS4HCzob2f",
"date_from": 1517429423,
"date_to": 1596658222,
"description": "Basic - Prorated Charges",
"discount_amount": 0,
"entity_id": "basic",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HCztAVi",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HCzob2f",
"tax_amount": 0,
"unit_amount": 29581
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429423000,
"round_off_amount": 0,
"status": "pending",
"sub_total": 29731,
"subscription_id": "__test__XpbBxViS4HCzob2f",
"tax": 0,
"term_finalized": true,
"total": 29731,
"updated_at": 1517429423,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/add_charge
The amount to be charged.
required, in cents, min=1
Detailed description about this lineitem.
required, string, max chars=250
Indicates the type of sale carried out. This is applicable only if you use
Chargebee’s AvaTax for Communications integration.
optional, enumerated stringPossible 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.
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
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
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Identifier of the subscription for which this charge needs to be created. Applicable for consolidated invoice.
optional, string, max chars=50
Parameters for line_item
pass parameters as line_item[<param name>]
The time when the service period for the charge starts.
optional, timestamp(UTC) in seconds
The time when the service period for the charge ends.
optional, timestamp(UTC) in seconds
Resource object representing invoice.
always returned
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_addon_charge \
-u {site_api_key}:\
-d addon_id="non_recurring_addon" \
-d addon_unit_price=495 \
-d addon_quantity=2
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__2/add_addon_charge \
-u {site_api_key}:\
-d addon_id="non_recurring_addon" \
-d addon_unit_price=495 \
-d addon_quantity=2
Sample Response [ JSON ]
Show more...
{"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 30571,
"amount_paid": 0,
"amount_to_collect": 30571,
"applied_credits": [],
"base_currency_code": "USD",
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HCzMb2R",
"date": 1517429422,
"deleted": false,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__2",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 29581,
"customer_id": "__test__XpbBxViS4HCzMb2R",
"date_from": 1517429422,
"date_to": 1596658221,
"description": "Basic - Prorated Charges",
"discount_amount": 0,
"entity_id": "basic",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HCzhcVX",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HCzMb2R",
"tax_amount": 0,
"unit_amount": 29581
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429422000,
"round_off_amount": 0,
"status": "pending",
"sub_total": 30571,
"subscription_id": "__test__XpbBxViS4HCzMb2R",
"tax": 0,
"term_finalized": true,
"total": 30571,
"updated_at": 1517429422,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/add_addon_charge
The ID of the non-recurring addon to be charged.
required, string, max chars=100
The number of addon units to be charged. Mandatory for quantity based addons.
optional, integer, min=1
Amount that will override the Addon's default price.
optional, in cents, min=0
addon_quantity_in_decimal
The decimal representation of the quantity of the
non-recurring addon. Provide the value in major units of the currency. Must be provided when the addon is quantity-based. This parameter can only be passed when
multi-decimal pricing is enabled.
optional, string, max chars=33
addon_unit_price_in_decimal
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Identifier of the subscription for which this addon needs to be created. Applicable for consolidated invoice.
optional, string, max chars=50
Parameters for line_item
pass parameters as line_item[<param name>]
The time when the service period for the addon starts.
optional, timestamp(UTC) in seconds
The time when the service period for the addon ends.
optional, timestamp(UTC) in seconds
Resource object representing invoice.
always returned
Finalizes a pending
invoice. Invoices are created with a pending
status
when Metered Billing is enabled. Ensure that usage charges are added before invoking this API as an invoice without any line_items
cannot be closed. Any refundable_credits
and excess_payments
for the customer are applied to the invoice, and any payment due is collected automatically if auto_collection
is on
for the customer.
Related Tutorial
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__10/close \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__10/close \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 28686,
"amount_paid": 0,
"amount_to_collect": 28686,
"applied_credits": [
{
"applied_amount": 895,
"applied_at": 1517429426,
"cn_create_reason_code": "Subscription Change",
"cn_date": 1517429426,
"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__XpbBxViS4HD0eL3g",
"date": 1517429426,
"deleted": false,
"due_date": 1517429426,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__10",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 29581,
"customer_id": "__test__XpbBxViS4HD0eL3g",
"date_from": 1517429426,
"date_to": 1596658226,
"description": "Basic - Prorated Charges",
"discount_amount": 0,
"entity_id": "basic",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HD0iGWg",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD0eL3g",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 29581
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"next_retry_at": 1517429431,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429426000,
"round_off_amount": 0,
"status": "payment_due",
"sub_total": 29581,
"subscription_id": "__test__XpbBxViS4HD0eL3g",
"tax": 0,
"term_finalized": true,
"total": 29581,
"updated_at": 1517429426,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/close
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Add a
note to this invoice.
optional, string, max chars=2000
Set as
false
to show general notes on the invoice.
General note is a site-level note that’s added to all invoices and configured via the Chargebee UI under
Settings > Configure Chargebee > Invoices, credit notes, and quotes > Invoices.
optional, boolean, default=false
Parameters for notes_to_remove. Multiple notes_to_remove can be passed by specifying unique indices.
pass parameters as notes_to_remove[<param name>][<idx:0..n>]
notes_to_remove[entity_type][0..n]
Type of entity to which the note belongs. To remove the general note, use the remove_general_note parameter.
optional, enumerated stringPossible values are
planEntity that represents a plan.addonEntity that represents an addon.customerEntity that represents a customer.subscriptionEntity that represents a subscription of customer.couponEntity that represents a coupon.
notes_to_remove[entity_id][0..n]
Unique identifier of the
note.
optional, string, max chars=100
Resource object representing invoice.
always returned
Storing card after successful 3DS completion is not supported in this API. Use
create using Payment Intent API under Payment source to store the card after successful 3DS flow completion.
This API can be used to collect the payments for payment_due and not_paid invoices. If no payment method is present for the customer or if the payment is unsuccessful, the corresponding error will be thrown.
Pass authorization_transaction_id to capture the already blocked funds to collect the payment. If the invoice due amount is greater than the authorization the invoice status will be returned as payment_due.
Notes
The authorization transaction will not be captured if the fraud status is found as suspicious. This api will result in invalid_state_for_request error. Read more on
fraud management using Stripe Radar.
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__12/collect_payment \
-X POST \
-u {site_api_key}:\
-d payment_source_id="pm___test__XpbBxQiS4HD14TWv"
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__XpbBxQiS4HD14TWv"
Sample Response [ JSON ]
Show more...
{
"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__XpbBxViS4HD0mk3u",
"date": 1594073426,
"deleted": false,
"due_date": 1594073426,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073427,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD0xF4S",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"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,
"customer_id": "__test__XpbBxViS4HD0mk3u",
"date_from": 1594073426,
"date_to": 1596751826,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD0wq4R",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD0mk3u",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1517429427,
"txn_amount": 895,
"txn_date": 1517429427,
"txn_id": "txn___test__XpbBxQiS4HD15WX1",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"object": "invoice",
"paid_at": 1517429427,
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429427000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD0mk3u",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429427,
"write_off_amount": 0
},
"transaction": {
"amount": 895,
"amount_unused": 0,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HD0mk3u",
"date": 1517429427,
"deleted": false,
"exchange_rate": 1,
"gateway": "chargebee",
"gateway_account_id": "gw___test__XpbBxViS4HCz991g",
"id": "txn___test__XpbBxQiS4HD15WX1",
"id_at_gateway": "cb___test__XpbBxQiS4HD15YX2",
"linked_invoices": [
{
"applied_amount": 895,
"applied_at": 1517429427,
"invoice_date": 1594073426,
"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__XpbBxQiS4HD14TWv",
"resource_version": 1517429427000,
"status": "success",
"subscription_id": "__test__XpbBxViS4HD0mk3u",
"type": "payment",
"updated_at": 1517429427
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/collect_payment
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 to be used for this payment.
optional, string, max chars=40
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Resource object representing invoice.
always returned
Resource object representing transaction.
always returned
To record a offline payment for an invoice.
The invoice status will be marked as 'paid' if its amount due becomes 0 because of this recorded payment.
Note: If the payment transaction amount is more than the invoice due amount, the remaining transaction amount will be added to the customer's Excess Payments balance to be used against other invoices.
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__28/record_payment \
-u {site_api_key}:\
-d comment="Payment received" \
-d transaction[amount]=200 \
-d transaction[payment_method]="bank_transfer" \
-d transaction[date]=1594163432
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__28/record_payment \
-u {site_api_key}:\
-d comment="Payment received" \
-d transaction[amount]=200 \
-d transaction[payment_method]="bank_transfer" \
-d transaction[date]=1594163432
Sample Response [ JSON ]
Show more...
{
"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__XpbBxViS4HD27i5F",
"date": 1594073431,
"deleted": false,
"due_date": 1594073431,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073432,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD2Gt5n",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"dunning_status": "in_progress",
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__28",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__XpbBxViS4HD27i5F",
"date_from": 1594073431,
"date_to": 1596751831,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD2GY5m",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD27i5F",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1594073432,
"txn_amount": 895,
"txn_date": 1594073432,
"txn_id": "txn___test__XpbBxViS4HD2Gt5n",
"txn_status": "failure"
},
{..}
],
"net_term_days": 0,
"next_retry_at": 1594419033,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429432000,
"round_off_amount": 0,
"status": "payment_due",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD27i5F",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429432,
"write_off_amount": 0
},
"transaction": {
"amount": 200,
"amount_unused": 0,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HD27i5F",
"date": 1594163432,
"deleted": false,
"exchange_rate": 1,
"gateway": "not_applicable",
"id": "txn___test__XpbBxQiS4HD2LmZD",
"linked_invoices": [
{
"applied_amount": 200,
"applied_at": 1517429432,
"invoice_date": 1594073431,
"invoice_id": "__demo_inv__28",
"invoice_status": "payment_due",
"invoice_total": 895
},
{..}
],
"linked_refunds": [],
"object": "transaction",
"payment_method": "bank_transfer",
"resource_version": 1517429432000,
"status": "success",
"subscription_id": "__test__XpbBxViS4HD27i5F",
"type": "payment",
"updated_at": 1517429432
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/record_payment
Remarks, if any, on the payment.
optional, string, max chars=300
Parameters for transaction
pass parameters as transaction[<param name>]
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=cardPossible 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
The status of this transaction.
optional, enumerated string, default=successPossible values are
successThe transaction is successful.failureTransaction failed. Refer the 'error_code' and 'error_text' fields to know the reason for failure.
Indicates when this transaction occurred.
optional, timestamp(UTC) in seconds
Error code received from the payment gateway on failure.
optional, string, max chars=100
Error message received from the payment gateway on failure.
optional, string, max chars=65k
Resource object representing invoice.
always returned
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.
Read more on refunds in our docs.
Error will be thrown if you attempt to:
- refund an offline invoice. You can record refund for such invoices using our record refund API.
- refund a fully refunded invoice.
If the refund transaction succeeds, a Credit Note capturing this refund detail will be created for this invoice.
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__30/refund \
-u {site_api_key}:\
-d refund_amount=1000 \
-d credit_note[reason_code]="service_unsatisfactory"
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__30/refund \
-u {site_api_key}:\
-d refund_amount=1000 \
-d credit_note[reason_code]="service_unsatisfactory"
Sample Response [ JSON ]
Show more...
{
"credit_note": {
"allocations": [],
"amount_allocated": 0,
"amount_available": 0,
"amount_refunded": 1000,
"base_currency_code": "USD",
"create_reason_code": "Service Unsatisfactory",
"currency_code": "USD",
"customer_id": "__test__XpbBxQiS4HD2UEZa",
"date": 1517429433,
"deleted": false,
"exchange_rate": 1,
"fractional_correction": 0,
"id": "__demo_cn__7",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD2UEZa",
"date_from": 1517429433,
"date_to": 1517429433,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD2YLZo",
"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": 1517429433,
"txn_amount": 1000,
"txn_date": 1517429433,
"txn_id": "txn___test__XpbBxQiS4HD2Y0Zm",
"txn_status": "success"
},
{..}
],
"object": "credit_note",
"price_type": "tax_exclusive",
"reason_code": "service_unsatisfactory",
"reference_invoice_id": "__demo_inv__30",
"refunded_at": 1517429433,
"resource_version": 1517429433000,
"round_off_amount": 0,
"status": "refunded",
"sub_total": 1000,
"taxes": [],
"total": 1000,
"type": "refundable",
"updated_at": 1517429433
},
"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__XpbBxQiS4HD2UEZa",
"date": 1517429433,
"deleted": false,
"due_date": 1517429433,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__30",
"is_gifted": false,
"issued_credit_notes": [
{
"cn_create_reason_code": "Service Unsatisfactory",
"cn_date": 1517429433,
"cn_id": "__demo_cn__7",
"cn_reason_code": "service_unsatisfactory",
"cn_status": "refunded",
"cn_total": 1000
},
{..}
],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD2UEZa",
"date_from": 1517429433,
"date_to": 1517429433,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD2WHZh",
"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": 1517429433,
"txn_amount": 1000,
"txn_date": 1517429433,
"txn_id": "txn___test__XpbBxQiS4HD2WeZi",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1517429433,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429433000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"tax": 0,
"term_finalized": true,
"total": 1000,
"updated_at": 1517429433,
"write_off_amount": 0
},
"transaction": {
"amount": 1000,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__XpbBxQiS4HD2UEZa",
"date": 1517429433,
"deleted": false,
"exchange_rate": 1,
"gateway": "chargebee",
"gateway_account_id": "gw___test__XpbBxViS4HCz991g",
"id": "txn___test__XpbBxQiS4HD2Y0Zm",
"id_at_gateway": "cb___test__XpbBxQiS4HD2WhZj",
"linked_credit_notes": [
{
"applied_amount": 1000,
"applied_at": 1517429433,
"cn_create_reason_code": "Service Unsatisfactory",
"cn_date": 1517429433,
"cn_id": "__demo_cn__7",
"cn_reason_code": "service_unsatisfactory",
"cn_reference_invoice_id": "__demo_inv__30",
"cn_status": "refunded",
"cn_total": 1000
},
{..}
],
"masked_card_number": "***********0005",
"object": "transaction",
"payment_method": "card",
"payment_source_id": "pm___test__XpbBxQiS4HD2VDZc",
"refunded_txn_id": "txn___test__XpbBxQiS4HD2WeZi",
"resource_version": 1517429433000,
"status": "success",
"type": "refund",
"updated_at": 1517429433
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/refund
Amount to be refunded. If not specified, the entire refundable amount for this invoice will be refunded.
optional, integer, min=1
Comment, if any, on the refund.
optional, string, max chars=300
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
optional, string, max chars=2000
Parameters for credit_note
pass parameters as credit_note[<param name>]
The reason for issuing this Credit Note. The following reason codes are supported now[Deprecated; use the
create_reason_code parameter instead].
optional, enumerated string, default=otherPossible values are
product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]
credit_note[create_reason_code]
Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. The codes are case-sensitive
.
optional, string, max chars=100
Resource object representing invoice.
always returned
Resource object representing transaction.
always returned
Resource object representing credit_note.
optional
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__29/record_refund \
-u {site_api_key}:\
-d transaction[amount]=100 \
-d transaction[payment_method]="bank_transfer" \
-d transaction[date]=1517429433
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__29/record_refund \
-u {site_api_key}:\
-d transaction[amount]=100 \
-d transaction[payment_method]="bank_transfer" \
-d transaction[date]=1517429433
Sample Response [ JSON ]
Show more...
{
"credit_note": {
"allocations": [],
"amount_allocated": 0,
"amount_available": 0,
"amount_refunded": 100,
"base_currency_code": "USD",
"create_reason_code": "Other",
"currency_code": "USD",
"customer_id": "__test__XpbBxQiS4HD2O1ZH",
"date": 1517429433,
"deleted": false,
"exchange_rate": 1,
"fractional_correction": 0,
"id": "__demo_cn__6",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 100,
"customer_id": "__test__XpbBxQiS4HD2O1ZH",
"date_from": 1517429433,
"date_to": 1517429433,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD2RiZV",
"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": 1517429433,
"txn_amount": 100,
"txn_date": 1517429433,
"txn_id": "txn___test__XpbBxQiS4HD2RdZT",
"txn_status": "success"
},
{..}
],
"object": "credit_note",
"price_type": "tax_exclusive",
"reason_code": "other",
"reference_invoice_id": "__demo_inv__29",
"refunded_at": 1517429433,
"resource_version": 1517429433000,
"round_off_amount": 0,
"status": "refunded",
"sub_total": 100,
"taxes": [],
"total": 100,
"type": "refundable",
"updated_at": 1517429433
},
"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__XpbBxQiS4HD2O1ZH",
"date": 1517429432,
"deleted": false,
"due_date": 1517429432,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": true,
"has_advance_charges": false,
"id": "__demo_inv__29",
"is_gifted": false,
"issued_credit_notes": [
{
"cn_create_reason_code": "Other",
"cn_date": 1517429433,
"cn_id": "__demo_cn__6",
"cn_reason_code": "other",
"cn_status": "refunded",
"cn_total": 100
},
{..}
],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD2O1ZH",
"date_from": 1517429432,
"date_to": 1517429432,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD2QFZO",
"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": 1517429432,
"txn_amount": 1000,
"txn_date": 1517429432,
"txn_id": "txn___test__XpbBxQiS4HD2QYZP",
"txn_status": "success"
},
{..}
],
"net_term_days": 0,
"new_sales_amount": 1000,
"object": "invoice",
"paid_at": 1517429432,
"price_type": "tax_exclusive",
"recurring": false,
"resource_version": 1517429433000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 1000,
"tax": 0,
"term_finalized": true,
"total": 1000,
"updated_at": 1517429433,
"write_off_amount": 0
},
"transaction": {
"amount": 100,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__XpbBxQiS4HD2O1ZH",
"date": 1517429433,
"deleted": false,
"exchange_rate": 1,
"gateway": "not_applicable",
"id": "txn___test__XpbBxQiS4HD2RdZT",
"linked_credit_notes": [
{
"applied_amount": 100,
"applied_at": 1517429433,
"cn_create_reason_code": "Other",
"cn_date": 1517429433,
"cn_id": "__demo_cn__6",
"cn_reason_code": "other",
"cn_reference_invoice_id": "__demo_inv__29",
"cn_status": "refunded",
"cn_total": 100
},
{..}
],
"object": "transaction",
"payment_method": "bank_transfer",
"resource_version": 1517429433000,
"status": "success",
"type": "refund",
"updated_at": 1517429433
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/record_refund
Remarks, if any, on the refund.
optional, string, max chars=65k
The Customer Notes to be filled in the Credit Notes created to capture this refund detail.
optional, string, max chars=2000
Parameters for transaction
pass parameters as transaction[<param name>]
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=cardPossible values are
cashCash.checkCheck.chargebackOnly applicable for a transaction of type
= refund
. This value is set by Chargebee when an automated chargeback occurs. You can also set this explicitly when recording a refund.bank_transferBank Transfer.otherPayment Methods other than the above types.
Show all values[+]
transaction[reference_number]
The reference number for this transaction. For example, the check number when
payment_method
=
check
.
optional, string, max chars=100
Indicates when this transaction occurred.
required, timestamp(UTC) in seconds
Parameters for credit_note
pass parameters as credit_note[<param name>]
The reason for issuing this Credit Note. The following reason codes are supported now[Deprecated; use the
create_reason_code parameter instead].
optional, enumerated string, default=otherPossible values are
chargebackCan be set when you are recording your customer Chargebacks.product_unsatisfactoryProduct Unsatisfactory.service_unsatisfactoryService Unsatisfactory.order_changeOrder Change.order_cancellationOrder Cancellation.waiverWaiver.otherCan be set when none of the above reason codes are applicable.
Show all values[+]
credit_note[create_reason_code]
Reason code for creating the credit note. Must be one from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Credit Notes > Create Credit Note. The codes are case-sensitive
.
optional, string, max chars=100
Resource object representing invoice.
always returned
Resource object representing transaction.
always returned
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__34/remove_payment \
-X POST \
-u {site_api_key}:\
-d transaction[id]="txn___test__XpbBxQiS4HD30Sab"
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__34/remove_payment \
-X POST \
-u {site_api_key}:\
-d transaction[id]="txn___test__XpbBxQiS4HD30Sab"
Sample Response [ JSON ]
Show more...
{
"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__XpbBxViS4HD2jz62",
"date": 1594073434,
"deleted": false,
"due_date": 1594073434,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073435,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD2sx6a",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"dunning_status": "stopped",
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__34",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__XpbBxViS4HD2jz62",
"date_from": 1594073434,
"date_to": 1596751834,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD2sc6Z",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD2jz62",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1594073435,
"txn_amount": 895,
"txn_date": 1594073435,
"txn_id": "txn___test__XpbBxViS4HD2sx6a",
"txn_status": "failure"
},
{..}
],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429435000,
"round_off_amount": 0,
"status": "posted",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD2jz62",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429435,
"write_off_amount": 0
},
"transaction": {
"amount": 895,
"amount_unused": 895,
"base_currency_code": "USD",
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HD2jz62",
"date": 1517429435,
"deleted": false,
"exchange_rate": 1,
"gateway": "chargebee",
"gateway_account_id": "gw___test__XpbBxViS4HCz991g",
"id": "txn___test__XpbBxQiS4HD30Sab",
"id_at_gateway": "cb___test__XpbBxQiS4HD30Vac",
"linked_invoices": [],
"linked_refunds": [],
"masked_card_number": "***********0005",
"object": "transaction",
"payment_method": "card",
"payment_source_id": "pm___test__XpbBxQiS4HD2zdaV",
"resource_version": 1517429435000,
"status": "success",
"type": "payment",
"updated_at": 1517429435
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/remove_payment
Parameters for transaction
pass parameters as transaction[<param name>]
Uniquely identifies the transaction.
required, string, max chars=40
Resource object representing invoice.
always returned
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__32/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__32/remove_credit_note \
-X POST \
-u {site_api_key}:\
-d credit_note[id]="__demo_cn__8"
Sample Response [ JSON ]
Show more...
{
"credit_note": {
"allocations": [],
"amount_allocated": 0,
"amount_available": 1000,
"amount_refunded": 0,
"base_currency_code": "USD",
"create_reason_code": "Service Unsatisfactory",
"currency_code": "USD",
"customer_id": "__test__XpbBxQiS4HD2awZt",
"date": 1517429433,
"deleted": false,
"exchange_rate": 1,
"fractional_correction": 0,
"id": "__demo_cn__8",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 1000,
"customer_id": "__test__XpbBxQiS4HD2awZt",
"date_from": 1517429433,
"date_to": 1517429433,
"description": "Support Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD2dwa6",
"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__31",
"resource_version": 1517429434000,
"round_off_amount": 0,
"status": "refund_due",
"sub_total": 1000,
"taxes": [],
"total": 1000,
"type": "refundable",
"updated_at": 1517429434
},
"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__XpbBxQiS4HD2awZt",
"date": 1517429433,
"deleted": false,
"due_date": 1517429433,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__32",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 2000,
"customer_id": "__test__XpbBxQiS4HD2awZt",
"date_from": 1517429433,
"date_to": 1517429433,
"description": "Service Charge",
"discount_amount": 0,
"entity_type": "adhoc",
"id": "li___test__XpbBxQiS4HD2f9aB",
"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": 1517429434000,
"round_off_amount": 0,
"status": "not_paid",
"sub_total": 2000,
"tax": 0,
"term_finalized": true,
"total": 2000,
"updated_at": 1517429434,
"write_off_amount": 0
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/remove_credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
Credit-note id.
required, string, max chars=50
Resource object representing invoice.
always returned
Resource object representing credit_note.
always returned
Voids the specified invoice. Any payments must be removed from the invoice before voiding it.
- Any promotional credits or credit notes applied to the invoice are removed.
- If an invoice for the current term of a subscription is voided and the subscription is changed later with
proration
enabled, no prorated credits are issued.
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__42/void \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__42/void \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 29581,
"amount_paid": 0,
"amount_to_collect": 29581,
"applied_credits": [],
"base_currency_code": "USD",
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HD5hR8P",
"date": 1517429445,
"deleted": false,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__42",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 29581,
"customer_id": "__test__XpbBxViS4HD5hR8P",
"date_from": 1517429445,
"date_to": 1596658245,
"description": "Basic - Prorated Charges",
"discount_amount": 0,
"entity_id": "basic",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HD5kMbA",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD5hR8P",
"tax_amount": 0,
"unit_amount": 29581
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429445000,
"round_off_amount": 0,
"status": "voided",
"sub_total": 29581,
"subscription_id": "__test__XpbBxViS4HD5hR8P",
"tax": 0,
"term_finalized": true,
"total": 29581,
"updated_at": 1517429445,
"voided_at": 1517429445,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/void
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Reason code for voiding the invoice. Select from a list of reason codes set in the Chargebee app in Settings > Configure Chargebee > Reason Codes > Invoices > Void invoice. Must be passed if set as mandatory in the app. The codes are case-sensitive.
optional, string, max chars=100
Resource object representing invoice.
always returned
This API writes off an Invoice.
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__44/write_off \
-X POST \
-u {site_api_key}:
copy
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__44/write_off \
-X POST \
-u {site_api_key}:
Sample Response [ JSON ]
Show more...
{
"credit_note": {
"allocations": [
{
"allocated_amount": 895,
"allocated_at": 1517429446,
"invoice_date": 1594073446,
"invoice_id": "__demo_inv__44",
"invoice_status": "paid"
},
{..}
],
"amount_allocated": 895,
"amount_available": 0,
"amount_refunded": 0,
"base_currency_code": "USD",
"create_reason_code": "Write Off",
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HD5nq8d",
"date": 1517429446,
"deleted": false,
"exchange_rate": 1,
"fractional_correction": 0,
"id": "__demo_cn__10",
"line_item_discounts": [],
"line_item_taxes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__XpbBxViS4HD5nq8d",
"date_from": 1517429446,
"date_to": 1517429446,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HD61MbL",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD5nq8d",
"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__44",
"refunded_at": 1517429446,
"resource_version": 1517429446000,
"round_off_amount": 0,
"status": "adjusted",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD5nq8d",
"taxes": [],
"total": 895,
"type": "adjustment",
"updated_at": 1517429446
},
"invoice": {
"adjustment_credit_notes": [
{
"cn_create_reason_code": "Write Off",
"cn_date": 1517429446,
"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__XpbBxViS4HD5nq8d",
"date": 1594073446,
"deleted": false,
"due_date": 1594073446,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073447,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD5wc9B",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"dunning_status": "stopped",
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__44",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__XpbBxViS4HD5nq8d",
"date_from": 1594073446,
"date_to": 1596751846,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD5wI9A",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD5nq8d",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1594073447,
"txn_amount": 895,
"txn_date": 1594073447,
"txn_id": "txn___test__XpbBxViS4HD5wc9B",
"txn_status": "failure"
},
{..}
],
"net_term_days": 0,
"object": "invoice",
"paid_at": 1517429446,
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429446000,
"round_off_amount": 0,
"status": "paid",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD5nq8d",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429446,
"write_off_amount": 895
}
}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/write_off
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Resource object representing invoice.
always returned
Resource object representing credit_note.
always returned
Deletes the specified invoice. Any payments must be removed from the invoice before deleting it.
- Any promotional credits or credit notes applied to the invoice are removed.
- If an invoice for the current term of a subscription is deleted and the subscription is changed later with
proration
enabled, no prorated credits are issued.
Sample Request
curl https://{site}.chargebee.com/api/v2/invoices/__demo_inv__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 ]
Show more...
{"invoice": {
"adjustment_credit_notes": [],
"amount_adjusted": 0,
"amount_due": 29581,
"amount_paid": 0,
"amount_to_collect": 29581,
"applied_credits": [],
"base_currency_code": "USD",
"credits_applied": 0,
"currency_code": "USD",
"customer_id": "__test__XpbBxViS4HD1Vm4h",
"date": 1517429429,
"deleted": false,
"dunning_attempts": [],
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__20",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 29581,
"customer_id": "__test__XpbBxViS4HD1Vm4h",
"date_from": 1517429429,
"date_to": 1596658229,
"description": "Basic - Prorated Charges",
"discount_amount": 0,
"entity_id": "basic",
"entity_type": "plan",
"id": "li___test__XpbBxQiS4HD1ZOY7",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD1Vm4h",
"tax_amount": 0,
"unit_amount": 29581
},
{..}
],
"linked_orders": [],
"linked_payments": [],
"net_term_days": 0,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429429000,
"round_off_amount": 0,
"status": "pending",
"sub_total": 29581,
"subscription_id": "__test__XpbBxViS4HD1Vm4h",
"tax": 0,
"term_finalized": true,
"total": 29581,
"updated_at": 1517429429,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/delete
Reason for deleting the invoice. This comment will be added to the subscription entity if the invoice belongs to a subscription. It is added to the customer entity if the invoice is associated only with a customer.
optional, string, max chars=300
Indicates whether to put prorated credits back to the subscription or ignore while deleting the invoice.
optional, boolean, default=false
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__40/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__40/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 ]
Show more...
{"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__XpbBxViS4HD5SS7c",
"date": 1594073444,
"deleted": false,
"due_date": 1594073444,
"dunning_attempts": [
{
"attempt": 0,
"created_at": 1594073445,
"dunning_type": "auto_collect",
"transaction_id": "txn___test__XpbBxViS4HD5bD8A",
"txn_amount": 895,
"txn_status": "failure"
},
{..}
],
"dunning_status": "in_progress",
"exchange_rate": 1,
"first_invoice": false,
"has_advance_charges": false,
"id": "__demo_inv__40",
"is_gifted": false,
"issued_credit_notes": [],
"line_items": [
{
"amount": 895,
"customer_id": "__test__XpbBxViS4HD5SS7c",
"date_from": 1594073444,
"date_to": 1596751844,
"description": "No Trial",
"discount_amount": 0,
"entity_id": "no_trial",
"entity_type": "plan",
"id": "li___test__XpbBxViS4HD5as89",
"is_taxed": false,
"item_level_discount_amount": 0,
"object": "line_item",
"pricing_model": "per_unit",
"quantity": 1,
"subscription_id": "__test__XpbBxViS4HD5SS7c",
"tax_amount": 0,
"tax_exempt_reason": "tax_not_configured",
"unit_amount": 895
},
{..}
],
"linked_orders": [],
"linked_payments": [
{
"applied_amount": 895,
"applied_at": 1594073445,
"txn_amount": 895,
"txn_date": 1594073445,
"txn_id": "txn___test__XpbBxViS4HD5bD8A",
"txn_status": "failure"
},
{..}
],
"net_term_days": 0,
"next_retry_at": 1594419046,
"object": "invoice",
"price_type": "tax_exclusive",
"recurring": true,
"resource_version": 1517429445000,
"round_off_amount": 0,
"status": "payment_due",
"sub_total": 895,
"subscription_id": "__test__XpbBxViS4HD5SS7c",
"tax": 0,
"term_finalized": true,
"total": 895,
"updated_at": 1517429445,
"write_off_amount": 0
}}
URL Format POST
https://{site}.chargebee.com/api/v2/invoices/{invoice_id}/update_details
VAT/ Tax registration number of the customer.
Learn more.
optional, string, max chars=20
Purchase Order Number for this invoice.
optional, string, max chars=100
An internal
comment to be added for this operation, to the invoice. This comment is displayed on the Chargebee UI. It is not displayed on any customer-facing
Hosted Page or any document such as the
Invoice PDF.
optional, string, max chars=300
Parameters for billing_address
pass parameters as billing_address[<param name>]
billing_address[first_name]
The first name of the billing contact.
optional, string, max chars=150
billing_address[last_name]
The last name of the billing contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=150
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
billing_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
billing_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
shipping_address[first_name]
The first name of the contact.
optional, string, max chars=150
shipping_address[last_name]
The last name of the contact.
optional, string, max chars=150
The email address.
optional, string, max chars=70
shipping_address[company]
The company name.
optional, string, max chars=250
The phone number.
optional, string, max chars=50
Address line 1.
optional, string, max chars=180
Address line 2.
optional, string, max chars=150
Address line 3.
optional, string, max chars=150
The name of the city.
optional, string, max chars=50
shipping_address[state_code]
The
ISO 3166-2 state/province code without the country prefix. Currently supported for USA, Canada and India. For instance, for Arizona (USA), set
state_code
as
AZ
(not
US-AZ
). For Tamil Nadu (India), set as
TN
(not
IN-TN
). For British Columbia (Canada), set as
BC
(not
CA-BC
).
optional, string, max chars=50
The state/province name. Is set by Chargebee automatically for US, Canada and India If state_code
is provided.
optional, string, max chars=50
Zip or Postal code.
optional, string, max chars=20
shipping_address[country]
shipping_address[validation_status]
The address verification status.
optional, enumerated string, default=not_validatedPossible values are
not_validatedAddress is not yet validated.validAddress was validated successfully.partially_validAddress is verified but only partially.invalidAddress is invalid.
Resource object representing invoice.
always returned