Introducing the Better Auth Chargebee plugin: Use it to handle subscriptions, billing, and auth seamlessly.
Chargebeechargebee API

Import invoice

Idempotency Supported

Imports an invoice into Chargebee Billing.

Use this API to import invoices from your other billing or accounting system into Chargebee Billing. You can import both current-term and historical invoices.

Prerequisites & Constraints

  • At least one line_items entry is required to import an invoice.
  • taxes must not be provided when status is pending.

Impacts

RevenueStory

Accounting Integrations

Implementation Notes

  • If discounts are present on the invoice, then the following parameters must be passed:
    • discounts[entity_type][]
    • discounts[amount][]
    • discounts[line_item_id][i] if discounts[entity_type][i] is item_level_coupon or document_level_coupon.
  • If taxes are present on the invoice, then the following parameters must be passed:
    • taxes[name][]
    • taxes[rate][]
    • line_items[tax*_name][]
    • line_items[tax*_amount][]

Sample Request

Sample Result[JSON]

URL Format

POST https://[site].chargebee.com/api/v2/invoices/import_invoice

Input Parameters

id
required, string, max chars=50

The invoice ID (also known as the invoice number). Must be unique so that it does not conflict with any existing invoice.id.

currency_code
required if Multicurrency is enabled, string, max chars=3

The currency code (ISO 4217 format) for the invoice.

Prerequisite
  • currency_code must be one of your site's configured currencies.
customer_id
optional, string, max chars=50

Identifier of the customer resource to which this invoice belongs.

Required if
  • customer_id is required when line_items is provided.
Constraints
  • customer_id is required when subscription_id is not provided.
  • If subscription_id is provided, for regular subscriptions customer_id must match the subscription's customer.
subscription_id
optional, string, max chars=50

The ID of the subscription resource to which this invoice belongs.

Required if
  • subscription_id is required when the invoice is a recurring invoice and line_items[subscription_id] is not provided.
Constraint
  • subscription_id is required when customer_id is not provided.
po_number
optional, string, max chars=100

Purchase Order Number for this invoice.

price_type
optional, enumerated string, default=tax_exclusive

The price type of the invoice.

Enum Values
tax_exclusive

All amounts in the document are exclusive of tax.

tax_inclusive

All amounts in the document are inclusive of tax.

tax_override_reason
optional, enumerated string

The reason for exempting the invoice from tax. (Applicable only for exempted invoices.).

Constraint
  • tax_override_reason must not be provided when status is pending.
Enum Values
id_exempt

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

The customer is exempted from tax.

export

The customer is from a non-taxable region or the billing address and shipping address are unavailable.

vat_number
optional, string, max chars=20

Vat Number. Required if this invoice is VAT exempted.

Required if
  • vat_number is required when tax_override_reason is id_exempt.
vat_number_prefix
optional, string, max chars=10

An overridden value for the first two characters of the full VAT number. Only applicable specifically for customers with billing_address

country as XI (which is United Kingdom - Northern Ireland ).

When you have enabled EU VAT in 2021 or have manually enabled the Brexit configuration, you have the option of setting billing_address

country as XI. That's the code for United Kingdom - Northern Ireland. The first two characters of the VAT number in such a case is XI by default. However, if the VAT number was registered in UK, the value should be GB. Set vat_number_prefix to GB for such cases.

Constraint
  • billing_address.country is required to provide vat_number_prefix.
date
required, timestamp(UTC) in seconds

Date when invoice raised.

Constraint
  • date must not be in the future.
total
required, in cents, min=0

Invoice total amount.

Constraints
  • total must equal the sum of all line_items[amount][], taxes[amount][], and round_off_amount, less any discounts[amount][].
  • status cannot be payment_due, posted, or not_paid when the total payment amount equals total.
round_off
optional, in cents, min=-99, max=99

Round off amount.

Constraint
  • round_off is not supported when your site's base currency is a zero-decimal currency.
status
optional, enumerated string

