> ## Documentation Index
> Fetch the complete documentation index at: https://docs.integrateledger.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Balance adjustments

> Add or remove a customer's credits by hand, with a reason, for goodwill credits, support fixes and missed payments.

An adjustment changes a customer's credits outside a plan or credit pack: a goodwill credit after an outage, a support fix, or taking credits back after a refund. For one-off fixes, use **Adjust credits** on the customer's page in the dashboard. From code:

```typescript TypeScript theme={"system"}
await billing.adjustCustomerBalance({
	customerId,
	body: {
		credits: 500,
		reason: "Goodwill for the outage",
		idempotencyKey: `goodwill-${customerId}`,
	},
});
```

```python Python theme={"system"}
billing.adjust_customer_balance(
    customer_id=customer_id,
    credits=500,
    reason="Goodwill for the outage",
    idempotency_key=f"goodwill-{customer_id}",
)
```

* **Positive `credits`** add a new grant that never expires, unless you set `expiresAt`. It's spent after plan credits, alongside packs ([spend order](https://docs.integrateledger.com/concepts/credits.md#spend-order)).
* **Negative `credits`** remove credits in spend order and never take the balance below zero: asking for more returns `409 insufficient_credits` with the `availableCredits` you can remove.
* **`reason` is required.** It shows on the customer's page and in billing history, with who made the change.
* **`idempotencyKey` is required**, per customer. A retry with the same key and body returns the first adjustment and changes nothing; the same key with a different body returns `409 idempotency_key_reused`.

The key needs the `billing:write` permission.

## Grant a payment Ledger didn't

If a customer paid and Ledger granted nothing, for example an invoice with a coupon that Ledger refused, add the credits with the payment's `stripeInvoiceId`, or `stripeCheckoutSessionId` for a pack. Ledger checks with Stripe that the payment is paid and belongs to this customer, then marks it granted so it can't be granted twice (`409 stripe_object_already_granted`). [Adjust a customer's balance](https://docs.integrateledger.com/api-reference/customers/balance-adjustments.md) lists every error.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.