Skip to main content
POST
cURL
Pass the exact customerId as a URL-encoded query value. Use an adjustment for credits outside a plan or credit pack: a goodwill credit, a support fix, or taking back credits after a refund. The key needs the billing:write permission.
  • Positive credits add a new grant. They never expire unless you set expiresAt, which must be after the customer’s current time.
  • Negative credits remove credits from the customer’s grants in the order requests spend them (plan credits first, then the rest by expiry). An adjustment never takes the balance below zero: asking for more than the balance returns 409 insufficient_credits with the availableCredits you can remove.
  • reason is required and appears on the customer’s page and in billing history, with who made the change (createdBy).
  • idempotencyKey is required, per customer. Retrying with the same key and the same body returns the first adjustment, with the Idempotent-Replayed: true header, and changes nothing. The same key with a different body returns 409 idempotency_key_reused.

​
Grant a payment Ledger didn’t

If a customer paid and Ledger granted no credits (for example, an invoice with tax that Ledger refused), add the credits with stripeInvoiceId, or stripeCheckoutSessionId for a credit pack:
Ledger asks Stripe that the payment exists in this environment (404 stripe_object_not_found otherwise), is paid (409 stripe_object_not_paid) and belongs to this customer (409 stripe_object_not_this_customers). The grant then counts as that payment’s, so the payment can’t be granted again (409 stripe_object_already_granted). Linking needs Stripe connected in this environment (422 stripe_not_ready); if Stripe doesn’t answer, the request returns 502 stripe_unavailable and you can retry with the same key. Unknown customers return 404 customer_not_found.

Authorizations

​
Authorization
string
header
required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Query Parameters

​
customerId
string
required
Required string length: 1 - 255

Body

application/json
​
credits
integer
required

Credits to add (positive) or remove (negative). A removal never takes the balance below zero.

Required range: -1000000000 <= x <= 1000000000
Example:

500

​
reason
string
required

Why the balance changed, for your team. Shown on the customer page and in billing history.

Required string length: 1 - 500
Example:

"Goodwill credit for the Nov 6 outage"

​
idempotencyKey
string
required

Your unique key for this adjustment. Retrying with the same key and body returns the first adjustment; the same key with a different body is refused.

Required string length: 1 - 255
Example:

"goodwill-2026-11-06-user_123"

​
expiresAt
string<date-time>

Added credits only: when they stop counting. Must be in the future. Omit for credits that never expire.

​
stripeInvoiceId
string

Added credits only: the paid Stripe invoice these credits stand in for, when Ledger didn't grant it. Ledger checks it's paid and this customer's, and marks it granted.

Pattern: ^in_[A-Za-z0-9]{1,250}$
Example:

"in_1QxYzExample"

​
stripeCheckoutSessionId
string

Added credits only: the paid credit-pack Checkout Session these credits stand in for. Not with stripeInvoiceId.

Pattern: ^cs_[A-Za-z0-9_]{1,250}$

Response

Credits added or removed. A retry with the same idempotencyKey returns the first adjustment, with the Idempotent-Replayed: true header.

​
customerId
string
required
​
adjustment
object
required
​
availableCredits
integer
required

The customer's balance after the adjustment.

Required range: x >= 0