Step 5: Transactions #

Transactions represent the primary means of loading source document financial data into the platform, which data is then processed to create the Financial Reports. In this quickstart, we will group the Transactions under the Sales Cycle, Purchasing Cycle and Financing.

Two Step Commit #

In line with book keeping best practice such as Segregation of Duties, transactions require two steps to be posted to the Ledger. The first step only saves the transaction, allowing changes to be made to it at a later time. To finalize it and record it it to the ledger which will make it immutable, we need to call the post endpoint.

Sales Cycle #

The sales cycle represents the expenditure of the Entity on goods and services, which may either be on cash or credit basis

Cash Sale #

In the case of Cash Sales, the cycle is a single step because cash is received at the same time as the goods and services are provided.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Bank Account created in Step 2>",
        "transaction_type": "CS",
        "narration": "Cash Sale",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Revenue Account created in Step 2>",
            "amount": 100,
            "narration": "Cash Sale Line Item",
            "taxes": ["<id of Output Tax created in Step 3>"]
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Bank Account created in Step 2>",
    "transaction_type": "CS",
    "narration": "Cash Sale",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Revenue Account created in Step 2>",
        "amount": 100,
        "narration": "Cash Sale Line Item",
        "taxes": ["<id of Output Tax created in Step 3>"]
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Bank Account created in Step 2>",
        "transaction_type": "CS",
        "narration": "Cash Sale",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Revenue Account created in Step 2>",
            "amount": 100,
            "narration": "Cash Sale Line Item",
            "taxes": ["<id of Output Tax created in Step 3>"]
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Bank Account created in Step 2>",
    "transaction_type": "CS",
    "narration": "Cash Sale",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Revenue Account created in Step 2>",
        "amount": 100,
        "narration": "Cash Sale Line Item",
        "taxes": ["<id of Output Tax created in Step 3>"]
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Bank Account created in Step 2>\",
    \"transaction_type\": \"CS\",
    \"narration\": \"Cash Sale\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Revenue Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Cash Sale Line Item\",
        \"taxes\" => [\"<id of Output Tax created in Step 3>\"]
    }]
}";
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": "Cash Sale: CS01/0001 for 110.00 created successfully",
    "resource": {
        "credited": false,
        "transaction_type": "CS",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 2,
        "narration": "Cash Sale",
        "currency_id": 1,
        "transaction_no": "CS01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 1,
        "transaction_name": "Cash Sale",
        "is_posted": false,
        "is_credited": false,
        "amount": 110,
        "tax": {
            "total": 10,
            "OTP": "10.0000"
        },
        "assignable": false,
        "clearable": false,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Cash Sale>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Cash Sale>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Cash Sale>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Cash Sale>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Cash Sale>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Credit Sale #

For Sales made on Credit first the sale is recorded in the form of a Client Invoice then the collection of the cash follows at a later date.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Receivable Account created in Step 2>",
        "transaction_type": "IN",
        "narration": "Client Invoice",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Revenue Account created in Step 2>",
            "amount": 100,
            "narration": "Client Invoice Line Item",
            "taxes": ["<id of Output Tax created in Step 3>"]
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Receivable Account created in Step 2>",
    "transaction_type": "IN",
    "narration": "Client Invoice",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Revenue Account created in Step 2>",
        "amount": 100,
        "narration": "Client Invoice Line Item",
        "taxes": ["<id of Output Tax created in Step 3>"]
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Receivable Account created in Step 2>",
        "transaction_type": "IN",
        "narration": "Client Invoice",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Revenue Account created in Step 2>",
            "amount": 100,
            "narration": "Client Invoice Line Item",
            "taxes": ["<id of Output Tax created in Step 3>"]
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Receivable Account created in Step 2>",
    "transaction_type": "IN",
    "narration": "Client Invoice",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Revenue Account created in Step 2>",
        "amount": 100,
        "narration": "Client Invoice Line Item",
        "taxes": ["<id of Output Tax created in Step 3>"]
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Receivable Account created in Step 2>\",
    \"transaction_type\": \"IN\",
    \"narration\": \"Client Invoice\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Revenue Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Client Invoice Line Item\",
        \"taxes\" => [\"<id of Output Tax created in Step 3>\"]
    }]
}";
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": "Client Invoice: IN01/0001 for 110.00 created successfully",
    "resource": {
        "credited": false,
        "transaction_type": "IN",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 3,
        "narration": "Client Invoice",
        "currency_id": 1,
        "transaction_no": "IN01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 2,
        "transaction_name": "Client Invoice",
        "is_posted": false,
        "is_credited": false,
        "amount": 110,
        "tax": {
            "total": 10,
            "OTP": "10.0000"
        },
        "assignable": false,
        "clearable": true,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Client Invoice>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Client Invoice>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Client Invoice>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Client Invoice>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Client Invoice>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Client Receipt #

Invoices that are issued are expected to be settled at some time in the future when the Client provides cash against their outstanding balance. This cash may or may not fully clear the Invoice, and is recorded via a Client Receipt.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Receivable Account created in Step 2>",
        "transaction_type": "RC",
        "narration": "Client Receipt",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Bank Account created in Step 2>",
            "amount": 50,
            "narration": "Client Receipt Line Item"
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Receivable Account created in Step 2>",
    "transaction_type": "RC",
    "narration": "Client Receipt",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Bank Account created in Step 2>",
        "amount": 50,
        "narration": "Client Receipt Line Item"
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Receivable Account created in Step 2>",
        "transaction_type": "RC",
        "narration": "Client Receipt",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Bank Account created in Step 2>",
            "amount": 50,
            "narration": "Client Receipt Line Item"
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Receivable Account created in Step 2>",
    "transaction_type": "RC",
    "narration": "Client Receipt",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Bank Account created in Step 2>",
        "amount": 50,
        "narration": "Client Receipt Line Item"
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Receivable Account created in Step 2>\",
    \"transaction_type\": \"RC\",
    \"narration\": \"Client Receipt\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Bank Account created in Step 2>\",
        \"amount\": 50,
        \"narration\": \"Client Receipt Line Item\"
    }]
}";
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": "Client Receipt: RC01/0001 for 50.00 created successfully",
    "resource": {
        "credited": true,
        "transaction_type": "RC",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 3,
        "narration": "Client Receipt",
        "currency_id": 1,
        "transaction_no": "RC01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 3,
        "transaction_name": "Client Receipt",
        "is_posted": false,
        "is_credited": true,
        "amount": 50,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": false,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Client Receipt>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Client Receipt>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Client Receipt>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Client Receipt>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Client Receipt>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

These three transactions represent the most basic Sales Cycle.

Purchases Cycle #

The purchase cycle represents the expenditure of the Entity on goods and services, which may either be on cash or credit basis.

Cash Purchase (COGS) #

Cash Purchases involve the immediate payment for goods and services received from a Supplier. In this case the purchase is for use in production, and is thus recorded as the Cost of Goods Sold.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Bank Account created in Step 2>",
        "transaction_type": "CP",
        "narration": "Cash Purchase",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of COGS Account created in Step 2>",
            "amount": 100,
            "narration": "Cash Purchase Line Item",
            "taxes": ["<id of Input Tax created in Step 3>"]
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Bank Account created in Step 2>",
    "transaction_type": "CP",
    "narration": "Cash Purchase",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of COGS Account created in Step 2>",
        "amount": 100,
        "narration": "Cash Purchase Line Item",
        "taxes": ["<id of Input Tax created in Step 3>"]
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Bank Account created in Step 2>",
        "transaction_type": "CP",
        "narration": "Cash Purchase",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of COGS Account created in Step 2>",
            "amount": 100,
            "narration": "Cash Purchase Line Item",
            "taxes": ["<id of Input Tax created in Step 3>"]
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Bank Account created in Step 2>",
    "transaction_type": "CP",
    "narration": "Cash Purchase",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of COGS Account created in Step 2>",
        "amount": 100,
        "narration": "Cash Purchase Line Item",
        "taxes": ["<id of Input Tax created in Step 3>"]
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Bank Account created in Step 2>\",
    \"transaction_type\": \"CP\",
    \"narration\": \"Cash Purchase\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of COGS Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Cash Purchase Line Item\",
        \"taxes\" => [\"<id of Input Tax created in Step 3>\"]
    }]
}";
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": "Cash Purchase: CP01/0001 for 110.00 created successfully",
    "resource": {
        "credited": true,
        "transaction_type": "CP",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 2,
        "narration": "Cash Purchase",
        "currency_id": 1,
        "transaction_no": "CP01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 4,
        "transaction_name": "Cash Purchase",
        "is_posted": false,
        "is_credited": true,
        "amount": 110,
        "tax": {
            "total": 10,
            "OTP": "10.0000"
        },
        "assignable": false,
        "clearable": false,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Cogs Purchase>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Cogs Purchase>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Cogs Purchase>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Cogs Purchase>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Cogs Purchase>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Cash Purchase (Administration) #

In contrast to the COGS example above, this purchase is for goods and services that have no connection with the operations of the Entity such as Utilities and Administration.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Bank Account created in Step 2>",
        "transaction_type": "CP",
        "narration": "Cash Purchase",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Expense Account created in Step 2>",
            "amount": 100,
            "narration": "Cash Purchase Line Item 2",
            "taxes": ["<id of Input Tax created in Step 3>"]
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Bank Account created in Step 2>",
    "transaction_type": "CP",
    "narration": "Cash Purchase",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Expense Account created in Step 2>",
        "amount": 100,
        "narration": "Cash Purchase Line Item 2",
        "taxes": ["<id of Input Tax created in Step 3>"]
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Bank Account created in Step 2>",
        "transaction_type": "CP",
        "narration": "Cash Purchase",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Expense Account created in Step 2>",
            "amount": 100,
            "narration": "Cash Purchase Line Item 2",
            "taxes": ["<id of Input Tax created in Step 3>"]
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Bank Account created in Step 2>",
    "transaction_type": "CP",
    "narration": "Cash Purchase",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Expense Account created in Step 2>",
        "amount": 100,
        "narration": "Cash Purchase Line Item 2",
        "taxes": ["<id of Input Tax created in Step 3>"]
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Bank Account created in Step 2>\",
    \"transaction_type\": \"CP\",
    \"narration\": \"Cash Purchase\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Expense Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Cash Purchase Line Item 2\",
        \"taxes\" => [\"<id of Input Tax created in Step 3>\"]
    }]
}";
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": "Cash Purchase: CP01/0002 for 110.00 created successfully",
    "resource": {
        "credited": true,
        "transaction_type": "CP",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 2,
        "narration": "Cash Purchase",
        "currency_id": 1,
        "transaction_no": "CP01/0002",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 5,
        "transaction_name": "Cash Purchase",
        "is_posted": false,
        "is_credited": true,
        "amount": 110,
        "tax": {
            "total": 10,
            "OTP": "10.0000"
        },
        "assignable": false,
        "clearable": false,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Admin Purchase>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Admin Purchase>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Admin Purchase>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Admin Purchase>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Admin Purchase>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Credit Purchase #

For the Credit Purchase Example, we will simulate the purchase of an Asset by the Entity. As such things tend to be expensive, it is common that their purchase is made on credit.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Payable Account created in Step 2>",
        "transaction_type": "BL",
        "narration": "Supplier Bill",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Asset Account created in Step 2>",
            "amount": 100,
            "narration": "Supplier Bill Line Item",
            "taxes": ["<id of Input Tax created in Step 3>"]
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Payable Account created in Step 2>",
    "transaction_type": "BL",
    "narration": "Supplier Bill",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Asset Account created in Step 2>",
        "amount": 100,
        "narration": "Supplier Bill Line Item",
        "taxes": ["<id of Input Tax created in Step 3>"]
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Payable Account created in Step 2>",
        "transaction_type": "BL",
        "narration": "Supplier Bill",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Asset Account created in Step 2>",
            "amount": 100,
            "narration": "Supplier Bill Line Item",
            "taxes": ["<id of Input Tax created in Step 3>"]
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Payable Account created in Step 2>",
    "transaction_type": "BL",
    "narration": "Supplier Bill",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Asset Account created in Step 2>",
        "amount": 100,
        "narration": "Supplier Bill Line Item",
        "taxes": ["<id of Input Tax created in Step 3>"]
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Payable Account created in Step 2>\",
    \"transaction_type\": \"BL\",
    \"narration\": \"Supplier Bill\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Revenue Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Supplier Bill Line Item\",
        \"taxes\" => [\"<id of Input Tax created in Step 3>\"]
    }]
}";
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": "Supplier Bill: BL01/0001 for 110.00 created successfully",
    "resource": {
        "credited": true,
        "transaction_type": "BL",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 5,
        "narration": "Supplier Bill",
        "currency_id": 1,
        "transaction_no": "BL01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 6,
        "transaction_name": "Supplier Bill",
        "is_posted": false,
        "is_credited": true,
        "amount": 110,
        "tax": {
            "total": 10,
            "OTP": "10.0000"
        },
        "assignable": false,
        "clearable": true,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Bill>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Bill>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Bill>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Bill>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Bill>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

Supplier Payment #

A Supplier Payment is used to record the transfer of cash from the Entity to a supplier in clearance of their outstanding obligations. These payments may or may not clear the whole amount in the outstanding Supplier Bill.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Payable Account created in Step 2>",
        "transaction_type": "PY",
        "narration": "Supplier Payment",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Bank Account created in Step 2>",
            "amount": 50,
            "narration": "Supplier Payment Line Item"
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Payable Account created in Step 2>",
    "transaction_type": "PY",
    "narration": "Supplier Payment",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Bank Account created in Step 2>",
        "amount": 50,
        "narration": "Supplier Payment Line Item"
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Payable Account created in Step 2>",
        "transaction_type": "PY",
        "narration": "Supplier Payment",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Bank Account created in Step 2>",
            "amount": 50,
            "narration": "Supplier Payment Line Item"
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Payable Account created in Step 2>",
    "transaction_type": "PY",
    "narration": "Supplier Payment",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Bank Account created in Step 2>",
        "amount": 50,
        "narration": "Supplier Payment Line Item"
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Payable Account created in Step 2>\",
    \"transaction_type\": \"PY\",
    \"narration\": \"Supplier Payment\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Bank Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Supplier Payment Line Item\"
    }]
}";
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": "Supplier Payment: PY01/0001 for 50.00 created successfully",
    "resource": {
        "credited": false,
        "transaction_type": "PY",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 5,
        "narration": "Supplier Payment",
        "currency_id": 1,
        "transaction_no": "PY01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 7,
        "transaction_name": "Supplier Payment",
        "is_posted": false,
        "is_credited": false,
        "amount": 50,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": false,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Payment>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Payment>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Payment>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Payment>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Supplier Payment>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

These four transactions represent the most basic Purchase Cycle.

Financing #

Financing Transactions usually involve changes in the Capital accounts of the Entity. In this example, we will simulate a capital injection by the owners into the business.

Capital Contribution #

From time to time, an enterprise needs to raise funds from its owners to fund operations. This is usually accomplished via direct cash injections which have the effect of increasing the capital balance owed to the owners.

Curl

curl --location --request POST 'https://api.microbooks.io/books/v1/transaction' \
    --header "Authorization: Bearer <bearer_token>" \
    --data-raw '{
        "account_id": "<id of Capital Account created in Step 2>",
        "transaction_type": "JN",
        "narration": "Journal Entry",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Bank Account created in Step 2>",
            "amount": 100,
            "narration": "Journal Entry Line Item",
        }]
    }'

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction"
body = {
    "account_id": "<id of Capital Account created in Step 2>",
    "transaction_type": "JN",
    "narration": "Journal Entry",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Bank Account created in Step 2>",
        "amount": 100,
        "narration": "Journal Entry Line Item",
    }]
}
headers = {"Authorization": "Bearer <bearer_token>"}

