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

Apply payments for an invoice

Idempotency Supported
Try in API Explorer

Applies payment to a single invoice. You can either specify individual payment transactions as parameters, or Chargebee applies any available excess payments for that customer. If you specify individual transactions then any un-applied amount in those transactions will be used.

Prerequisites & Constraints

  • The invoice's status must be payment_due, posted, or not_paid.
  • The customer must have excess payments available.

Impacts

Invoice

Invoice's amount_due is updated to reflect the applied payment. If no amount remains, the invoice status becomes paid.

Transactions

When a payment is applied to an invoice, the amount_unused field of the associated transaction(s) is reduced accordingly.

Accounting Integrations

Synchronization to the accounting system will not proceed if the linked transaction contains a surplus balance.

Implementation Notes

Before calling this API, ensure the following:

  • The invoice status is not_paid, payment_due, or posted.
  • Customer has excess_payments .

Sample Request

URL Format

POST https://[site].chargebee.com/api/v2/invoices/{invoice-id}/apply_payments

Input Parameters

comment
optional, string, max chars=300

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 .

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

Returns

invoiceInvoice object
Resource object representing invoice