Credit Transactions

Credit Transaction objects record every change to a customer's credit balance. This includes grants, consumptions, adjustments, and expirations. You can use this API to retrieve a detailed history of a customer's credit activities.

Each transaction provides a snapshot of the credit balance at the time of the event, making it a reliable ledger for auditing and tracking credit usage. For a higher-level overview of credit management, see the Credit-Based Billing guide.

The Credit Transaction Object

A CreditTransaction object contains detailed information about a single credit event.

Attribute	Type	Description
`id`	string	Unique identifier for the credit transaction object.
`customer_id`	string	ID of the customer associated with this transaction.
`credit_grant_id`	string	ID of the credit grant from which this transaction originated.
`meter_id`	string	(Optional) ID of the meter if the transaction is a consumption event.
`subscription_id`	string	(Optional) ID of the subscription associated with this transaction.
`meter_event_id`	string	(Optional) ID of the meter event that triggered a consumption.
`type`	string	The type of transaction. Can be `grant`, `consumption`, `adjustment`, or `expiration`.
`amount`	string	The amount of credit transacted, represented as a string. A positive value indicates credits added (e.g., a grant), and a negative value indicates credits removed (e.g., consumption).
`running_balance`	string	The customer's credit balance after this transaction occurred.
`description`	string	(Optional) An internal description of the transaction.
`livemode`	boolean	`true` if the transaction was created in live mode, `false` for test mode.
`created_at`	string	Timestamp of when the object was created.
`updated_at`	string	Timestamp of the last update to the object.
`metadata`	object	(Optional) A set of key-value pairs that you can attach to an object.

Retrieve a Credit Transaction

Retrieves the details of a specific credit transaction by its unique ID.

Retrieve a Transaction

const transaction = await payment.creditTransactions.retrieve(
  'ct_xxxxxxxxxxxxxx'
);

console.log(transaction);

Parameters

Name	Type	Description
`id`	string	Required. The unique identifier of the credit transaction to retrieve.

Returns

Returns a TCreditTransactionExpanded object if a valid ID is provided. Otherwise, this call returns an error.

Response Example

{
  "id": "ct_123456789",
  "customer_id": "cus_abcdefgh",
  "credit_grant_id": "cg_ijklmnop",
  "meter_id": "mtr_qrstuvwx",
  "subscription_id": "sub_yz123456",
  "meter_event_id": "me_7890abcd",
  "type": "consumption",
  "amount": "-100.00",
  "running_balance": "900.00",
  "description": "API Call Usage",
  "livemode": true,
  "created_at": "2023-10-27T10:00:00.000Z",
  "updated_at": "2023-10-27T10:00:00.000Z",
  "metadata": {},
  "customer": {
    "id": "cus_abcdefgh",
    "name": "John Doe",
    "email": "john.doe@example.com"
  },
  "meter": {
    "id": "mtr_qrstuvwx",
    "name": "API Calls"
  },
  "subscription": {
    "id": "sub_yz123456",
    "description": "Premium Plan"
  },
  "creditGrant": {
    "id": "cg_ijklmnop",
    "name": "Initial Grant"
  }
}

List Credit Transactions

Returns a paginated list of credit transactions. You can filter the list based on various parameters.

List Transactions

const transactions = await payment.creditTransactions.list({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  limit: 10,
});

console.log(transactions);

Parameters

Name	Type	Description
`page`	number	Optional. The page number for pagination, starting at 1. Defaults to `1`.
`pageSize`	number	Optional. The number of items to return per page. Defaults to `20`.
`customer_id`	string	Optional. Filter transactions for a specific customer.
`subscription_id`	string	Optional. Filter transactions for a specific subscription.
`credit_grant_id`	string	Optional. Filter transactions originating from a specific credit grant.
`meter_id`	string	Optional. Filter transactions related to a specific meter.
`source`	string	Optional. Filter by the source of the transaction.
`start`	number	Optional. A Unix timestamp to filter for transactions created on or after this time.
`end`	number	Optional. A Unix timestamp to filter for transactions created on or before this time.
`livemode`	boolean	Optional. Specify whether to fetch live or test mode transactions.
`q`	string	Optional. A general search query string.

Returns

Returns a paginated list of TCreditTransactionExpanded objects.

Response Example

{
  "count": 15,
  "list": [
    {
      "id": "ct_123456789",
      "customer_id": "cus_abcdefgh",
      "credit_grant_id": "cg_ijklmnop",
      "type": "consumption",
      "amount": "-100.00",
      "running_balance": "900.00",
      "livemode": true,
      "created_at": "2023-10-27T10:00:00.000Z",
      // ... other fields and expanded objects
    }
    // ... more transactions
  ],
  "paging": {
    "page": 1,
    "pageSize": 10
  }
}

Get Usage Summary

Retrieves a summary of credit consumption over a specified period for a customer, subscription, or meter.

Get Usage Summary

const summary = await payment.creditTransactions.summary({
  customer_id: 'cus_xxxxxxxxxxxxxx',
  start: Math.floor(new Date('2023-01-01').getTime() / 1000),
  end: Math.floor(new Date('2023-12-31').getTime() / 1000),
});

console.log(summary);

Parameters

Name	Type	Description
`customer_id`	string	Optional. The ID of the customer to summarize usage for.
`subscription_id`	string	Optional. The ID of the subscription to summarize usage for.
`currency_id`	string	Optional. Filter summary by a specific credit currency.
`meter_id`	string	Optional. Filter summary by a specific meter.
`start`	number	Optional. A Unix timestamp for the beginning of the reporting period.
`end`	number	Optional. A Unix timestamp for the end of the reporting period.

Returns

Returns a UsageSummary object detailing the total consumption and transaction count within the specified filters.

Response Example

{
  "total_quantity": "1500",
  "total_credit_amount": "-1500.00",
  "transaction_count": 42,
  "filters": {
    "customer_id": "cus_xxxxxxxxxxxxxx",
    "start_time": "2023-01-01T00:00:00.000Z",
    "end_time": "2023-12-31T00:00:00.000Z"
  }
}