Opening Balance

While migrating from existing accounting software to Zoho Books, you need to ensure that the transition is flawless, that all prevailing data such as journal entries, records, expense and income statements etc, has been recorded and continuity in financial statements is maintained. To ensure this, an opening balance needs to be calculated.

End Points

POST

/settings/openingbalances

PUT

/settings/openingbalances

GET

/settings/openingbalances

DELETE

/settings/openingbalances

Attribute

opening_balance_id

string

ID of opening balance.

date

string

Date on which the opening balance needs to be recorded. [yyyy-MM-dd]

price_precision

integer

Price Precision of the Values

accounts

array

Show Sub-Attributes

acount_split_id

string

ID of split account that you want to update.

account_id

string

ID of account for which you need to record opening balance.

account_name

string

debit_or_credit

string

Debit or Credit for which the amount needs to be recorded. Allowed Values: debit and credit.

exchange_rate

double

Exchange rate for the foreign currencies if involved.

currency_id

string

ID of account currency.

currency_code

string

bcy_amount

double

Amount in Base Currency of the Organisation

amount

double

total

integer

Total Amount from the Opening Balance

{
    "opening_balance_id": "460000000050041",
    "date": "2013-10-01",
    "price_precision": 2,
    "accounts": [
        {
            "acount_split_id": "460000000050045",
            "account_id": "460000000000358",
            "account_name": "Undeposited Funds",
            "debit_or_credit": "debit",
            "exchange_rate": 1,
            "currency_id": "460000000000097",
            "currency_code": "USD",
            "bcy_amount": 2000,
            "amount": 2000
        }
    ],
    "total": 10000
}

Create opening balance

Creates opening balance with the given information.
OAuth Scope : ZohoBooks.settings.CREATE

Arguments

date

string

(Required)

Date on which the opening balance needs to be recorded. [yyyy-MM-dd]

accounts

array

Show Sub-Attributes

account_id

string

ID of account for which you need to record opening balance.

debit_or_credit

string

(Required)

Debit or Credit for which the amount needs to be recorded. Allowed Values: debit and credit.

exchange_rate

double

Exchange rate for the foreign currencies if involved.

currency_id

string

ID of account currency.

amount

double

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695"
type: POST
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695")
  .post(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'POST',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("POST", "/books/v3/settings/openingbalances?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "POST",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/settings/openingbalances?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request POST \
  --url 'https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "date": "2013-10-01",
    "accounts": [
        {
            "account_id": "460000000000358",
            "debit_or_credit": "debit",
            "exchange_rate": 1,
            "currency_id": "460000000000097",
            "amount": 2000
        }
    ]
}

{
    "code": 0,
    "message": "The opening balances are saved!",
    "opening_balance": {
        "opening_balance_id": "460000000050041",
        "date": "2013-10-01",
        "price_precision": 2,
        "accounts": [
            {
                "acount_split_id": "460000000050045",
                "account_id": "460000000000358",
                "account_name": "Undeposited Funds",
                "debit_or_credit": "debit",
                "exchange_rate": 1,
                "currency_id": "460000000000097",
                "currency_code": "USD",
                "bcy_amount": 2000,
                "amount": 2000
            }
        ],
        "total": 10000
    }
}

Update opening balance

Updates the existing opening balance information.
OAuth Scope : ZohoBooks.settings.UPDATE

Arguments

date

string

Date on which the opening balance needs to be recorded. [yyyy-MM-dd]

accounts

array

Show Sub-Attributes

acount_split_id

string

ID of split account that you want to update.

account_id

string

ID of account for which you need to record opening balance.

account_name

string

debit_or_credit

string

Debit or Credit for which the amount needs to be recorded. Allowed Values: debit and credit.

exchange_rate

double

Exchange rate for the foreign currencies if involved.

currency_id

string

ID of account currency.

currency_code

string

bcy_amount

double

Amount in Base Currency of the Organisation

amount

double

opening_balance_id

string

(Required)

ID of opening balance.

parameters_data='{"field1":"value1","field2":"value2"}';
headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695"
type: PUT
headers: headers_data
content-type: application/json
parameters: parameters_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

MediaType mediaType = MediaType.parse("application/json");
RequestBody body = RequestBody.create(mediaType, "{\"field1\":\"value1\",\"field2\":\"value2\"}");
Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695")
  .put(body)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .addHeader("content-type", "application/json")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'PUT',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f',
    'content-type': 'application/json'
  },
  body: '{"field1":"value1","field2":"value2"}'
};

