Treasury

GET

treasury

earmarked-balance

Get the current Business's earmarked balance

curl --request GET \
  --url https://api.example.com/v1/treasury/earmarked-balance \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.example.com/v1/treasury/earmarked-balance', 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.example.com/v1/treasury/earmarked-balance",
  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.example.com/v1/treasury/earmarked-balance"

	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.example.com/v1/treasury/earmarked-balance")

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

{
  "currency": "<string>",
  "account_provisioned": true,
  "working_balance_minor": 123,
  "accrued_invoice_total_minor": 123,
  "accrued_subscription_total_minor": 123,
  "next_invoice_forecast_date": "2023-11-07T05:31:56Z",
  "low_balance_warning": true,
  "committed_outflow_minor": 123,
  "committed_payout_count": 123,
  "headroom_minor": 123,
  "headroom_warning": true
}

The treasury view partitions your Cleff Account balance into what a new payout can actually draw on:

Earmarked balance: what Cleff has reserved for your next monthly invoice’s fees. Fees accrue regardless of account state, so this reports even before an account is provisioned.
Working balance: the available balance minus the fee earmark. Signed; low_balance_warning is raised when it goes negative.
Committed outflow: payouts committed but not yet debited from the balance, with the count of payouts behind the figure.
Headroom: working balance minus committed outflow, which is what a new payout can safely draw on. headroom_warning is raised when it goes negative, meaning committed payouts will fail at dispatch unless funds arrive first.

Payout creation does not reserve funds. Headroom is the read you check before committing volume, and a shortfall surfaces at dispatch, not at creation. The view is scoped to the Business and environment of the credential; a sandbox credential reads the sandbox partition, never production.

Authorizations

Authorization

string

header

required

Cleff API key issued to a Business that self-registers via POST /v1/registration

Response

currency

string

required

account_provisioned

boolean

required

False until the Business has a provisioned dedicated account. When false the working balance is null and no low-balance warning is raised, but the earmarked fee buckets still report.

working_balance_minor

number | null

required

Available balance minus the in-progress invoice, in minor units. Signed — negative is the low-balance condition. Null when no account is provisioned.

accrued_invoice_total_minor

number

required

Monthly-invoice total accrued for the in-progress period, in minor units (bucket c).

accrued_subscription_total_minor

number

required

The subscription slice of the accrued invoice total, in minor units. The rest of the invoice total is usage-driven fees. Lets the caller show what portion of the earmark is the recurring subscription.

next_invoice_forecast_date

string<date-time>

required

Forecast collection date for the in-progress invoice (first of next month, UTC).

low_balance_warning

boolean

required

True when the working balance is negative — earmarked fees exceed what's available.

committed_outflow_minor

number

required

Payouts committed but not yet debited from the balance mirror, in minor units.

committed_payout_count

number

required

Number of payouts making up the committed outflow.

headroom_minor

number | null

required

What a new payout can safely draw on: working balance minus committed outflow, in minor units. Signed. Null when no account is provisioned.

headroom_warning

boolean

required

True when the headroom is negative — committed payouts exceed what's available after the fee earmark, so they will fail at dispatch unless funds arrive first.

⌘I

Get the current Business's earmarked balance

curl --request GET \
  --url https://api.example.com/v1/treasury/earmarked-balance \
  --header 'Authorization: Bearer <token>'

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

fetch('https://api.example.com/v1/treasury/earmarked-balance', 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.example.com/v1/treasury/earmarked-balance",
  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.example.com/v1/treasury/earmarked-balance"

	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.example.com/v1/treasury/earmarked-balance")

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

{
  "currency": "<string>",
  "account_provisioned": true,
  "working_balance_minor": 123,
  "accrued_invoice_total_minor": 123,
  "accrued_subscription_total_minor": 123,
  "next_invoice_forecast_date": "2023-11-07T05:31:56Z",
  "low_balance_warning": true,
  "committed_outflow_minor": 123,
  "committed_payout_count": 123,
  "headroom_minor": 123,
  "headroom_warning": true
}

Basics

Reference

Authorizations

Response