Exchange Rate Revaluation

The purpose of Exchange Rate Revaluation is to adjust the balance in General Ledger accounts according to any changes in the currency exchange rates. This is useful when you are closing your accounts books and want to update your Company’s GL accounts by bringing in the money from other currency accounts. Exchange Rate Revaluation feature is for dealing with the situation when you have accounts with different currencies in one Company’s Chart of Accounts.

Exchange rate revaluation is the process of adjusting the value of foreign currency-denominated assets and liabilities on a company’s balance sheet to reflect current exchange rates. This ensures that financial statements accurately represent the company’s financial position, particularly when dealing with transactions in multiple currencies.

Get list of Exchange Rate Revaluations

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.list
Method: GET
Payload:

{
    "doctype": "Exchange Rate Revaluation",
    "fields": ["name", "posting_date", "total_gain_loss"],
    "filters": [["posting_date", ">=", "1970-01-01"]],
    "start": 0,
    "page_length": 0,
    "order_by": "creation desc"
}

Headers

{
    "Authorization": "token <YOUR_TOKEN>"
}

Refer to Document List API Parameters for guidance on the payload

Get a single Exchange Rate Revaluation

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.get
Method: GET
Payload:

{
    "doc_id": "<DOC_ID>"
}

Headers

{
    "Authorization": "token <YOUR_TOKEN>"
}

Create Exchange Rate Revaluation

It is important to note that only foreign denominated accounts with balances are subject to revaluation.

To get the list of accounts that can be revalued at a specific point (end of month etc), use the below endpoint

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.get_accounts_to_revalue
Method: POST
Payload:

{
    "as_at_date": "2025-06-30",
    "show_summarized": true
}

Headers

{
   "Authorization": "token <YOUR_TOKEN>"
}

The response will be of the from

{
    "message": {
        "success": true,
        "status": 200,
        "data": [
            {
                "account": "1201 - KCB - USD - DCL",
                "party_type": "",
                "party": "",
                "account_currency": "USD",
                "balance_in_base_currency": 256000.0,
                "balance_in_account_currency": 2000.0,
                "zero_balance": false,
                "current_exchange_rate": 128.0,
                "new_exchange_rate": 0.0,
                "new_balance_in_base_currency": 0.0,
                "new_balance_in_account_currency": 2000.0,
                "gain_loss": -256000.0
            }
        ]
    }
}

The list of accounts in the data property represent those that can be revalued at the specified posting_date. If the list is empty, it means there is no foreign currency denominated account that has a balance to revalue.

Note

Use this get_accounts_to_revalue to get a list of the accounts to be revalued as you are creating an Exchange Rate Revaluation record. Use it to get the accounts to revalue including the current balance
Getting the list of revaluable accounts is important in situations when an institution does not want to revalue all the foreign currency denominated accounts
If the value of show_summarized parameter is true, the result will be grouped by distinct accounts. If the value is false, the result will be for all transactions that need revaluation

To create an Exchange Rate Revaluation record, call this endpoint

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.create
Method: POST
Payload:

{
    "posting_date" : "2025-06-30",
    "company": "Demo Company Ltd",
    "new_exchange_rate" : 131,
    "accounts": [{
                "account": "1201"
            }
        ],
    "created_by": "Nyaga",
    "created_on": "2025-04-16",
    "approved_by": "Steve",
    "approved_on": "2025-04-20",
}

Headers

{
   "Authorization": "token <YOUR_TOKEN>"
}

Warning

Creating an Exchange Rate Revaluation involves 2 steps:
1. Retrieve the list of accounts that can be revalued. The list comes with the balance for each account. Use the get_accounts_to_revalue end point
2. Call the create end point with the relevant payload
Exchange Rate Revaluations are made at the end of a period e.g month or financial year. You can automate this process by having a scheduled job

Reverse Exchange Rate Revaluation

Reversals of Exchange Revaluations are usually done at the beginning of a period. The reversal is for the exchange rate revaluation that was made in the previous month. Refer to Exchange Rate Gain/Loss for guidance on reversals

To reverse an Exchange Rate Revaluation using this endpoint:

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.reverse
Method: POST
Payload:

{
    "doc_id": "ACC-ERR-2025-00008",
    "posting_date" : "2025-08-06",
    "company": "EQUITY FOR TANZANIA",
    "reversal_reason": "Sample reason",
    "created_by": "Nyaga",
    "created_on": "2025-04-16",
    "approved_by": "Steve",
    "approved_on": "2025-04-20",
}

Headers

{
    "Authorization": "token <YOUR_TOKEN>"
}

Delete Exchange Rate Revaluation

An Exchange Rate Revaluation generates journal entries when it is created. Before you can delete an exchange rate revaluation, ensure you have deleted any journal entries and reversal journal entries linked to the exchange rate revaluation.

After deleting these journals, you can now call this endpoint

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.delete
Method: DELETE
Payload:

{
    "doc_id": "<DOC_ID>"
}

Headers

{
    "Authorization": "token <YOUR_TOKEN>"
}

Exchange Rate Revaluation Report

1. To get a report of the accounts that can be revalued at a specific point in time, call this end point

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.get_accounts_to_revalue
Method: POST
Payload:

{
    "as_at_date": "2025-06-30"
}

Headers

{
   "Authorization": "token <YOUR_TOKEN>"
}

The response will be of the from

{
    "message": {
        "success": true,
        "status": 200,
        "data": [
            {
                "account": "1201 - KCB - USD - DCL",
                "party_type": "",
                "party": "",
                "account_currency": "USD",
                "balance_in_base_currency": 256000.0,
                "balance_in_account_currency": 2000.0,
                "zero_balance": false,
                "current_exchange_rate": 128.0,
                "new_exchange_rate": 0.0,
                "new_balance_in_base_currency": 0.0,
                "new_balance_in_account_currency": 2000.0,
                "gain_loss": -256000.0
            }
        ]
    }
}

2. To get a report of all Exchange Rate Revaluations, call this end point

Endpoint: {SERVER_URL}/api/method/eclectics.api.exchange_rate_revaluation.list
Method: GET
Payload:

{
    "doctype": "Exchange Rate Revaluation",
    "fields": ["name", "posting_date", "total_gain_loss"],
    "filters": [["posting_date", ">=", "1970-01-01"]],
    "start": 0,
    "page_length": 0,
    "order_by": "creation desc"
}

Headers

{
    "Authorization": "token <YOUR_TOKEN>"
}

3. To get a report of all journal entries for Exchange Rate Revaluation and Reversals, call the Journal Entry list API while passing the appropriate filter on voucher type. See below

Endpoint: {SERVER_URL}/api/method/eclectics.api.journal_entry.list
Method: GET
Payload:

{
    "fields": [
        "name",
        "title",
        "posting_date",
        "voucher_type",
        "total_amount_currency"
    ],
    "filters": [["voucher_type", "=", "Exchange Gain Or Loss"]],
    "start": 0,
    "page_length": 0,
    "order_by": "creation desc"
}

Headers:

{
    "Authorization": "token <YOUR_TOKEN>"
}