fetch('https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

payload = "{\"field1\":\"value1\",\"field2\":\"value2\"}"

headers = {
    'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    'content-type': "application/json"
    }

conn.request("PUT", "/books/v3/settings/openingbalances?organization_id=10234695", payload, headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "PUT",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/settings/openingbalances?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f",
    "content-type": "application/json"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.write(JSON.stringify({field1: 'value1', field2: 'value2'}));
req.end();

curl --request PUT \
  --url 'https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f' \
  --header 'content-type: application/json' \
  --data '{"field1":"value1","field2":"value2"}'

{
    "date": "2013-10-01",
    "accounts": [
        {
            "acount_split_id": "460000000050045",
            "account_id": "460000000000358",
            "account_name": "Undeposited Funds",
            "debit_or_credit": "debit",
            "exchange_rate": 1,
            "currency_id": "460000000000097",
            "currency_code": "USD",
            "bcy_amount": 2000,
            "amount": 2000
        }
    ],
    "opening_balance_id": "460000000050041"
}

{
    "code": 0,
    "message": "The opening balances are saved!",
    "opening_balance": {
        "opening_balance_id": "460000000050041",
        "date": "2013-10-01",
        "price_precision": 2,
        "accounts": [
            {
                "acount_split_id": "460000000050045",
                "account_id": "460000000000358",
                "account_name": "Undeposited Funds",
                "debit_or_credit": "debit",
                "exchange_rate": 1,
                "currency_id": "460000000000097",
                "currency_code": "USD",
                "bcy_amount": 2000,
                "amount": 2000
            }
        ],
        "total": 10000
    }
}

Get opening balance

Get opening balance.
OAuth Scope : ZohoBooks.settings.READ

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695"
type: GET
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695")
  .get()
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'GET',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("GET", "/books/v3/settings/openingbalances?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "GET",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/settings/openingbalances?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request GET \
  --url 'https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "code": 0,
    "message": "success",
    "opening_balance": {
        "opening_balance_id": "460000000050041",
        "date": "2013-10-01",
        "price_precision": 2,
        "accounts": [
            {
                "acount_split_id": "460000000050045",
                "account_id": "460000000000358",
                "account_name": "Undeposited Funds",
                "debit_or_credit": "debit",
                "exchange_rate": 1,
                "currency_id": "460000000000097",
                "currency_code": "USD",
                "bcy_amount": 2000,
                "amount": 2000
            }
        ],
        "total": 10000
    }
}

Delete opening balance

Delete the entered opening balance.
OAuth Scope : ZohoBooks.settings.DELETE

headers_data = Map();
headers_data.put("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f");
response = invokeUrl
[
url: "https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695"
type: DELETE
headers: headers_data
connection: <connection_name>
]
info response;

OkHttpClient client = new OkHttpClient();

Request request = new Request.Builder()
  .url("https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695")
  .delete(null)
  .addHeader("Authorization", "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f")
  .build();

Response response = client.newCall(request).execute();

const options = {
  method: 'DELETE',
  headers: {
    Authorization: 'Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'
  }
};

fetch('https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

import http.client

conn = http.client.HTTPSConnection("www.zohoapis.com")

headers = { 'Authorization': "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f" }

conn.request("DELETE", "/books/v3/settings/openingbalances?organization_id=10234695", headers=headers)

res = conn.getresponse()
data = res.read()

print(data.decode("utf-8"))

const http = require("https");

const options = {
  "method": "DELETE",
  "hostname": "www.zohoapis.com",
  "port": null,
  "path": "/books/v3/settings/openingbalances?organization_id=10234695",
  "headers": {
    "Authorization": "Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f"
  }
};

const req = http.request(options, function (res) {
  const chunks = [];

  res.on("data", function (chunk) {
    chunks.push(chunk);
  });

  res.on("end", function () {
    const body = Buffer.concat(chunks);
    console.log(body.toString());
  });
});

req.end();

curl --request DELETE \
  --url 'https://www.zohoapis.com/books/v3/settings/openingbalances?organization_id=10234695' \
  --header 'Authorization: Zoho-oauthtoken 1000.41d9xxxxxxxxxxxxxxxxxxxxxxxxc2d1.8fccxxxxxxxxxxxxxxxxxxxxxxxx125f'

{
    "code": 0,
    "message": "The entered opening balance has been deleted."
}