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

Server-side language

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

Server-side language

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

Server-side language

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

Endpoints

POST/v1/billing_portal/sessions