---
title: "List balance transactions"
method: GET
path: "/customers/{customer_id}/balance_transactions"
tags: ["Customer"]
---

# List balance transactions

`GET /customers/{customer_id}/balance_transactions`

## The customer balance

The customer balance is an amount in the customer's currency, which Orb automatically applies to subsequent
invoices. This balance can be adjusted manually via Orb's webapp on the customer details page. You can use this
balance to provide a fixed mid-period credit to the customer. Commonly, this is done due to system downtime/SLA
violation, or an adhoc adjustment discussed with the customer.

If the balance is a positive value at the time of invoicing, it represents that the customer has credit that should
be used to offset the amount due on the next issued invoice. In this case, Orb will automatically reduce the next
invoice by the balance amount, and roll over any remaining balance if the invoice is fully discounted.

If the balance is a negative value at the time of invoicing, Orb will increase the invoice's amount due with a
positive adjustment, and reset the balance to 0.

This endpoint retrieves all customer balance transactions in reverse chronological order for a single customer,
providing a complete audit trail of all adjustments and invoice applications.

## Path parameters

- `customer_id` string, required

## Query parameters

- `limit` integer — The number of items to fetch. Defaults to 20.
- `cursor` string, nullable — Cursor for pagination. This can be populated by the `next_cursor` value returned from the initial request.
- `operation_time[gte]` string, date-time, nullable
- `operation_time[gt]` string, date-time, nullable
- `operation_time[lt]` string, date-time, nullable
- `operation_time[lte]` string, date-time, nullable

## Response `200`

OK

- CustomerBalanceTransactions
  - `data` CustomerBalanceTransaction[], required
    - `id` string, required — A unique id for this transaction.
    - `created_at` string, date-time, required — The creation time of this transaction.
    - `starting_balance` string, required — The original value of the customer's balance prior to the transaction, in the customer's currency.
    - `ending_balance` string, required — The new value of the customer's balance prior to the transaction, in the customer's currency.
    - `amount` string, required — The value of the amount changed in the transaction.
    - `action` 'applied_to_invoice' | 'manual_adjustment' | 'prorated_refund' | 'revert_prorated_refund' | 'return_from_voiding' | 'credit_note_applied' | 'credit_note_voided' | 'overpayment_refund' | 'external_payment' | 'small_invoice_carryover', required
    - `description` string, nullable, required — An optional description provided for manual customer balance adjustments.
    - `invoice` InvoiceTiny, required
      - `id` string, required — The Invoice id
    - `type` 'increment' | 'decrement', required
    - `credit_note` CreditNoteTiny, required
      - `id` string, required — The id of the Credit note
  - `pagination_metadata` PaginationMetadata, required
    - `has_more` boolean, required
    - `next_cursor` string, nullable, required

## Other responses

- `400` — Bad Request
- `401` — Unauthorized
- `404` — Not Found
- `409` — Conflict
- `413` — Content Too Large
- `429` — Too Many Requests
- `500` — Internal Server Error

---

[API](https://skmtc.net/withorb/apis/api-reference.md) · [All operations](https://skmtc.net/withorb/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/withorb/api-reference/versions/816dfe734e2e/schema)