Credit Transactions
Credit Transactions are immutable records tracking the grant, consumption, adjustment, and expiration of credits. They provide a detailed ledger of all credit-related activities for each customer, which is essential for auditing and understanding usage patterns.
Each transaction is linked to a customer and a credit_grant. For more information on how credits are issued, see the Credit Grants documentation. To understand how usage is tracked, refer to Meters and Meter Events.
The Credit Transaction Object#
A credit transaction object contains detailed information about a single credit event.
Attribute | Type | Description |
|---|---|---|
|
| Unique identifier for the credit transaction. |
|
| The ID of the customer associated with this transaction. |
|
| The ID of the credit grant from which this transaction originates. |
|
| (Optional) The ID of the meter that triggered a consumption transaction. |
|
| (Optional) The ID of the subscription related to this transaction. |
|
| (Optional) The ID of the meter event that led to this consumption. |
|
| The type of transaction. Can be |
|
| The amount of credits transacted. This is positive for grants and adjustments that add credit, and negative for consumptions and expirations. |
|
| The credit balance of the grant after this transaction occurred. |
|
| (Optional) An internal description of the transaction. |
|
|
|
|
| The timestamp when the transaction was created (ISO 8601 format). |
|
| The timestamp of the last update (ISO 8601 format). |
|
| (Optional) A set of key-value pairs that you can attach to the object. |
Retrieve a Transaction#
Fetches 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
A TCreditTransactionExpanded object containing full details of the transaction.
Example
async function getCreditTransaction(transactionId) {
try {
const transaction = await payment.creditTransactions.retrieve(transactionId);
console.log('Retrieved Transaction:', transaction);
} catch (error) {
console.error('Error retrieving transaction:', error.message);
}
}
// Replace 'crtrx_xxxxxxxx' with a valid transaction ID
getCreditTransaction('crtrx_xxxxxxxx');Example Response
{
"id": "crtrx_xxxxxxxxxxxxxx",
"customer_id": "cust_xxxxxxxxxxxxxx",
"credit_grant_id": "crg_xxxxxxxxxxxxxx",
"meter_id": "mtr_xxxxxxxxxxxxxx",
"subscription_id": "sub_xxxxxxxxxxxxxx",
"meter_event_id": "mevt_xxxxxxxxxxxxxx",
"type": "consumption",
"amount": "-100",
"running_balance": "900",
"description": "API Call Usage",
"livemode": false,
"created_at": "2023-10-27T10:00:00.000Z",
"updated_at": "2023-10-27T10:00:00.000Z",
"metadata": {}
}List Transactions#
Returns a paginated list of credit transactions. You can filter the list based on various parameters.
Parameters
Name | Type | Description |
|---|---|---|
|
| (Optional) Filter transactions by a specific customer ID. |
|
| (Optional) Filter transactions by a specific subscription ID. |
|
| (Optional) Filter transactions by a specific credit grant ID. |
|
| (Optional) A Unix timestamp to filter for transactions created after this time. |
|
| (Optional) A Unix timestamp to filter for transactions created before this time. |
|
| (Optional) Set to |
|
| (Optional) A search query string for free-text search on relevant fields. |
|
| (Optional) The page number for pagination, starting from 1. |
|
| (Optional) The number of items to return per page. Defaults to 20. |
|
| (Optional) The order in which to sort the results (e.g., |
Returns
A paginated object containing a list of credit transaction objects.
Name | Type | Description |
|---|---|---|
|
| The total number of transactions matching the query. |
|
| An array of credit transaction objects for the current page. |
Example
async function listCustomerTransactions(customerId) {
try {
const transactions = await payment.creditTransactions.list({
customer_id: customerId,
pageSize: 5
});
console.log(`Found ${transactions.count} transactions.`);
transactions.list.forEach(tx => {
console.log(`- ID: ${tx.id}, Type: ${tx.type}, Amount: ${tx.amount}`);
});
} catch (error) {
console.error('Error listing transactions:', error.message);
}
}
// Replace 'cust_xxxxxxxx' with a valid customer ID
listCustomerTransactions('cust_xxxxxxxx');Example Response
{
"count": 25,
"list": [
{
"id": "crtrx_xxxxxxxxxxxxxx",
"customer_id": "cust_xxxxxxxx",
"credit_grant_id": "crg_xxxxxxxxxxxxxx",
"type": "consumption",
"amount": "-50",
"running_balance": "850",
"livemode": false,
"created_at": "2023-10-27T11:00:00.000Z",
"updated_at": "2023-10-27T11:00:00.000Z"
},
{
"id": "crtrx_yyyyyyyyyyyyyy",
"customer_id": "cust_xxxxxxxx",
"credit_grant_id": "crg_xxxxxxxxxxxxxx",
"type": "grant",
"amount": "1000",
"running_balance": "1000",
"livemode": false,
"created_at": "2023-10-01T09:00:00.000Z",
"updated_at": "2023-10-01T09:00:00.000Z"
}
]
}Get Usage Summary#
Provides a summarized view of credit usage over a specified period for a customer or subscription.
Parameters
Name | Type | Description |
|---|---|---|
|
| (Optional) The ID of the customer for whom to generate the summary. |
|
| (Optional) The ID of the subscription for which to generate the summary. |
|
| (Optional) Filter summary by a specific currency ID. |
|
| (Optional) A Unix timestamp defining the beginning of the summary period. |
|
| (Optional) A Unix timestamp defining the end of the summary period. |
Returns
A UsageSummary object with aggregated credit data.
Name | Type | Description |
|---|---|---|
|
| The total amount of credits consumed during the period. |
|
| The total amount of credits granted during the period. |
|
| The net change in credit balance ( |
|
| The total number of transactions in the period. |
|
| An object providing a more detailed breakdown of usage. |
|
| Usage broken down by transaction type ( |
|
| (Optional) Usage broken down by meter, if applicable. |
Example
async function getCreditSummary(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);
}
}
// Replace 'cust_xxxxxxxx' with a valid customer ID
getCreditSummary('cust_xxxxxxxx');Example Response
{
"customer_id": "cust_xxxxxxxx",
"total_consumption": "150",
"total_grants": "1000",
"net_balance": "850",
"transaction_count": 12,
"breakdown": {
"by_type": {
"grant": {
"amount": "1000",
"count": 1
},
"consumption": {
"amount": "150",
"count": 11
}
},
"by_meter": {
"mtr_xxxxxxxxxxxxxx": {
"amount": "100",
"count": 8,
"meter_name": "API Calls"
},
"mtr_yyyyyyyyyyyyyy": {
"amount": "50",
"count": 3,
"meter_name": "Data Storage"
}
}
}
}With these tools, you can effectively monitor and analyze credit activity within your application. For a higher-level overview of implementing a credit-based system, please see our Credit Billing guide.