Introducing the Chargebee CLI
chargebee api

Update the overdraft limit

Updates the overdraft limit for a subscription and credit unit.

By default, the overdraft limit for a credit unit is a single, site-wide value applied to every subscription. Use this operation to manually override that default for one subscription_id-unit_id pair — for example, to raise the ceiling for a trusted high-value customer, or to let customers self-configure their own spending limit after credits are granted.

Behavior

  • Applies the new limit synchronously and returns the outcome in the same response — there's no pending or asynchronous state.
  • Rejects the request immediately if the new limit is below what's already committed (used_amount + hold_amount) on the active overdraft balance. The limit isn't scheduled or retried later; the caller must resubmit once the balance permits it.
  • Requires that an overdraft balance already exists for the subscription and credit unit.
  • Leaves the provisioned_balance and the site-level default untouched. Other subscriptions on the same credit unit continue to use the site default until they get their own override.

Usage

Use this operation to raise or lower the overdraft ceiling for a specific subscription without changing the site-wide default — for instance, extending more runway to an enterprise customer, or letting an end customer raise their own limit after receiving promotional credits.

The response echoes the subscription_id, unit_id, and change_reason inputs, and returns the resulting overdraft_balance snapshot as well.

Sample Request

update the overdraft limit

Sample Result[JSON]

URL Format

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

Input Parameters

subscription_id
required, string, max chars=50

A unique, immutable identifier for the subscription whose overdraft limit is being changed.

unit_id
required, string, max chars=50

Identifier of the credit unit linked to the subscription. For example, a credit unit id such as ai_credits.

Prerequisites

An overdraft balance must already exist for this (subscription_id, unit_id) pair.

is_unlimited
required, boolean

Whether the overdraft limit for this credit unit is unlimited.

Behavior

  • When true, requests unlimited overdraft and limit must not be passed.
  • When false, requests a finite overdraft and limit is required.
limit
optional, string, max chars=36

The new maximum overdraft allowed for this credit unit. Pass this value as a decimal string.

Required if

is_unlimited is false.

Constraints

  • Must not be passed when is_unlimited is true.
  • Must be zero or a positive value; negative values are not allowed.
  • Maximum supported value: 9999999999999999999999999.9999999999 (up to 25 digits before the decimal and up to 10 digits after).
  • Must be greater than or equal to the sum of used_amount and hold_amount on the active overdraft balance. Any limit that would drop below the already committed amount is rejected.
change_reason
optional, string, max chars=255

The reason for this overdraft limit change, for your reference. Recorded for audit purposes.

Returns

subscription_id
required, string, max chars=50

A unique, immutable identifier for the subscription whose overdraft limit was changed. Echoes the value passed in the request.

unit_id
required, string, max chars=50

Identifier of the credit unit linked to the subscription. Echoes the value passed in the request.

change_reason
optional, string, max chars=255

The reason for this overdraft limit change. Echoes the value passed in the request. This field is omitted from the response when the request does not include it.

overdraft_balance
required, jsonobject

The resulting overdraft_balance for the subscription and credit unit, reflecting the newly applied limit.