Line Items

Line Items #

Line items consitute the second part of the Double Entry after a Transaction has established the first part. A Transaction can have multiple Line Items, each with its own Account, multiple Taxes and Discounts. For most Transactions, the amounts on the Line Items are posted to the opposite side of the Double Entry to that of the Transaction’s main Account. The exception is the compound Journal Entry, where the side to post each Line Item amount can be set arbitrarily.

Properties #

Direct Properties #

PropertyTypeDefinition
AmountFloatThe total amount of the Line Item
Net AmountFloatThe amount of the Line Item net of Taxes and Discounts
QuantityFloatA multiplier to be applied to the amount of the Line Item
TaxFloatThe total Tax applied to the the Line Item
DiscountFloatThe total Discount applied to the the Line Item
NarrationStringA short description of the Line Item
Compound TaxBooleanIndicates whether the Line Item has compound Taxes
Tax InclusiveBooleanIndicates whether the Line Item’s amount is inclusive of Taxes
Has Withholding TaxBooleanIndicates whether the Line Item has witholding Taxes
Has Operations DiscountsBooleanIndicates whether the Line Item has operations Discounts
Has Gross DiscountsBooleanIndicates whether the Line Item has a Discount on the Tax inclusive amount

Indirect Properties #

PropertyTypeDefinition
AccountDictionaryThe main Account of the Line Item
TransactionDictionaryThe Transaction to which the Line Item belongs
TaxesListThe Tax resources associated with the Line Item
DiscountsListThe Discount resources associated with the Line Item

Basics #

The parameters required to create a Transaction Resource are the Id of the Account and an amount.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/line-item' \
--data-raw '{
	"account_id": 1,
	"narration": "Test line item",
	"amount": 100
}'

import requests

url = "https://api.microbooks.io/books/v1/line-item"
body = {
    "account_id": 1,
	"narration": "Test line item",
	"amount": 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/line-item',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": 1,
        "narration": "Test line item",
        "amount": 100
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "account_id": 1,
	"narration": "Test line item",
	"amount": 100
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/line-item', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": 1,
	\"narration\": \"Test line item\",
	\"amount\": 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",
    "resource": {
        "uuid": "fdfced1a-7a4a-4553-9c78-96a37d04513b",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "transaction_id": null,
        "narration": null,
        "amount": "100.0000",
        "quantity": "1.0000",
        "tax_inclusive": false,
        "compound_tax": false,
        "entry_type": "DEBIT",
        "credited": false,
        "tax": {
            "total": 0
        },
        "discount": {
            "total": 0
        },
        "net_amount": 100,
        "has_withholding_tax": false,
        "has_gross_discount": false,
        "has_operations_discounts": false
    }
}

Variations #

With Taxes and Discounts #

Already existing Taxes and Discount Resources can be attached to a Line Item during creation by providing lists of their ids.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/line-item' \
--data-raw '{
	"account_id": 1,
	"narration": "Test line item",
	"amount": 100,
    "taxes": [1],
    "discounts": [2]
}'

import requests

url = "https://api.microbooks.io/books/v1/line-item"
body = {
    "account_id": 1,
	"narration": "Test line item",
	"amount": 100,
	"taxes": [1, 2],
    "discounts": [2]
}
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/line-item',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "account_id": 1,
        "narration": "Test line item",
        "amount": 100,
        "taxes": [1, 2],
        "discounts": [2]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "account_id": 1,
	"narration": "Test line item",
	"amount": 100,
	"taxes": [1, 2],
    "discounts": [2]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/line-item', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"account_id\": 1,
	\"narration\": \"Test line item\",
	\"amount\": 100,
	\"taxes\": [1],
    \"discounts\": [2]
}";
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": "LineItem: Dorris Bartell DDS for 100 created successfully",
    "resource": {
        "credited": false,
        "quantity": 1,
        "account_id": 1,
        "amount": 100,
        "narration": "Test Transaction",
        "entity_id": 1,
        "id": 2,
        "tax": {
            "total": 16,
            "BADCE": "16.0000"
        },
        "discount": {
            "total": 11.6,
            "ECABD": "11.6000"
        },
        "net_amount": 88.4,
        "has_withholding_tax": false,
        "has_gross_discount": true,
        "has_operations_discounts": false,
        "account": {
            "uuid": "06d04dfe-a374-4bd4-9a74-420e6fed9ecc",
            "id": 1,
            "entity_id": 1,
            "category_id": 1,
            "currency_id": 1,
            "code": 2,
            "name": "Dorris Bartell DDS",
            "description": null,
            "type": "Reconciliation",
            "is_closed": false
        }
    }
}

Operations #

Add Taxes #

Taxes can be added to a Line Item by calling this endpoint with an array of thier ids. Therefore the Taxes to be added must already be existing in the system.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/line-item/add-taxes/1' \
--data-raw '
    "taxes": [1, 2]

