Every change to a customer’s credit balance is recorded as a movement in the transaction history. The history is a complete, ordered log of all credit activity for a customer and is the authoritative source for their balance.
Credit transaction history
This feature is currently in Beta and should not be used in a production environment.
Related Documentation
Incompatible with
on-prem
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. One movement per grant drawn from in a single charge. |
expired
|
Negative (-) | Recorded when unused credits from a grant pass their expiration date. |
Amounts are expressed from the customer’s perspective.
- A
fundedmovement of +100 USD means the customer gained 100 USD in credit. - A
consumedmovement 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 |
|---|---|
type
|
The movement type: funded, consumed, or expired.
|
amount
|
The signed amount of the movement. Positive for funded, negative for consumed and expired. |
currency
|
The currency of the movement. |
grant_id
|
The ID of the grant this movement is associated with. |
balance_before
|
The customer’s settled credit balance immediately before this movement. |
balance_after
|
The customer’s settled credit balance immediately after this movement. |
created_at
|
The timestamp at which the movement was recorded. |
metadata
|
Optional key-value metadata attached to the movement. |
Ordering and pagination
Movements are returned in stable insertion order. The API uses cursor-based pagination to ensure consistent results even when new movements are added while you’re paginating.
Pass the cursor from the previous response’s next field to fetch the next page.
Restarting pagination from the beginning always gives results in the same stable order.
Corrections
Movements are immutable and can’t be edited or deleted. If a movement was recorded in error (for example, a grant was issued for the wrong amount), issue a correction by creating a new movement that offsets the error.
For example, if a grant of 100 USD was issued but should have been 80 USD:
- The original
fundedmovement of +100 USD remains in the ledger unchanged. - Issue a new correction grant of -20 USD (or void the original and reissue the correct amount using the appropriate API operation).
The full history, including the original movement and the correction, remains visible in transaction history. This preserves the complete audit trail.