response = requests.request("POST", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');
var options = {
    'method': 'POST',
    'url': 'https://api.microbooks.io/books/v1/transaction',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": "<id of Capital Account created in Step 2>",
        "transaction_type": "JN",
        "narration": "Journal Entry",
        "transaction_date": "2022-07-25",
        "line_items": [{
            "account_id": "<id of Bank Account created in Step 2>",
            "amount": 100,
            "narration": "Journal Entry Line Item",
        }]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = '
    "account_id": "<id of Capital Account created in Step 2>",
    "transaction_type": "JN",
    "narration": "Journal Entry",
    "transaction_date": "2022-07-25",
    "line_items": [{
        "account_id": "<id of Bank Account created in Step 2>",
        "amount": 100,
        "narration": "Journal Entry Line Item",
    }]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/transaction', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": \"<id of Capital Account created in Step 2>\",
    \"transaction_type\": \"JN\",
    \"narration\": \"Journal Entry\",
    \"transaction_date\": \"2022-07-25\",
    \"line_items\": [{
        \"account_id\": \"<id of Bank Account created in Step 2>\",
        \"amount\": 100,
        \"narration\": \"Journal Entry Line Item\"
    }]
}";
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": "Journal Entry: JN01/0001 for 100.00 created successfully",
    "resource": {
        "credited": true,
        "transaction_type": "JN",
        "transaction_date": "2022-07-25T00:00:00.000000Z",
        "account_id": 1,
        "narration": "Journal Entry",
        "currency_id": 1,
        "transaction_no": "JN01/0001",
        "exchange_rate_id": 1,
        "entity_id": 1,
        "id": 8,
        "transaction_name": "Journal Entry",
        "is_posted": false,
        "is_credited": true,
        "amount": 100,
        "tax": {
            "total": 0
        },
        "assignable": true,
        "clearable": true,
        "has_integrity": true,
        "line_items": [...],
        "clearances": [],
        "assignments": []
    }
}

Post Transaction #

Curl

curl --location --request GET 'https://api.microbooks.io/books/v1/transaction/post/<id of Journal Entry>' \
--header "Authorization: Bearer <bearer_token>"

Python

import requests

url = "https://api.microbooks.io/books/v1/transaction/post/<id of Journal Entry>"
body = {}
headers = {"Authorization": "Bearer <bearer_token>"}
response = requests.request("GET", url, headers=headers, json=body)

print(response.text)

NodeJs

var request = require('request');

var options = {
    'method': 'GET',
    'url': 'https://api.microbooks.io/books/v1/transaction/post/<id of Journal Entry>',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': null
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

PHP

$client = new Client();
$body = null;
$request = new Request('GET', 'https://api.microbooks.io/books/v1/transaction/post/<id of Journal Entry>', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/transaction/post/<id of Journal Entry>");
client.Timeout = -1;
var request = new RestRequest(Method.GET);
request.AddHeader("Authorization", "Bearer " + <bearer_token>);
IRestResponse response = client.Execute(request);
Console.WriteLine(response.Content);

These transaction represents an example of a Financing Transaction.

For more details on the Transactions endpoint check out the How To Guide page as well as the Postman API Reference.