Balances #
Balances represent Transactions in Balance Sheet Accounts that are still outstanding at the end of the previous Reporting Period. Balances arise from Clearable Transactions such as Client Invoices, Supplier Bills and Journal Entries.
Properties #
Direct Properties #
| Property | Type | Definition |
|---|---|---|
| Balance Type | String | Must be one of DEBIT or CREDIT and represents the side of the Double Entry the Balance falls |
| Transaction Type | String | Must be one of IN, BL or JN. Represents the type of Transaction that gave rise to the Balance |
| Transaction Date | Date | The date of the Transaction that gave rise to the Balance. It can be no later than the first day of the Balance’s Reporting Period, unless the Entity has mid_year_balances switched on |
| Reference | String | Identifying information about the Transaction that gave rise to the Balance e.g Invoice Number |
| Balance | Float | The amount outstanding on the balance Transaction from the Previous Period, in the Currency of the Balance. It is stored translated at the Exchange Rate |
Indirect Properties #
| Property | Type | Definition |
|---|---|---|
| Currency | Dictionary | The Foreign Currency used in the Transaction |
| Exchange Rate | Dictionary | The Closing Rate from the previous Reporting Period for Foreign Currency Transaction |
| Account | Dictionary | The Account for which the Balance relates |
| Reporting Period | Dictionary | The Reporting Period to which the Balance relates. It must belong to the Entity |
Basics #
The parameters required to create a balance are the Id of the account for which the balance is for, the balance type, the transaction type and the date.
Request #
curl --location --request POST 'https://api.microbooks.io/books/v1/balance' \
--header "Authorization: Bearer <bearer_token>" \
--data-raw '{
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}'
import requests
url = "https://api.microbooks.io/books/v1/balance"
body = {
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("POST", url, headers=headers, json=body)
print(response.text)
var request = require('request');
var options = {
'method': 'POST',
'url': 'https://api.microbooks.io/books/v1/balance',
'headers': {'Authorization': 'Bearer <bearer_token>'},
'body': '{
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}'
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
$client = new Client();
$body = '{
"currency_id" : 2,
"exchange_rate_id" : 1,
"account_id" : 1,
"reporting_period_id" : 2,
"balance_type" : "DEBIT",
"transaction_type" : "IN",
"transaction_date" : "2021-10-21",
"balance" : 100
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/balance',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/balance");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
\"currency_id\" : 2,
\"exchange_rate_id\" : 1,
\"account_id\" : 1,
\"reporting_period_id\" : 2,
\"balance_type\" : \"DEBIT\",
\"transaction_type\" : \"IN\",
\"transaction_date\" : \"2021-10-21\",
\"balance\" : 100
}";
request.AddParameter("text/plain", body, ParameterType.RequestBody);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response #
{
"status": "success",
"message": "Debit Balance: Barrett Runolfsdottir DVM for year 2022 created successfully",
"resource": {
"reporting_period_id": 2,
"exchange_rate_id": 1,
"balance_type": "DEBIT",
"currency_id": 2,
"account_id": 1,
"transaction_date": "2021-10-21",
"balance": 100,
"transaction_no": "1EGP2008",
"entity_id": 1,
"id": 1,
"transaction_name": "Client Invoice",
"amount": 100,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...},
"account": {...},
"currency": {..},
"reporting_period": {...}
}
}
Updating a Balance #
A balance sent in an update is translated only if its value differs from the one stored, so sending back the figure you read leaves the Balance as it is. To correct an amount, send it in the Currency of the Balance: it is translated once.
Changing exchange_rate_id on its own keeps the amount in the Currency of the Balance and replaces the rate it is translated at. Balances in a closed Reporting Period cannot be changed in this way.
Closed Reporting Periods #
The Balances of a closed Reporting Period are fixed, and each of the following returns error 108:
- Creating a Balance in the period
- Moving a Balance into or out of the period
- Changing the amount, date, type, Exchange Rate, Currency or Account of a Balance
- Deleting a Balance, or restoring one from the Recycle Bin
Anything else, such as the reference, can still be updated. To correct a Balance, reopen the Reporting Period first.
Variations #
The Balance Resource has no Variations.
Operations #
Opening Balances #
The Opening Balances Endpoint provides a comparison between the Credit and Debit Balances recorded for a given Reoprting Period, making it easy to make sure that their totals are equal.
Request #
curl --location --request GET 'https://api.microbooks.io/books/v1/balance/opening-balances' \
--header "Authorization: Bearer <bearer_token>"
import requests
url = "https://api.microbooks.io/books/v1/balance/opening-balances"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)
print(response.text)
var request = require('request');
var options = {
'method': 'GET',
'url': 'https://api.microbooks.io/books/v1/balance/opening-balances',
'headers': {'Authorization': 'Bearer <bearer_token>'},
'body': '{}'
};
request(options, function (error, response) {
if (error) throw new Error(error);
console.log(response.body);
});
$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/balance/opening-balances',
[headers' => ['Authorization' => 'Bearer <bearer_token>']],
$body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();
var client = new RestClient("https://api.microbooks.io/books/v1/balance/opening-balances");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
var body = null;
request.AddParameter("text/plain", body, ParameterType.RequestBody);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);
Response #
{
"status": "success",
"balances": {
"balances": {
"debit": 90,
"credit": -90
},
"accounts": [
{
"uuid": "d686186b-e2a4-4780-892a-d9d400e53f61",
"id": 1,
"entity_id": 1,
"category_id": null,
"currency_id": 1,
"code": 6,
"name": "Violette Howell",
"description": null,
"opening_balance": 70,
"type": "Receivable",
"is_closed": false,
"balances": [
{
"uuid": "9f56af92-1568-4b93-b47a-d60cab4a87d0",
"id": 1,
"entity_id": 1,
"account_id": 1,
"currency_id": 4,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "at",
"transaction_date": "2021-10-21 15:07:59",
"transaction_no": "est",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Client Invoice",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {...}
},
{
"uuid": "4d979036-4c34-4f88-9429-3241e980dd73",
"id": 2,
"entity_id": 1,
"account_id": 1,
"currency_id": 6,
"exchange_rate_id": 1,
"reporting_period_id": 1,
"reference": "quaerat",
"transaction_date": "2021-10-21 15:08:00",
"transaction_no": "qui",
"balance_type": "DEBIT",
"balance": "50.0000",
"transaction_name": "Journal Entry",
"amount": 50,
"type": "Debit",
"is_posted": true,
"is_credited": false,
"exchange_rate": {..}
}
]
},
{
"uuid": "cc60ebf8-cbf7-4924-9b07-d15df6c9c451",
"id": 2,
"entity_id": 1,
"category_id": null,
"currency_id": 1,
"code": 9,
"name": "Clara Ritchie",
"description": null,
"opening_balance": 20,
"type": "Inventory",
"is_closed": false,
"balances": [...]
},
{
"uuid": "70b5b64e-ec7a-4e21-a6b8-2af221e61adf",
"id": 4,
"entity_id": 1,
"category_id": null,
"currency_id": 1,
"code": 1,
"name": "Friedrich Schneider",
"description": null,
"opening_balance": -40,
"type": "Payable",
"is_closed": false,
"balances": [...]
}
]
}
}
Errors #
Below are the Errors that are returned by the Balance Resource.
| Detail Code | HTTP Status | Name | Definition |
|---|---|---|---|
| 101 | 400 | Missing Entity | The Balance Resource requires an existing Entity because it is used for transfering uncleared Transactions accross Reporting Periods, which Transactions are scoped to the Entity |
| 102 | 400 | Negative Amount | A negative amount on a Balance Resource is meaningless |
| 103 | 400 | Invalid Balance Transaction | The type of Balance Transcation provided cannot be transfered accross Reporting Periods and is therefore invalid according to the rules of IFRS/Bookkeeping |
| 104 | 400 | Invalid Balance Type | The type of Balance provided is invalid according to the rules of IFRS/Bookkeeping |
| 105 | 400 | Invalid Account Class Balance | Balances of Accounts in the class of the Account provided cannot be transfered accross Reporting Periods and it is therefore invalid according to the rules of IFRS/Bookkeeping |
| 106 | 400 | Invalid Balance Date | The date provided at which the Balance arose is after the first day of the Balance’s Reporting Period, which only an Entity with mid_year_balances switched on allows. It is checked when a Balance is created, or when its date or Reporting Period changes |
| 107 | 400 | Invalid Currency | The Currency of the Balance must be the same as that of the provided Balance Account |
| 109 | 400 | Closed Month | The Balance is dated in a closed month, or is being moved out of one, so it cannot be created, changed, deleted or restored until the month is reopened. Returned under transaction_date |
| 108 | 400 | Closed Reporting Period | The Balance’s Reporting Period is closed, so the Balance cannot be added, changed, moved, deleted or restored. See Closed Reporting Periods |
| 422 | 422 | Validation | A field is missing, malformed or not recognised. The field is the key under errors |
Errors use the standard error envelope, which also lists the request-level codes (401, 403, 404, 429 and others) that any endpoint can return.