Create a customer balance transaction 

Creates an immutable transaction that updates the customer’s credit balance.

Parameters

  • amountintegerRequired

    The integer amount in cents to apply to the customer’s credit balance.

  • currencyenumRequired

    Three-letter ISO currency code, in lowercase. Must be a supported currency. Specifies the invoice_credit_balance that this transaction will apply to. If the customer’s currency is not set, it will be updated to this value.

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

Returns a customer balance transaction object if the call succeeded.

POST /v1/customers/:id/balance_transactions
curl https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
-d amount=-500 \
-d currency=usd
Response
{
"id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI",
"object": "customer_balance_transaction",
"amount": -500,
"created": 1680216086,
"credit_note": null,
"currency": "usd",
"customer": "cus_NcjdgdwZyI9Rj7",
"description": null,
"ending_balance": -500,
"invoice": null,
"livemode": false,
"metadata": {},
"type": "adjustment"
}

Update a customer credit balance transaction 

Most credit balance transaction fields are immutable, but you may update its description and metadata.

Parameters

  • descriptionstring

    An arbitrary string attached to the object. Often useful for displaying to users.

  • metadataobject

    Set of key-value pairs that you can attach to an object. This can be useful for storing additional information about the object in a structured format. Individual keys can be unset by posting an empty value to them. All keys can be unset by posting an empty value to metadata.

Returns

Returns a customer balance transaction object if the call succeeded.

POST /v1/customers/:id/balance_transactions/:id
curl https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions/cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
-d "metadata[order_id]"=6735
Response
{
"id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI",
"object": "customer_balance_transaction",
"amount": -500,
"created": 1680216086,
"credit_note": null,
"currency": "usd",
"customer": "cus_NcjdgdwZyI9Rj7",
"description": null,
"ending_balance": -500,
"invoice": null,
"livemode": false,
"metadata": {
"order_id": "6735"
},
"type": "adjustment"
}

Retrieve a customer balance transaction 

Retrieves a specific customer balance transaction that updated the customer’s balances.

Parameters

No parameters.

Returns

Returns a customer balance transaction object if a valid identifier was provided.

GET /v1/customers/:id/balance_transactions/:id
curl https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions/cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:"
Response
{
"id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI",
"object": "customer_balance_transaction",
"amount": -500,
"created": 1680216086,
"credit_note": null,
"currency": "usd",
"customer": "cus_NcjdgdwZyI9Rj7",
"description": null,
"ending_balance": -500,
"invoice": null,
"livemode": false,
"metadata": {},
"type": "adjustment"
}

List customer balance transactions 

Returns a list of transactions that updated the customer’s balances.

Parameters

No parameters.

More parameters

  • ending_beforestring

  • limitinteger

  • starting_afterstring

Returns

A dictionary with a data property that contains an array of up to limit customer balance transactions, starting after item starting_after. Each entry in the array is a separate customer balance transaction object. If no more items are available, the resulting array will be empty.

GET /v1/customers/:id/balance_transactions
curl -G https://api.stripe.com/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions \
-u "sk_test_BQokikJ...2HlWgH4olfQ2sk_test_BQokikJOvBiI2HlWgH4olfQ2:" \
-d limit=3
Response
{
"object": "list",
"url": "/v1/customers/cus_NcjdgdwZyI9Rj7/balance_transactions",
"has_more": false,
"data": [
{
"id": "cbtxn_1MrU9qLkdIwHu7ixhdjxGBgI",
"object": "customer_balance_transaction",
"amount": -500,
"created": 1680216086,
"credit_note": null,
"currency": "usd",
"customer": "cus_NcjdgdwZyI9Rj7",
"description": null,
"ending_balance": -500,
"invoice": null,
"livemode": false,
"metadata": {},
"type": "adjustment"
}
]
}

Customer Portal Session 

The Billing customer portal is a Stripe-hosted UI for subscription and billing management.

A portal configuration describes the functionality and features that you want to provide to your customers through the portal.

A portal session describes the instantiation of the customer portal for a particular customer. By visiting the session’s URL, the customer can manage their subscriptions and billing details. For security reasons, sessions are short-lived and will expire if the customer does not visit the URL. Create sessions on-demand when customers intend to manage their subscriptions and billing details.

Related guide: Customer management