Current status of this invoice.

Prerequisite
  • Metered Billing must be enabled for your site to import an invoice with status set to pending.
Constraint
  • Invoice status 'posted' is not supported for non-recurring invoices unless payment terms for one-time invoices is enabled. Contact Support to enable this feature.
Enum Values
paid

Indicates a paid invoice.

posted

Indicates the payment is not yet collected and will be in this state till the due date to indicate the due period.

payment_due

Indicates the payment is not yet collected and is being retried as per retry settings.

not_paid

Indicates the payment is not made and all attempts to collect is failed.

voided

Indicates a voided invoice.

pending

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_invoicesattribute is set to true. 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.

voided_at
optional, timestamp(UTC) in seconds

Timestamp indicating the date & time this invoice got voided.

Required if
  • voided_at is required when status is voided.
Constraints
  • voided_at must not be in the future.
  • voided_at must not be earlier than date.
void_reason_code
optional, string, max chars=100

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.

is_written_off
optional, boolean, default=false

If is_written_off is true then the invoice is written off.

Constraint
  • is_written_off cannot be true when status is voided.
write_off_amount
optional, in cents, default=0, min=0

Amount written off against this invoice. If this value is not present then the due amount of the invoice will be written off.

Constraint
  • status cannot be payment_due, posted, or not_paid when the total payment amount plus write_off_amount equals total.
write_off_date
optional, timestamp(UTC) in seconds

The date on which the write_off invoice has occurred. This is a mandatory field if is_written_off is true. The same date reflects on the created credit note.

Required if
  • write_off_date is required when is_written_off is true.
Constraints
  • write_off_date must be in the past.
  • write_off_date must be after date.
due_date
optional, timestamp(UTC) in seconds

The due date of the invoice.

Required if
  • due_date is required when status is posted.
Constraints
  • due_date and net_term_days must be provided together or both omitted.
  • due_date must be a date in the future.
net_term_days
optional, integer, default=0

The number of days from invoice.date until payment for the invoice is due.

Required if
  • net_term_days is required when status is posted.
Constraints
  • net_term_days must be greater than 0.
  • Payment Terms must be enabled for your site to provide due_date and net_term_days.
has_advance_charges
optional, boolean, default=false

Boolean indicating any advance charge is present in this invoice.

Constraint
use_for_proration
optional, boolean, default=false

If the invoice falls within the subscription current term will be used for proration.

credit_note
Parameters for credit_note
pass parameters as credit_note[<param name>]
billing_address
Parameters for billing_address
pass parameters as billing_address[<param name>]
shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
line_items[0..n]
Parameters for line_items. Multiple line_items can be passed by specifying unique indices.
pass parameters as line_items[<param name>][<idx:0..n>]
payment_reference_numbers[0..n]
Parameters for payment_reference_numbers. Multiple payment_reference_numbers can be passed by specifying unique indices.
pass parameters as payment_reference_numbers[<param name>][<idx:0..n>]
line_item_tiers[0..n]
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>]
discounts[0..n]
Parameters for discounts. Multiple discounts can be passed by specifying unique indices.
pass parameters as discounts[<param name>][<idx:0..n>]
taxes[0..n]
Parameters for taxes. Multiple taxes can be passed by specifying unique indices.
pass parameters as taxes[<param name>][<idx:0..n>]
payments[0..n]
Parameters for payments. Multiple payments can be passed by specifying unique indices.
pass parameters as payments[<param name>][<idx:0..n>]
notes[0..n]
Parameters for notes. Multiple notes can be passed by specifying unique indices.
pass parameters as notes[<param name>][<idx:0..n>]
line_item_addresses[0..n]
Parameters for line_item_addresses. Multiple line_item_addresses can be passed by specifying unique indices.
pass parameters as line_item_addresses[<param name>][<idx:0..n>]

Returns

invoice
Invoice object
Resource object representing invoice
credit_note
Credit note object
Resource object representing credit_note