BiasDocs

Customer balance transactions

A customer balance transaction records one change to a customer’s balance: credit toward their invoices, or an amount they owe. The customer balance guide covers how invoices use the balance.

The CustomerBalanceTransaction object

Name
object
Type
"customer_balance_transaction",
Description
The object's type.
Name
id
Type
string,
Description
Unique identifier for the object.
Name
live
Type
boolean,
Description
true if the object is live, or false if it's in a sandbox.
Name
created_at
Type
integer,
Description
When the object was created, in milliseconds since the Unix epoch.
Name
amount
Type
integer,
Description
The change in cents: positive adds credit, negative adds an amount owed.
Name
credit_note
Type
string or CreditNote or null,
Description
Expandable. The credit note the transaction came from, if any.
Name
customer
Type
string or Customer,
Description
Expandable. The customer whose balance changed.
Name
description
Type
string or null,
Description
An internal note.
Name
ending_balance
Type
integer,
Description
The customer's balance in cents after this transaction.
Name
invoice
Type
string or Invoice or null,
Description
Expandable. The invoice that applied or gave back the balance, for invoice_applied and invoice_reversed.
Name
metadata
Type
object,
Description
Your own key-value data on the object.
Name
refund
Type
string or Refund or null,
Description
Expandable. The refund that failed, for refund_failed, or paid out the credit, for credit_refunded.
Name
type
Type
enum,
Description
What changed the customer's balance.
Properties

The CustomerBalanceTransaction object

{
  "object": "customer_balance_transaction",
  "live": false,
  "id": "cbt_u4w57sAPX2W3yiruT2ld73",
  "created_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "type": "credit_note",
  "amount": 2500,
  "ending_balance": 2500,
  "invoice": null,
  "credit_note": "cn_hxUznDJdC6eOs4OcqeVP83",
  "refund": null,
  "description": null,
  "metadata": {}
}

Get a customer balance transaction

Retrieve a customer balance transaction by its ID.

Required parameters

Name
id
Type
string,
Description
The ID of the customer balance transaction to retrieve.

Optional parameters

Name
expand
Type
object,
Properties

Returns

Returns the customer balance transaction object.

Get a customer balance transaction

const customerBalanceTransaction = await bias.customerBalanceTransactions.get("id");

Response example

{
  "object": "customer_balance_transaction",
  "live": false,
  "id": "cbt_u4w57sAPX2W3yiruT2ld73",
  "created_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "type": "credit_note",
  "amount": 2500,
  "ending_balance": 2500,
  "invoice": null,
  "credit_note": "cn_hxUznDJdC6eOs4OcqeVP83",
  "refund": null,
  "description": null,
  "metadata": {}
}

List all customer balance transactions

Retrieve a paginated list of customer balance transactions, most recently created first. Filtering by customer gives one customer’s history.

Optional parameters

Name
expand
Type
object,
Description
Related objects to expand in the response.
Properties
Name
ending_before
Type
string,
Description
The ID of the object to list before, for pagination.
Name
starting_after
Type
string,
Description
The ID of the object to list after, for pagination.
Name
limit
Type
integer, at least 1, at most 1000, default is 50
Description
The maximum number of objects to return, from 1 to 1000. Defaults to 50.
Name
filters
Type
object, object, or object,
Description
Filters for the list, combined with and and or.
Properties

Returns

Returns a list of customer balance transaction objects.

List all customer balance transactions

const customerBalanceTransaction = await bias.customerBalanceTransactions.list();

Response example

{
  "object": "list",
  "items": [
    {
      "object": "customer_balance_transaction",
      "live": false,
      "id": "cbt_u4w57sAPX2W3yiruT2ld73",
      "created_at": 1750000000000,
      "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
      "type": "credit_note",
      "amount": 2500,
      "ending_balance": 2500,
      "invoice": null,
      "credit_note": "cn_hxUznDJdC6eOs4OcqeVP83",
      "refund": null,
      "description": null,
      "metadata": {}
    }
  ],
  "has_more": true
}

Create a customer balance transaction

An adjustment gives a customer credit toward their next invoices, such as a goodwill credit, or adds an amount they owe. Bias applies the balance when an invoice is finalized.

Required parameters

Name
customer
Type
string,
Description
The customer whose balance to change.
Name
amount
Type
integer,
Description
The change in cents: positive adds credit, negative adds an amount the customer owes.

Optional parameters

Name
expand
Type
object,
Properties
Name
description
Type
string or null,
Description
An internal note.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the customer balance transaction object, with type: "adjustment".

Create a customer balance transaction

const customerBalanceTransaction = await bias.customerBalanceTransactions.create({
  customer: "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  amount: 2000,
  description: "Credit for the March outage"
});

Response example

{
  "object": "customer_balance_transaction",
  "live": false,
  "id": "cbt_u4w57sAPX2W3yiruT2ld73",
  "created_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "type": "credit_note",
  "amount": 2500,
  "ending_balance": 2500,
  "invoice": null,
  "credit_note": "cn_hxUznDJdC6eOs4OcqeVP83",
  "refund": null,
  "description": null,
  "metadata": {}
}

Update a customer balance transaction

Only a transaction’s description and metadata can change. To correct an amount, create another transaction for the opposite amount.

Required parameters

Name
id
Type
string,

Optional parameters

Name
expand
Type
object,
Properties
Name
description
Type
string or null,
Description
An internal note.
Name
metadata
Type
object or null,
Description
Your own key-value data on the object.

Returns

Returns the customer balance transaction object.

Update a customer balance transaction

const customerBalanceTransaction = await bias.customerBalanceTransactions.update("id", {
  description: "Credit for the March outage"
});

Response example

{
  "object": "customer_balance_transaction",
  "live": false,
  "id": "cbt_u4w57sAPX2W3yiruT2ld73",
  "created_at": 1750000000000,
  "customer": "cus_aB4DEXqbFGOlpEOxwp0Fx1",
  "type": "credit_note",
  "amount": 2500,
  "ending_balance": 2500,
  "invoice": null,
  "credit_note": "cn_hxUznDJdC6eOs4OcqeVP83",
  "refund": null,
  "description": null,
  "metadata": {}
}