Stripe: Retrieve a credit balance transaction
Stripe billing.getBillingCreditBalanceTransactionsId: arguments, response, policy and SDK examples.
← Billing operations · Get started
Operation stripe.getbillingcreditbalancetransactionsid
Provider route: GET /v1/billing/credit_balance_transactions/{id}. Alter supplies the connection’s credentials and routing.
Call through Alter
Section titled “Call through Alter”Install @alter-ai/sdk @alter-ai/stripe with npm, or alter-sdk-stripe with pip. Supply your connected customer’s grant ID and the arguments described below.
import { App } from "@alter-ai/sdk";import { StripeIntegration } from "@alter-ai/stripe";
async function execute(input: Parameters<StripeIntegration["billing"]["getBillingCreditBalanceTransactionsId"]>[0]) { const app = new App({ apiKey: process.env.ALTER_API_KEY! }); try { const provider = new StripeIntegration(app, { grantId: process.env.PROVIDER_GRANT_ID! }); const call = await provider.billing.getBillingCreditBalanceTransactionsId(input); const result = await call.wait(); return result.bodyJson(); } finally { await app.close(); }}import osfrom alter_sdk import Appfrom alter_sdk_stripe import StripeIntegration
async def execute(arguments): async with App(api_key=os.environ["ALTER_API_KEY"]) as app: provider = StripeIntegration(app, {"grant_id": os.environ["PROVIDER_GRANT_ID"]}) call = await provider.billing.get_billing_credit_balance_transactions_id(arguments) result = await call.wait() return result.body_json()| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | Additional keys: not allowed |
path | object | Required within parent | Additional keys: not allowed |
path.id | string | Required within parent | Maximum length: 5000 |
query | object | Optional | Additional keys: not allowed |
query.expand | array | Optional | |
query.expand[] | string | Each item | Maximum length: 5000 |
Response
Section titled “Response”Response media type: application/json. The table describes the pinned successful response. Referenced models link to their complete fields.
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | Model | Root | Expand Retrieve a credit balance transaction — response body |
Referenced models: Retrieve a credit balance transaction — response body
Schemas
Section titled “Schemas”706 more schemas are linked from the tables above, on the schema pages.
Retrieve a credit balance transaction — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A credit balance transaction is a resource representing a transaction (either a credit or a debit) against an existing credit grant. |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
credit | JSON | Optional | |
credit (anyOf 1) | JSON | Alternative | Credit details for this credit balance transaction. Only present if type is `credit`. |
credit (anyOf 1) (anyOf 1) | Model | Alternative | Expand Retrieve a credit balance transaction — response body — credit / value / type: credits application invoice voided, credits granted |
credit (anyOf 2) | null | Alternative | |
credit_grant | JSON | Required within parent | The credit grant associated with this credit balance transaction. |
credit_grant (anyOf 1) | string | Alternative | Maximum length: 5000 |
credit_grant (anyOf 2) | Model | Alternative | Expand Void a credit grant — response body |
debit | JSON | Optional | |
debit (anyOf 1) | JSON | Alternative | Debit details for this credit balance transaction. Only present if type is `debit`. |
debit (anyOf 1) (anyOf 1) | Model | Alternative | Expand Retrieve a credit balance transaction — response body — debit / value / type: credits applied, credits expired, credits voided |
debit (anyOf 2) | null | Alternative | |
effective_at | JSON | Required within parent | |
effective_at (anyOf 1) | integer | Alternative | The effective time of this credit balance transaction. Format: unix-time |
effective_at (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: billing.credit_balance_transaction |
test_clock | JSON | Optional | |
test_clock (anyOf 1) | JSON | Alternative | ID of the test clock this credit balance transaction belongs to. |
test_clock (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
test_clock (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a test clock — response body |
test_clock (anyOf 2) | null | Alternative | |
type | JSON | Optional | |
type (anyOf 1) | string | Alternative | The type of credit balance transaction (credit or debit). Known values: credit, debit |
type (anyOf 2) | null | Alternative |
Referenced models: Void a credit grant — response body, Retrieve a credit balance transaction — response body — credit / value / type: credits application invoice voided, credits granted, Retrieve a credit balance transaction — response body — debit / value / type: credits applied, credits expired, credits voided, Create a test clock — response body
Void a credit grant — response body
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | A credit grant is an API resource that documents the allocation of some billing credits to a customer. Related guide: [Billing credits](https://docs.stripe.com/billing/subscriptions/usage-based/billing-credits) |
amount | Model | Required within parent | Expand Void a credit grant — response body — amount |
applicability_config | Model | Required within parent | Expand Void a credit grant — response body — applicability config |
category | string | Required within parent | The category of this credit grant. This is for tracking purposes and isn't displayed to the customer. Known values: paid, promotional |
created | JSON | Required within parent | |
created (anyOf 1) | integer | Alternative | Time at which the object was created. Measured in seconds since the Unix epoch. Format: unix-time |
created (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
customer | JSON | Required within parent | ID of the customer receiving the billing credits. |
customer (anyOf 1) | string | Alternative | Maximum length: 5000 |
customer (anyOf 2) | Model | Alternative | Expand Create a customer — response body |
customer (anyOf 3) | Model | Alternative | Expand Delete a customer — response body |
customer_account | JSON | Optional | |
customer_account (anyOf 1) | string | Alternative | ID of the account representing the customer receiving the billing credits Maximum length: 5000 |
customer_account (anyOf 2) | null | Alternative | |
effective_at | JSON | Optional | |
effective_at (anyOf 1) | JSON | Alternative | |
effective_at (anyOf 1) (anyOf 1) | integer | Alternative | The time when the billing credits become effective-when they're eligible for use. Format: unix-time |
effective_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
effective_at (anyOf 2) | null | Alternative | |
expires_at | JSON | Optional | |
expires_at (anyOf 1) | JSON | Alternative | |
expires_at (anyOf 1) (anyOf 1) | integer | Alternative | The time when the billing credits expire. If not present, the billing credits don't expire. Format: unix-time |
expires_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
expires_at (anyOf 2) | null | Alternative | |
id | string | Required within parent | Unique identifier for the object. Maximum length: 5000 |
livemode | boolean | Required within parent | If the object exists in live mode, the value is `true`. If the object exists in test mode, the value is `false`. |
metadata | object | Required within parent | Set of [key-value pairs](https://docs.stripe.com/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Additional keys: see wildcard field |
metadata.* | string | Additional keys | Maximum length: 500 |
name | JSON | Optional | |
name (anyOf 1) | string | Alternative | A descriptive name shown in dashboard. Maximum length: 5000 |
name (anyOf 2) | null | Alternative | |
object | string | Required within parent | String representing the object's type. Objects of the same type share the same value. Known values: billing.credit_grant |
priority | JSON | Optional | |
priority (anyOf 1) | JSON | Alternative | |
priority (anyOf 1) (anyOf 1) | integer | Alternative | The priority for applying this credit grant. The highest priority is 0 and the lowest is 100. |
priority (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
priority (anyOf 2) | null | Alternative | |
test_clock | JSON | Optional | |
test_clock (anyOf 1) | JSON | Alternative | ID of the test clock this credit grant belongs to. |
test_clock (anyOf 1) (anyOf 1) | string | Alternative | Maximum length: 5000 |
test_clock (anyOf 1) (anyOf 2) | Model | Alternative | Expand Create a test clock — response body |
test_clock (anyOf 2) | null | Alternative | |
updated | JSON | Required within parent | |
updated (anyOf 1) | integer | Alternative | Time at which the object was last updated. Measured in seconds since the Unix epoch. Format: unix-time |
updated (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
voided_at | JSON | Optional | |
voided_at (anyOf 1) | JSON | Alternative | |
voided_at (anyOf 1) (anyOf 1) | integer | Alternative | The time when this credit grant was voided. If not present, the credit grant hasn't been voided. Format: unix-time |
voided_at (anyOf 1) (anyOf 2) | string | Alternative | Pattern: ^-?[0-9]+(?:\.[0-9]+)?(?:[eE][+-]?[0-9]+)?$ |
voided_at (anyOf 2) | null | Alternative |
Referenced models: Void a credit grant — response body — amount, Void a credit grant — response body — applicability config, Create a customer — response body, Delete a customer — response body, Create a test clock — response body
Void a credit grant — response body — applicability config
| Field | Type | Presence | Description and constraints |
|---|---|---|---|
$ | object | Root | |
scope | Model | Required within parent | Expand Void a credit grant — response body — applicability config scope |
Referenced models: Void a credit grant — response body — applicability config scope
Policy, approvals and errors
Section titled “Policy, approvals and errors”SDK function policy ID: stripe.getbillingcreditbalancetransactionsid. Catalog operation: GetBillingCreditBalanceTransactionsId. Rules can name either ID; function rules distinguish managed calls and conservatively cover raw calls sharing the route. Existing grant permissions and policy rules apply. wait() returns an immediate result or waits for a required approval; it never approves the request itself. Persist the approval ID to resume after a restart.
Provider errors retain their response; JSON decoding raises ProviderAPIError for provider failures. ManagedOperationError identifies contract/input/retention errors. See error handling and provider-specific behavior. Sensitive input may be refused before approval storage. A decoding error never resubmits a write.
Pinned headers: {"Stripe-Version": "2026-09-30.endive"}