Credit Balance Transaction

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

Endpoints

GET/v1/billing/credit_balance_transactions/:id

GET/v1/billing/credit_balance_transactions

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

Server-side language

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

Server-side language

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.

Endpoints