import requests

url = "https://api.microbooks.io/books/v1/line-item/add-taxes/1"
body = {
    "taxes": [1, 2]
}
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/line-item/add-taxes/1',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "taxes": [1, 2]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "taxes": [1, 2]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/line-item/add-taxes/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item/add-taxes/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"taxes\": [1, 2]
}";
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": "LineItem: Test Account for 50 Taxes added successfully",
    "resource": {
        "uuid": "3ad21bc5-21f7-42d8-8dc0-0028c51a3efd",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "transaction_id": 1,
        "narration": "Rem mollitia ut officiis blanditiis.",
        "amount": "50.0000",
        "quantity": "1.0000",
        "tax_inclusive": false,
        "compound_tax": false,
        "entry_type": "DEBIT",
        "credited": false,
        "tax": {
            "total": 13,
            "DABEC": "8.0000",
            "ABCED": "5.0000"
        },
        "discount": {
            "total": 0
        },
        "net_amount": 50,
        "has_withholding_tax": false,
        "has_gross_discount": false,
        "has_operations_discounts": false,
        "account": {
            "uuid": "eaebd366-8ce2-4e38-919d-bcfc8efe5419",
            "id": 1,
            "entity_id": 1,
            "category_id": 1,
            "currency_id": 1,
            "code": 0,
            "name": "Test Account",
            "description": null,
            "type": "Non Current Liability",
            "is_closed": false
        }
    }
}

Get Taxes #

A list of Taxes that have been applied to the Line Item can be retrieved by calling this endpoint.

Request #

curl --location --request GET 'api.microbooks.io/books/v1/line-item/1/taxes'

import requests

url = "https://api.microbooks.io/books/v1/line-item/1/taxes"
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/line-item/1/taxes',
    '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 = '{}';
$request = new Request('GET', 'https://api.microbooks.io/books/v1/line-item/1/taxes', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item/1/taxes");
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",
    "taxes": [
        {
            "applicable_id": 1,
            "amount": "2.5000",
            "name": "Camille Wilkinson",
            "code": "BADCE",
            "type": "Tax"
        },
        {
            "applicable_id": 2,
            "amount": "2.5000",
            "name": "Miss Tiara Langworth",
            "code": "DBCEA",
            "type": "Tax"
        }
    ]
}

Remove Taxes #

Taxes can be removed from an Line Items by calling this endpoint with an array of thier ids.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/line-item/remove-taxes/1' \
--data-raw '
    "taxes": [1, 2]

import requests

url = "https://api.microbooks.io/books/v1/line-item/remove-taxes/1"
body = {
    "taxes": [1, 2]
}
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/line-item/remove-taxes/1',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "taxes": [1, 2]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "taxes": [1, 2]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/line-item/remove-taxes/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item/remove-taxes/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"taxes\": [1, 2]
}";
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": "LineItem: Test Account for 50 Taxes removed successfully",
    "resource": {
        "uuid": "3ad21bc5-21f7-42d8-8dc0-0028c51a3efd",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "transaction_id": 1,
        "narration": "Rem mollitia ut officiis blanditiis.",
        "amount": "50.0000",
        "quantity": "1.0000",
        "tax_inclusive": false,
        "compound_tax": false,
        "entry_type": "DEBIT",
        "credited": false,
        "tax": {
            "total": 0
        },
        "discount": {
            "total": 0
        },
        "net_amount": 50,
        "has_withholding_tax": false,
        "has_gross_discount": false,
        "has_operations_discounts": false,
        "account": {
            "uuid": "eaebd366-8ce2-4e38-919d-bcfc8efe5419",
            "id": 1,
            "entity_id": 1,
            "category_id": 1,
            "currency_id": 1,
            "code": 0,
            "name": "Test Account",
            "description": null,
            "type": "Non Current Liability",
            "is_closed": false
        }
    }
}

Add Discounts #

Discounts can be added to a Line Item by calling this endpoint with an array of thier ids. Therefore the Discounts to be added must already be existing in the system.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/line-item/add-discounts/1' \
--data-raw '
    "discounts": [1]

import requests

