# customer\_balance\_transaction

From **Stripe API**.

Each customer has a [`balance`](https://stripe.com/docs/api/customers/object#customer_object-balance) value,
which denotes a debit or credit that's automatically applied to their next invoice upon finalization.
You may modify the value directly by using the [update customer API](https://stripe.com/docs/api/customers/update),
or by creating a Customer Balance Transaction, which increments or decrements the customer's `balance` by the specified `amount`.

Related guide: [Customer Balance](https://stripe.com/docs/billing/customer/balance) to learn more.

- Type: `object`

## Properties

### `amount`

- Required: true
- Type: `integer`

The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's `balance`.

### `created`

- Required: true
- Type: `integer`
- Format: `unix-time`

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

### `credit_note`

- Required: false
- Nullable: true

The ID of the credit note (if any) related to the transaction.

### `currency`

- Required: true
- Type: `string`

Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).

### `customer`

- Required: true
The ID of the customer the transaction belongs to.

### `description`

- Required: false
- Type: `string`
- Nullable: true
- maxLength: `5000`

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

### `ending_balance`

- Required: true
- Type: `integer`

The customer's `balance` after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.

### `id`

- Required: true
- Type: `string`
- maxLength: `5000`

Unique identifier for the object.

### `invoice`

- Required: false
- Nullable: true

The ID of the invoice (if any) related to the transaction.

### `livemode`

- Required: true
- Type: `boolean`

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

### `metadata`

- Required: false
- Type: `object`
- Nullable: true

Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.

### `object`

- Required: true
- Type: `string`
- Allowed values: `"customer_balance_transaction"`

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

### `type`

- Required: true
- Type: `string`
- Allowed values: `"adjustment"`, `"applied_to_invoice"`, `"credit_note"`, `"initial"`, `"invoice_too_large"`, `"invoice_too_small"`, `"migration"`, `"unapplied_from_invoice"`, `"unspent_receiver_credit"`

Transaction type: `adjustment`, `applied_to_invoice`, `credit_note`, `initial`, `invoice_too_large`, `invoice_too_small`, `unspent_receiver_credit`, or `unapplied_from_invoice`. See the [Customer Balance page](https://stripe.com/docs/billing/customer/balance#types) to learn more about transaction types.

## JSON Schema

```json
{"description":"Each customer has a [`balance`](https://stripe.com/docs/api/customers/object#customer_object-balance) value,\nwhich denotes a debit or credit that's automatically applied to their next invoice upon finalization.\nYou may modify the value directly by using the [update customer API](https://stripe.com/docs/api/customers/update),\nor by creating a Customer Balance Transaction, which increments or decrements the customer's `balance` by the specified `amount`.\n\nRelated guide: [Customer Balance](https://stripe.com/docs/billing/customer/balance) to learn more.","properties":{"amount":{"description":"The amount of the transaction. A negative value is a credit for the customer's balance, and a positive value is a debit to the customer's `balance`.","type":"integer"},"created":{"description":"Time at which the object was created. Measured in seconds since the Unix epoch.","format":"unix-time","type":"integer"},"credit_note":{"anyOf":[{"maxLength":5000,"type":"string"},{"$ref":"#/components/schemas/credit_note"}],"description":"The ID of the credit note (if any) related to the transaction.","nullable":true,"x-expansionResources":{"oneOf":[{"$ref":"#/components/schemas/credit_note"}]}},"currency":{"description":"Three-letter [ISO currency code](https://www.iso.org/iso-4217-currency-codes.html), in lowercase. Must be a [supported currency](https://stripe.com/docs/currencies).","type":"string"},"customer":{"anyOf":[{"maxLength":5000,"type":"string"},{"$ref":"#/components/schemas/customer"}],"description":"The ID of the customer the transaction belongs to.","x-expansionResources":{"oneOf":[{"$ref":"#/components/schemas/customer"}]}},"description":{"description":"An arbitrary string attached to the object. Often useful for displaying to users.","maxLength":5000,"nullable":true,"type":"string"},"ending_balance":{"description":"The customer's `balance` after the transaction was applied. A negative value decreases the amount due on the customer's next invoice. A positive value increases the amount due on the customer's next invoice.","type":"integer"},"id":{"description":"Unique identifier for the object.","maxLength":5000,"type":"string"},"invoice":{"anyOf":[{"maxLength":5000,"type":"string"},{"$ref":"#/components/schemas/invoice"}],"description":"The ID of the invoice (if any) related to the transaction.","nullable":true,"x-expansionResources":{"oneOf":[{"$ref":"#/components/schemas/invoice"}]}},"livemode":{"description":"Has the value `true` if the object exists in live mode or the value `false` if the object exists in test mode.","type":"boolean"},"metadata":{"additionalProperties":{"maxLength":500,"type":"string"},"description":"Set of [key-value pairs](https://stripe.com/docs/api/metadata) that you can attach to an object. This can be useful for storing additional information about the object in a structured format.","nullable":true,"type":"object"},"object":{"description":"String representing the object's type. Objects of the same type share the same value.","enum":["customer_balance_transaction"],"type":"string"},"type":{"description":"Transaction type: `adjustment`, `applied_to_invoice`, `credit_note`, `initial`, `invoice_too_large`, `invoice_too_small`, `unspent_receiver_credit`, or `unapplied_from_invoice`. See the [Customer Balance page](https://stripe.com/docs/billing/customer/balance#types) to learn more about transaction types.","enum":["adjustment","applied_to_invoice","credit_note","initial","invoice_too_large","invoice_too_small","migration","unapplied_from_invoice","unspent_receiver_credit"],"type":"string"}},"required":["amount","created","currency","customer","ending_balance","id","livemode","object","type"],"title":"CustomerBalanceTransaction","type":"object","x-expandableFields":["credit_note","customer","invoice"],"x-resourceId":"customer_balance_transaction"}
```