Credit Transactions
A Credit Transaction object represents a single entry in a customer's credit ledger. Every time credits are granted, consumed, adjusted, or expire, a new credit transaction is created. This provides a detailed and auditable history of all credit movements.
This API resource allows you to list and retrieve these transactions, which is essential for tracking credit usage, debugging billing issues, and providing customers with a transparent history of their credit balance. For more information on issuing credits, refer to the Credit Grants documentation.
The Credit Transaction Object#
A TCreditTransaction object contains detailed information about a specific credit event.
Attribute | Type | Description |
|---|---|---|
|
| Unique identifier for the credit transaction object. |
|
| The ID of the customer this transaction belongs to. |
|
| The ID of the credit grant that this transaction is part of. |
|
| (Optional) The ID of the meter if the transaction type is |
|
| (Optional) The ID of the subscription associated with this transaction. |
|
| (Optional) The ID of the meter event that triggered this consumption. |
|
| The type of transaction. Can be |
|
| The amount of credit involved in the transaction. This is positive for grants and negative for consumptions or expirations. |
|
| The customer's credit balance after this transaction was processed. |
|
| (Optional) An internal description of the transaction. |
|
|
|
|
| ISO 8601 timestamp for when the object was created. |
|
| ISO 8601 timestamp for when the object was last updated. |
|
| (Optional) A set of key-value pairs that you can attach to an object. |
List all Credit Transactions#
Retrieves a paginated list of credit transactions. You can filter the list based on various parameters such as customer, subscription, or a specific time range.
Parameters
Name | Type | Description |
|---|---|---|
|
| Optional. Filters the list to transactions for a specific customer. |
|
| Optional. Filters the list to transactions associated with a specific subscription. |
|
| Optional. Filters the list to transactions originating from a specific credit grant. |
|
| Optional. Filters the list to consumption transactions from a specific meter. |
|
| Optional. Filters by the source of the transaction. |
|
| Optional. A Unix timestamp to filter for transactions created on or after this time. |
|
| Optional. A Unix timestamp to filter for transactions created on or before this time. |
|
| Optional. A generic search query string. |
|
| Optional. The page number for pagination. Defaults to |
|
| Optional. The number of objects to return per page. Defaults to |
|
| Optional. The sort order for the results, based on |
Returns
Returns a paginated list of credit transaction objects.
import payment from '@blocklet/payment-js';
async function listCreditTransactions(customerId) {
try {
const response = await payment.creditTransactions.list({
customer_id: customerId,
pageSize: 5,
});
console.log(`Found ${response.count} transactions:`);
response.list.forEach(tx => {
console.log(`- ID: ${tx.id}, Type: ${tx.type}, Amount: ${tx.amount}`);
});
} catch (error) {
console.error('Error listing credit transactions:', error.message);
}
}
listCreditTransactions('cus_xxxxxxxxxxxxxx');Example Response
{
"count": 15,
"list": [
{
"id": "ctx_xxxxxxxxxxxxxx",
"customer_id": "cus_xxxxxxxxxxxxxx",
"credit_grant_id": "cg_xxxxxxxxxxxxxx",
"meter_id": "mtr_xxxxxxxxxxxxxx",
"subscription_id": null,
"type": "consumption",
"amount": "-100",
"running_balance": "9900",
"livemode": false,
"created_at": "2023-10-27T10:00:00.000Z",
"customer": {
"id": "cus_xxxxxxxxxxxxxx",
"name": "John Doe",
"email": "john.doe@example.com"
},
"meter": {
"id": "mtr_xxxxxxxxxxxxxx",
"name": "API Calls"
}
}
],
"paging": {
"page": 1,
"pageSize": 5
}
}Retrieve a Credit Transaction#
Retrieves the details of a specific credit transaction by its unique ID.
Parameters
Name | Type | Description |
|---|---|---|
|
| The unique identifier of the credit transaction to retrieve. |
Returns
Returns a single credit transaction object if a valid ID is provided.
import payment from '@blocklet/payment-js';
async function getCreditTransaction(transactionId) {
try {
const transaction = await payment.creditTransactions.retrieve(transactionId);
console.log('Retrieved transaction:', transaction);
} catch (error) {
console.error(`Error retrieving transaction ${transactionId}:`, error.message);
}
}
getCreditTransaction('ctx_xxxxxxxxxxxxxx');Example Response
{
"id": "ctx_xxxxxxxxxxxxxx",
"customer_id": "cus_xxxxxxxxxxxxxx",
"credit_grant_id": "cg_xxxxxxxxxxxxxx",
"type": "consumption",
"amount": "-100",
"running_balance": "9900",
"description": "API call to /data/query",
"livemode": false,
"created_at": "2023-10-27T10:00:00.000Z",
"customer": {
"id": "cus_xxxxxxxxxxxxxx",
"name": "John Doe",
"email": "john.doe@example.com"
},
"creditGrant": {
"id": "cg_xxxxxxxxxxxxxx",
"name": "Initial Grant"
},
"meter": {
"id": "mtr_xxxxxxxxxxxxxx",
"name": "API Calls",
"event_name": "api.call"
}
}Get Usage Summary#
Retrieves a summary of credit usage for a given customer or subscription over a specified period.
Parameters
Name | Type | Description |
|---|---|---|
|
| Optional. The ID of the customer to summarize usage for. |
|
| Optional. The ID of the subscription to summarize usage for. |
|
| Optional. The ID of the credit currency to filter by. |
|
| Optional. The ID of the meter to filter by. |
|
| Optional. A Unix timestamp representing the start of the summary period. |
|
| Optional. A Unix timestamp representing the end of the summary period. |
Returns
Returns a UsageSummary object containing aggregated data about credit consumption.
Attribute | Type | Description |
|---|---|---|
|
| The total quantity of usage consumed. |
|
| The total amount of credits consumed (as a negative value). |
|
| The total number of consumption transactions in the period. |
|
| The filters that were applied to generate this summary. |
import payment from '@blocklet/payment-js';
async function getUsageSummary(customerId) {
try {
const summary = await payment.creditTransactions.summary({
customer_id: customerId,
});
console.log('Usage Summary:', summary);
} catch (error) {
console.error('Error getting usage summary:', error.message);
}
}
getUsageSummary('cus_xxxxxxxxxxxxxx');Example Response
{
"total_quantity": "5000",
"total_credit_amount": "-50.00",
"transaction_count": 50,
"filters": {
"customer_id": "cus_xxxxxxxxxxxxxx"
}
}The Credit Transactions resource provides a complete and auditable log of all credit movements. By using the list, retrieve, and summary methods, you can build transparent billing features and effectively monitor customer credit usage.