Using AI coding agents like Claude Code or Cursor? Try the official Chargebee Agent Skills to speed up your development.Try now
ChargebeeAPI

Create an invoice

Idempotency Supported

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.

  • 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.
creates an invoice for a one-time charge.

Sample Result[JSON]

URL Format

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

Input Parameters

customer_id
optional, string, max chars=50

Identifier of the customer for which this invoice needs to be created. Should be specified if 'subscription_id' is not specified.

subscription_id
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).

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

The currency code (ISO 4217 format) of the invoice amount.

invoice_date
optional, timestamp(UTC) in seconds

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

invoice_note
optional, string, max chars=2000

A note for this particular invoice. This, and all other notes for the invoice are displayed on the PDF invoice sent to the customer.

remove_general_note
optional, boolean, default=false

Set as true to remove the general note from this invoice.

po_number
optional, string, max chars=100

Purchase Order Number for this invoice.

coupon_ids
optional, string, max chars=100

List of Coupons to be added.

authorization_transaction_id
optional, string, max chars=40

Authorization transaction to be captured.

payment_source_id
optional, string, max chars=40

Payment source to be used for this payment.

auto_collection
optional, enumerated string

If specified, the customer level auto collection will be overridden.

Enum Values
on

Whenever an invoice is created, an automatic attempt will be made to charge.

off

Whenever an invoice is created as payment due.

token_id
optional, string, max chars=40

Token generated by Chargebee JS representing payment method details.

replace_primary_payment_source
optional, boolean, default=false

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

retain_payment_source
optional, boolean, default=true

Indicates whether the payment source should be retained for the customer.

payment_initiator
optional, enumerated string

The type of initiator to be used for the payment request triggered by this operation.

Enum Values
customer

Pass this value to indicate that the request is initiated by the customer

merchant

Pass this value to indicate that the request is initiated by the merchant

shipping_address
Parameters for shipping_address
pass parameters as shipping_address[<param name>]
statement_descriptor
Parameters for statement_descriptor
pass parameters as statement_descriptor[<param name>]
card
Parameters for card
pass parameters as card[<param name>]
bank_account
Parameters for bank_account
pass parameters as bank_account[<param name>]
payment_method
Parameters for payment_method
pass parameters as payment_method[<param name>]
payment_intent
Parameters for payment_intent
pass parameters as payment_intent[<param name>]
addons[0..n]
Parameters for addons. Multiple addons can be passed by specifying unique indices.
pass parameters as addons[<param name>][<idx:0..n>]
charges[0..n]
Parameters for charges. Multiple charges can be passed by specifying unique indices.
pass parameters as charges[<param name>][<idx:0..n>]
tax_providers_fields[0..n]
Parameters for tax_providers_fields. Multiple tax_providers_fields can be passed by specifying unique indices.
pass parameters as tax_providers_fields[<param name>][<idx:0..n>]
notes_to_remove[0..n]
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>]

Returns

invoice
Invoice object
Resource object representing invoice