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.

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.

{
  "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": {

List Credit Transactions#

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

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.

{
  "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.

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.

{
  "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"
  }
}