Create new balance

POST

balances

Create new balance

curl --request POST \
  --url http://localhost:5001/balances \
  --header 'X-blnk-key: <api-key>'

const options = {method: 'POST', headers: {'X-blnk-key': '<api-key>'}};

fetch('http://localhost:5001/balances', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_PORT => "5001",
  CURLOPT_URL => "http://localhost:5001/balances",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_HTTPHEADER => [
    "X-blnk-key: <api-key>"
  ],
]);

$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 := "http://localhost:5001/balances"

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

	req.Header.Add("X-blnk-key", "<api-key>")

	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("http://localhost:5001/balances")

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

request = Net::HTTP::Post.new(url)
request["X-blnk-key"] = '<api-key>'

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

Use blnk.ledgerBalances().create for this operation.

Call the method

Ledger balance
General Ledger indicator

ApiResponse<JsonNode> response = blnk.ledgerBalances().create(
    CreateLedgerBalance.create()
        .ledgerId("ldg_073f7ffe-9dfd-42ce-aa50-d1dca1788adc")
        .currency("USD")
        .metaData(Map.of()));

Field	Type	Description
`ledger_id`	`String`	Ledger the balance belongs to.
`currency`	`String`	Currency or asset class for the balance.
`identity_id`	`String`	Identity to link to the balance. Required when `track_fund_lineage` is `true`.
`track_fund_lineage`	`boolean`	Enable fund lineage tracking on this balance.
`allocation_strategy`	`String`	How tagged provider funds are allocated on spend: `FIFO`, `LIFO`, or `PROPORTIONAL`.
`meta_data`	`Map<String, Object>`	Optional metadata for extra context.

Create an internal balance yourself instead of waiting for the first @ reference on a transaction. See Internal balances.

ApiResponse<JsonNode> response = blnk.ledgerBalances().create(
    CreateLedgerBalance.create()
        .ledgerId("general_ledger_id")
        .currency("USD")
        .indicator("@Revenue"));

Field	Type	Description
`ledgerId("general_ledger_id")`	`String`	Must be the General Ledger. `indicator` is only allowed on this ledger.
`indicator()`	`String`	Must start with `@` and contain no whitespace.

Save the balance ID

Use response.data().get("balance_id").asText() as the source or destination on transactions, or when creating balance monitors.

Response

Ledger balance
General Ledger indicator

201 Created

{
  "balance": 0,
  "inflight_balance": 0,
  "credit_balance": 0,
  "inflight_credit_balance": 0,
  "debit_balance": 0,
  "inflight_debit_balance": 0,
  "ledger_id": "ldg_049495c6-356e-4ebc-a45e-60d1e1e16afb",
  "identity_id": "",
  "balance_id": "bln_5ce86029-3c2e-4e2a-aae2-7fb931ca4c4f",
  "currency": "USD",
  "created_at": "2024-11-26T08:36:36.238244338Z",
  "meta_data": null
}

201 Created

{
  "balance": 0,
  "inflight_balance": 0,
  "credit_balance": 0,
  "inflight_credit_balance": 0,
  "debit_balance": 0,
  "inflight_debit_balance": 0,
  "ledger_id": "general_ledger_id",
  "indicator": "@Revenue",
  "identity_id": "",
  "balance_id": "bln_a7c3e91f-2d48-4b1a-9e6c-5f8d2a1b4c70",
  "currency": "USD",
  "created_at": "2024-11-26T08:36:36.238244338Z",
  "meta_data": null
}

Field	Type	Description
`balance_id`	`String`	Unique ID for the balance. Use as `source` or `destination` on transactions.
`ledger_id`	`String`	Ledger ID you passed in the request.
`indicator`	`String`	Set when you created a General Ledger balance with `indicator`.
`currency`	`String`	Currency you passed in the request.
`balance`	`Number`	Current net amount in the balance.
`created_at`	`String`	Date and time the balance was created.

View balance docs

Balance concepts and setup.

HTTP request and response schema.

Need help?

We are very happy to help you make the most of Blnk, regardless of whether it is your first time or you are switching from another tool. To ask questions or discuss issues, please contact us or join our Discord community.

Start Here

Ledgers

Ledger balances

Transactions

Reconciliation

Identities

Metadata

Hooks

Search

API keys

System

Create new balance

View balance docs