url = "https://api.microbooks.io/books/v1/line-item/add-discounts/1"
body = {
    "discounts": [1]
}
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/line-item/add-discounts/1',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "discounts": [1]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "discounts": [1]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/line-item/add-discounts/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item/add-discounts/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"discounts\": [1]
}";
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": "LineItem: Test Account for 50 Discounts added successfully",
    "resource": {
        "uuid": "18d072ff-ba13-4350-8ce8-b8d0827f05b7",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "transaction_id": 1,
        "narration": "Et facere voluptate numquam iusto eaque et asperiores sint.",
        "amount": "50.0000",
        "quantity": "1.0000",
        "tax_inclusive": false,
        "compound_tax": false,
        "entry_type": "DEBIT",
        "credited": false,
        "tax": {
            "total": 0
        },
        "discount": {
            "total": 4,
            "CABED": "4.0000"
        },
        "net_amount": 46,
        "has_withholding_tax": false,
        "has_gross_discount": true,
        "has_operations_discounts": true,
        "account": {
            "uuid": "ac2b4a58-7b74-41a4-95bd-dc2967936662",
            "id": 1,
            "entity_id": 1,
            "category_id": 1,
            "currency_id": 1,
            "code": 5,
            "name": "Test Account",
            "description": null,
            "type": "Current Liability",
            "is_closed": false
        }
    }
}

Get Discounts #

A list of Discounts that have been applied to the Line Item can be retrieved by calling this endpoint.

Request #

curl --location --request GET 'api.microbooks.io/books/v1/line-item/1/discounts'

import requests

url = "https://api.microbooks.io/books/v1/line-item/1/discounts"
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/line-item/1/discounts',
    '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 = '{}';
$request = new Request('GET', 'https://api.microbooks.io/books/v1/line-item/1/discounts', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item/1/discounts");
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",
    "discounts": [
        {
            "applicable_id": 1,
            "amount": "1.0000",
            "name": "Edd Lueilwitz",
            "code": "BADCE",
            "type": "Discount"
        },
        {
            "applicable_id": 2,
            "amount": "2.5000",
            "name": "Dr. Hans Marquardt DVM",
            "code": "CBEAD",
            "type": "Discount"
        }
    ]
}

Remove Discounts #

Discounts can be removed from an Line Items by calling this endpoint with an array of thier ids.

Request #

curl --location --request POST 'api.microbooks.io/books/v1/line-item/remove-discounts/1' \
--data-raw '
    "discounts": [1, 2]

import requests

url = "https://api.microbooks.io/books/v1/line-item/remove-discounts/1"
body =discounts{
    "taxes": [1, 2]
}
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/line-item/remove-discounts/1',
    'headers': {'Authorization': 'Bearer <bearer_token>'},
    'body': '{
        "discounts": [1, 2]
    }'
};
request(options, function (error, response) {
    if (error) throw new Error(error);
    console.log(response.body);
});

$client = new Client();
$body = '{
    "discounts": [1, 2]
}';
$request = new Request('POST', 'https://api.microbooks.io/books/v1/line-item/remove-discounts/1', 
    [headers' => ['Authorization' => 'Bearer <bearer_token>']], 
    $body
);
$res = $client->sendAsync($request)->wait();
echo $res->getBody();

var client = new RestClient("https://api.microbooks.io/books/v1/line-item/remove-discounts/1");
client.Timeout = -1;
var request = new RestRequest(Method.POST);
var body = "{
    \"discounts\": [1, 2]
}";
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": "LineItem: Test Account for 50 Discounts removed successfully",
    "resource": {
        "uuid": "18d072ff-ba13-4350-8ce8-b8d0827f05b7",
        "id": 1,
        "entity_id": 1,
        "account_id": 1,
        "transaction_id": 1,
        "narration": "Et facere voluptate numquam iusto eaque et asperiores sint.",
        "amount": "50.0000",
        "quantity": "1.0000",
        "tax_inclusive": false,
        "compound_tax": false,
        "entry_type": "DEBIT",
        "credited": false,
        "tax": {
            "total": 0
        },
        "discount": {
            "total": 0
        },
        "net_amount": 50,
        "has_withholding_tax": false,
        "has_gross_discount": false,
        "has_operations_discounts": false,
        "account": {
            "uuid": "ac2b4a58-7b74-41a4-95bd-dc2967936662",
            "id": 1,
            "entity_id": 1,
            "category_id": 1,
            "currency_id": 1,
            "code": 5,
            "name": "Test Account",
            "description": null,
            "type": "Current Liability",
            "is_closed": false
        }
    }
}

Errors #

Below are the Errors that are returned by the Line Item Resource.

Detail CodeNameDefinition
100Orphaned ItemsCannot recycle the Line Item Resource because it has dependent Resources
101Missing EntityThe Line Item Resource requires an existing Entity because it is used for balancing Transactions, for the purpose of preparing Financial Statements which are scoped to an Entity
102Negative AmountA negative amount on a Line Ltem Resource is meaningless
103Negative QuantityA quantity amount on a Line Ltem Resource is meaningless
104Multiple Applicable ErrorThe combination of Taxes/Discounts being attached to the Line Item Resource is invalid according to the rules of IFRS/Bookkeeping
105Posted TransactionTo maintain the integrity of the Ledger, a Transaction Resource’s Line Items cannot be modified once it has been posted. One would have to cancel it via its reversing Transaction and then create a new one