POST /invoices/{invoice-id}/remove_payment

Removes a payment transaction that was applied to an invoice and moves the amount to the customer's excess payments balance.

This API does not refund the payment to the customer. To refund a payment transaction, use one of the following APIs:

For online payments, use Refund a payment.
For offline payments, use Record an offline refund.

Prerequisites & Constraints

The invoice must not have any refunds or refundable credits issued. Specifically, there must be no issued_credit_notes with a cn_status value of refunded or refund_due for the invoice.
The specified transaction must be linked to the invoice. It must match one of the linked_payments[].txn_id for the invoice.
The status of the transaction must be success, in_progress, or needs_attention.

Impacts

Invoice amount due

The amount_due on the invoice increases by the amount of the removed payment.

Invoice status

If the invoice status was payment_due, not_paid, or posted, the status does not change after a payment is removed.
If the invoice status was paid:
- The status changes to posted if the due_date is in the future.
- The status changes to payment_due if the due_date is in the past and auto_collection is off, or if auto_collection is on and dunning is in progress for the invoice.
- The status changes to not_paid if the due date is in the past, auto_collection is on, and dunning was not in progress for the invoice.

Transaction

The amount_unused on the transaction increases by the amount of the removed payment.

Customer excess payments balance

The customer's excess_payments balance increases by the amount of the removed payment.

Invoice dunning process

If the invoice status is payment_due and dunning was in progress for the invoice, the dunning process continues as configured.

Implementation Notes

Before you call this API, make sure that:

There are no issued_credit_notes with a cn_status value of refunded or refund_due for the invoice.
The specified transaction matches one of the linked_payments[].txn_id for the invoice.
The status of the transaction is success, in_progress, or needs_attention.

FAQs

Can I remove payments from multiple invoices at once?

Yes. To remove payments from multiple invoices in bulk, go to Settings > Import > Export Data > Bulk Operation, and select Remove payment from Invoice.

How can I track the history of payments removed from invoices?

You can view the history of payments removed from invoices in the Activity Log section of the invoice. The log shows all actions taken, including payments removed.

Servers

{protocol}://{site}.{environment}:{port}/api/v2
{protocol}://{site}-test.{environment}:{port}/api/v2

Path parameters

Name	Type	Required	Description
`invoice-id`	String	Yes

Request headers

Name	Type	Required	Description
`chargebee-request-origin-device`	String	No	The device from which the customer has made the request
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/x-www-form-urlencoded"
`chargebee-event-webhook`	String	No	skip only webhooks Valid values: `"all-disabled"`
`chargebee-business-entity-id`	String	No	If the site has multiple business entities, you can use this custom HTTP header to specify the business entity for which Chargebee should perform the operation.
`chargebee-event-actions`	String	No	skip all actions to be done on the events Valid values: `"all-disabled"`
`chargebee-request-origin-user`	String	No	The email address of your customer/user. Use this when the email address has only ASCII characters.
`chargebee-request-origin-ip`	String	No	The IP address of the customer where the request originated
`chargebee-request-origin-user-encoded`	String	No	The Base64-encoded email address of your customer/user. Use this if the email address has UTF-8 characters. When this header is provided, the header chargebee-request-origin-user is ignored.
`chargebee-event-email`	String	No	skip only emails Valid values: `"all-disabled"`

Request body fields

Name	Type	Required	Description
`transaction`	Object	No	Parameters for transaction
`transaction.id`	String	Yes	Uniquely identifies the transaction.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.