Skip to main content

List 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.

Eligibility​

The customer balance can only be applied to invoices or adjusted manually if invoices are not synced to a separate invoicing provider. If a payment gateway such as Stripe is used, the balance will be applied to the invoice before forwarding payment to the gateway.

Path Parameters
    customer_id string required
Query Parameters
    limit integer

    Possible values: >= 1 and <= 1000

    Default value: 20

    cursor string
    operation_time[gte] date-time
    operation_time[gt] date-time
    operation_time[lt] date-time
    operation_time[lte] date-time
Responses

OK

Response Headers
    Schema
      data object[] required
    • Array [
      • id string required

      A unique id for this transaction.

      created_at 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 string required

      Possible values: [applied_to_invoice, manual_adjustment, prorated_refund, revert_prorated_refund, return_from_voiding, credit_note_applied, credit_note_voided, overpayment_refund]

      description string nullable required

      An optional description provided for manual customer balance adjustments.

      invoice object nullable
      id string required

      The Invoice id

      type string required

      Possible values: [increment, decrement]

      credit_note object nullable
      id string required

      The id of the Credit note

    • ]
      • pagination_metadata object required
      has_more boolean required
      next_cursor string nullable required
    Loading...