Credit transaction history

Uses: Metering & Billing

Movement types

Type	Sign	Description
`funded`	Positive (+)	Recorded when a grant is issued. Represents credit added to the customer’s balance.
`consumed`	Negative (-)	Recorded when credits are applied to a charge.
`expired`	Negative (-)	Recorded when unused credits from a grant pass their expiration date.
`voided`	Negative (-)	Recorded when a grant is voided. Represents the unused credit that was forfeited.

Amounts are expressed from the customer’s perspective.

A funded movement of +100 USD means the customer gained 100 USD in credit.
A consumed movement of -30 USD means 30 USD of credits were applied to reduce a charge.

Movement fields

Each movement in the transaction history includes the following fields:

Field	Description
`id`	The ID of the movement.
`name`, `description`	A display name and optional description for the movement.
`type`	The movement type: `funded`, `consumed`, `expired`, or `voided`.
`amount`	The signed amount of the movement. Positive for funded, negative for consumed, expired, and voided.
`currency`	The currency of the balance the movement affects.
`custom_currency`	A reference to the custom currency. Present only for movements in a custom currency.
`available_balance.before`, `available_balance.after`	The customer’s available credit balance immediately before and after this movement.
`booked_at`	The time the movement takes effect on the balance. Movements are ordered by this time.
`created_at`	The time the movement was recorded.
`labels`	System-set references to related resources, such as `charge_id`, `subscription_id`, and `feature_id`. A `funded` movement for a voided grant carries the label `voided`.

A movement doesn’t carry a grant ID field. To relate movements to a grant or charge, use the charge_id label. On a funded movement, this is the ID of the grant.

Filtering by feature

You can filter the transaction history by product feature using filter[feature_key]. This returns only the transactions relevant to a specific feature, including shared unrestricted credits.

For the full reference on transaction filters, see Feature filters.

Ordering and pagination

Movements are returned in the following stable order:

Newest
Ordered by booked_at
Ordered by created_at
Ordered by ID The API uses cursor-based pagination to ensure consistent results even when new movements are added while you’re paginating.

Use page[size] to set the page size. To fetch the next page, pass the cursor from the previous response’s meta.page.next field as page[after]. To go back, pass meta.page.previous as page[before].

You can also filter the history by movement type with filter[type] and by currency with filter[currency].

Corrections

Movements are immutable and can’t be edited or deleted. Grant amounts must be positive, so you can’t offset a grant with a negative grant.

If a grant was issued for the wrong amount, void it and issue a new grant for the correct amount. For example, if a grant of 100 USD was issued but should have been 80 USD:

In the customer’s Credits tab, open the actions menu of the grant’s funded movement in Transaction History and click Void.
Confirm in the Void Grant dialog. The unused remainder of the grant is forfeited and recorded as a voided movement.
Grant 80 USD of credits.

Keep the following in mind when you void a grant:

Voiding is irreversible.
Only active grants can be voided. You can’t void a grant that is pending, expired, or fully consumed.
Credits already consumed by usage aren’t affected. Only the unused remainder is forfeited.
Voiding doesn’t adjust invoices or payments. If the grant was funded by an invoice, the original invoiced amount may still be collected.

The full history, including the original movement and the void, remains visible in transaction history. This preserves the complete audit trail.

Next Steps

Learn about feature filters

Get started with prepaid credits