Stripe "customer_balance_transaction" for goodwill credits: keeping the audit trail

TL;DR

A customerbalancetransaction adds a goodwill credit to the customer's Stripe balance, which automatically applies to their next invoice. Always include a clear description and metadata (reason, approver, ticket) because 'goodwill' with no context is an audit finding waiting to happen. Set an internal approval threshold: small credits self-serve, large ones need a manager. The transaction history on the customer is the audit trail, so never adjust balances by hand-editing; every credit is its own transaction record.

The query

Stripe "customer_balance_transaction" for goodwill credits: keeping the audit trail

Use this when

• Granting courtesy credits for service issues
• Goodwill credits that apply to the next invoice
• Audit-proof credit issuance in Stripe

Not for

• Refunding a specific paid invoice (use credit notes)
• Discounting the current invoice only (use coupons)

Steps

1. Confirm the credit amount and the business reason with the ticket or incident.

Expected output: The credit is justified and sized.

1. Create the customerbalancetransaction with a descriptive reason and metadata.

Expected output: The audit trail records who, why, and how much.

1. Get approval per your threshold policy for larger amounts.

Expected output: Big credits have a second pair of eyes.

1. Confirm the next invoice picks up the credit via starting_balance.

Expected output: The customer actually benefits on the next bill.

1. Report credits monthly: total, reasons, approvers.

Expected output: Finance sees the pattern, not just the entries.

Variant phrasings

Stripe customer balance transaction goodwill credit

courtesy credit Stripe audit trail

add credit to customer balance Stripe

Root cause

The balance transaction is append-only history, which is exactly what auditors want: every credit is an immutable record with a reason, unlike editing a balance field which erases the story. Treat credits like cash disbursements in your controls.

Edge cases

• Credits apply to the next invoice automatically; they cannot be earmarked for a specific future invoice
• Negative balances from over-crediting carry forward; review them quarterly

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_cBwlBF6Ewrcej17KWszwcg