List balance transactions

curl --request GET \
  --url https://api.withorb.com/v1/customers/{customer_id}/balance_transactions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.withorb.com/v1/customers/{customer_id}/balance_transactions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.withorb.com/v1/customers/{customer_id}/balance_transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/customers/{customer_id}/balance_transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/customers/{customer_id}/balance_transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/customers/{customer_id}/balance_transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "starting_balance": "<string>",
      "ending_balance": "<string>",
      "amount": "<string>",
      "description": "An optional description",
      "invoice": {
        "id": "<string>"
      },
      "credit_note": {
        "id": "<string>"
      }
    }
  ],
  "pagination_metadata": {
    "has_more": true,
    "next_cursor": "<string>"
  }
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Customer

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.

GET

customers

{customer_id}

balance_transactions

List balance transactions

curl --request GET \
  --url https://api.withorb.com/v1/customers/{customer_id}/balance_transactions \
  --header 'Authorization: Bearer <token>'

import requests

url = "https://api.withorb.com/v1/customers/{customer_id}/balance_transactions"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.text)

const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

fetch('https://api.withorb.com/v1/customers/{customer_id}/balance_transactions', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.withorb.com/v1/customers/{customer_id}/balance_transactions",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "GET",
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"net/http"
	"io"
)

func main() {

	url := "https://api.withorb.com/v1/customers/{customer_id}/balance_transactions"

	req, _ := http.NewRequest("GET", url, nil)

	req.Header.Add("Authorization", "Bearer <token>")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

require 'uri'
require 'net/http'

url = URI("https://api.withorb.com/v1/customers/{customer_id}/balance_transactions")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Get.new(url)
request["Authorization"] = 'Bearer <token>'

response = http.request(request)
puts response.read_body

{
  "data": [
    {
      "id": "<string>",
      "created_at": "2023-11-07T05:31:56Z",
      "starting_balance": "<string>",
      "ending_balance": "<string>",
      "amount": "<string>",
      "description": "An optional description",
      "invoice": {
        "id": "<string>"
      },
      "credit_note": {
        "id": "<string>"
      }
    }
  ],
  "pagination_metadata": {
    "has_more": true,
    "next_cursor": "<string>"
  }
}

{
  "type": "https://docs.withorb.com/reference/error-responses#400-constraint-violation",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#401-authentication-error",
  "status": 401,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#404-feature-not-available",
  "status": 400,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#409-resource-conflict",
  "status": 409,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#413-request-too-large",
  "status": 413,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#429-too-many-requests",
  "status": 429,
  "detail": "<string>",
  "title": "<string>"
}

{
  "type": "https://docs.withorb.com/reference/error-responses#500-internal-server-error",
  "status": 123,
  "detail": "<string>",
  "title": "<string>"
}

Authorizations

Authorization

string

header

required

API Keys can be issued in the Orb's web application.

Path Parameters

customer_id

string

required

Query Parameters

limit

integer

default:20

The number of items to fetch. Defaults to 20.

Required range: 1 <= x <= 100

cursor

string | null

Cursor for pagination. This can be populated by the next_cursor value returned from the initial request.

operation_time[gte]

string<date-time> | null

operation_time[gt]

string<date-time> | null

operation_time[lt]

string<date-time> | null

operation_time[lte]

string<date-time> | null

Response

data

CustomerBalanceTransaction · object[]

required

Show child attributes

pagination_metadata

PaginationMetadata · object

required

Show child attributes

⌘I

API documentation

Alert

Coupon

Credit

Credit note

Customer

Dimensional Price Group

Event

Invoice

Item

LicenseType

License

Metric

Availability

Plan

Price

Subscription Change

Subscription

Price interval

List balance transactions

The customer balance

Authorizations

Path Parameters

Query Parameters

Response