Credit Balance Transaction 

A credit balance transaction is a resource representing a transaction (either a credit or a debit) against an existing credit grant.

The Credit Balance Transaction object 

Attributes

  • idstring

    Unique identifier for the object.

  • objectstring

    String representing the object’s type. Objects of the same type share the same value.

  • createdtimestamp

    Time at which the object was created. Measured in seconds since the Unix epoch.

  • creditnullable object

    Credit details for this credit balance transaction. Only present if type is credit.

  • credit_grantstringExpandable

    The credit grant associated with this credit balance transaction.

  • debitnullable object

    Debit details for this credit balance transaction. Only present if type is debit.

  • effective_attimestamp

    The effective time of this credit balance transaction.

  • livemodeboolean

    Has the value true if the object exists in live mode or the value false if the object exists in test mode.

  • test_clocknullable stringExpandable

    ID of the test clock this credit balance transaction belongs to.

  • typenullable enum

    The type of credit balance transaction (credit or debit).

    Possible enum values
    credit

    A credit transaction.

    debit

    A debit transaction.

The Credit Balance Transaction object
{
"id": "cbtxn_test_61R9ZljjaFmdidb6e41L6nFOS1ekD9Ue",
"object": "billing.credit_balance_transaction",
"created": 1726619524,
"credit": null,
"credit_grant": "credgr_test_61R9ZkIkIzLSp0xze41L6nFOS1ekDTPE",
"debit": {
"amount": {
"monetary": {
"currency": "usd",
"value": 1000
},
"type": "monetary"
},
"credits_applied": {
"invoice": "in_1Q0BoLL6nFOS1ekDbwBM5ER1",
"invoice_line_item": "il_1QB443L6nFOS1ekDwRiN3Z4n"
},
"type": "credits_applied"
},
"effective_at": 1729211351,
"livemode": false,
"test_clock": "clock_1Q0BoJL6nFOS1ekDbyYYuseM",
"type": "debit"
}

Retrieve a credit balance transaction 

Retrieves a credit balance transaction.

Parameters

  • idstringRequired

    Unique identifier for the object.

Returns

Returns a credit balance transaction.

GET /v1/billing/credit_balance_transactions/:id
curl https://api.stripe.com/v1/billing/credit_balance_transactions/cbtxn_test_61R9ZljjaFmdidb6e41L6nFOS1ekD9Ue \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
"id": "cbtxn_test_61R9ZljjaFmdidb6e41L6nFOS1ekD9Ue",
"object": "billing.credit_balance_transaction",
"created": 1726619524,
"credit": null,
"credit_grant": "credgr_test_61R9ZkIkIzLSp0xze41L6nFOS1ekDTPE",
"debit": {
"amount": {
"monetary": {
"currency": "usd",
"value": 1000
},
"type": "monetary"
},
"credits_applied": {
"invoice": "in_1Q0BoLL6nFOS1ekDbwBM5ER1",
"invoice_line_item": "il_1QB443L6nFOS1ekDwRiN3Z4n"
},
"type": "credits_applied"
},
"effective_at": 1729211351,
"livemode": false,
"test_clock": "clock_1Q0BoJL6nFOS1ekDbyYYuseM",
"type": "debit"
}

List credit balance transactions 

Retrieve a list of credit balance transactions.

Parameters

  • customerstringRequired

    The customer for which to fetch credit balance transactions.

  • credit_grantstring

    The credit grant for which to fetch credit balance transactions.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

Returns a list of credit balanace transactions.

GET /v1/billing/credit_balance_transactions
curl -G https://api.stripe.com/v1/billing/credit_balance_transactions \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
-d customer=cus_QrvQguzkIK8zTj \
-d credit_grant=credgr_test_61R9ZkIkIzLSp0xze41L6nFOS1ekDTPE
Response
{
"object": "list",
"data": [
{
"id": "cbtxn_test_61R9ZljjaFmdidb6e41L6nFOS1ekD9Ue",
"object": "billing.credit_balance_transaction",
"created": 1726619524,
"credit": null,
"credit_grant": "credgr_test_61R9ZkIkIzLSp0xze41L6nFOS1ekDTPE",
"debit": {
"amount": {
"monetary": {
"currency": "usd",
"value": 1000
},
"type": "monetary"
},
"credits_applied": {
"invoice": "in_1Q0BoLL6nFOS1ekDbwBM5ER1",
"invoice_line_item": "il_1QB443L6nFOS1ekDwRiN3Z4n"
},
"type": "credits_applied"
},
"effective_at": 1729211351,
"livemode": false,
"test_clock": "clock_1Q0BoJL6nFOS1ekDbyYYuseM",
"type": "debit"
},
{
"id": "cbtxn_test_61R9ZkIbb17ze4b2s41L6nFOS1ekDXHs",
"object": "billing.credit_balance_transaction",
"created": 1726619434,
"credit": {
"amount": {
"monetary": {
"currency": "usd",
"value": 1000
},
"type": "monetary"
},
"type": "credits_granted"
},
"credit_grant": "credgr_test_61R9ZkIkIzLSp0xze41L6nFOS1ekDTPE",
"debit": null,
"effective_at": 1726619434,
"livemode": false,
"test_clock": "clock_1Q0BoJL6nFOS1ekDbyYYuseM",
"type": "credit"
}
],
"has_more": false,
"url": "/v1/billing/credit_grants"
}

Plans 

You can now model subscriptions more flexibly using the Prices API. It replaces the Plans API and is backwards compatible to simplify your migration.

Plans define the base price, currency, and billing cycle for recurring purchases of products. Products help you track inventory or provisioning, and plans help you track pricing. Different physical goods or levels of service should be represented by products, and pricing options should be represented by plans. This approach lets you change prices without having to change your provisioning scheme.

For example, you might have a single “gold” product that has plans for $10/month, $100/year, €9/month, and €90/year.

Related guides: Set up a subscription and more about products and prices.