Using Custom API Rows

A management-report line may be impossible to produce from account categories alone, for example a specialised budget-adjusted metric calculated by an installed custom app. The value must appear beside standard account lines and remain available to later formulas.

A Financial Report Template Enhanced row with Data Source set to Custom API calls an approved server-side Python function. Use it only when Account Data and Calculated Amount rows cannot express the requirement. This is an advanced developer feature, not a way to call an external HTTP endpoint from the report.

Before you begin

• Use a site where the custom Frappe app can be installed and deployed.
• Implement and test a module-level Python function in that app.
• Confirm the function's performance, permissions, data access, and error handling.
• Create or identify the Financial Report Template Enhanced that needs the row.

Add the Custom API row

1. Open the template.
2. Add a row in Report Line Items and open its row editor.
3. Set Data Source to Custom API.
4. Enter a dotted Python path such as my_app.financial_report_api.get_budget_variance.
5. Set a Line Reference when later formula rows need the returned value.
6. Configure Reverse Sign, Hide If Zero, Hidden Line, Include in Charts, and Value Type as required.
7. Save the template and run Financial Statement Enhanced.

Function contract

The method receives the report filters, generated periods, and current row. Return one numeric value for each period, in the same order.

CSF OHADA requires the function to be whitelisted and to permit GET.

from frappe.utils import flt

@frappe.whitelist(methods=["GET"])
def get_budget_variance(filters=None, periods=None, row=None):
    filters = filters or {}
    periods = periods or []
    values = []

    for period in periods:
        variance = calculate_variance(
            company=filters.get("company"),
            from_date=period.from_date,
            to_date=period.to_date,
        )
        values.append(flt(variance))

    return values

Return requirements

Important behaviour

The path must use the form app.module.method. The function must exist in an installed app. @frappe.whitelist(methods=["GET"]) is required. Server Scripts are not supported.

The same list is copied to every non-empty Value Column. The function cannot return a different series per measure.

Secure and test the function

Validate filter values, use permission-aware queries, avoid returning sensitive detail, and keep queries bounded. Test no-data periods, multiple periodicities, company separation, and error conditions. Reconcile the result with an independent calculation before publishing the template.

Troubleshooting

The API path is rejected

Use a complete dotted module path. Confirm the function is defined at module level, is whitelisted, and permits GET.

The row shows zeros

Review Error Log for a Custom API error, confirm the function returned one numeric value per period, and test the function with the same report filters.

A calculated row cannot use the result

Give the Custom API row a unique Line Reference and use that exact reference in the later formula.

Frequently asked questions

Can the row call a public REST API directly?

The template calls a Python function on the ERPNext server. That function may integrate with another system according to your app's security design.

Can the function change accounting data?

A reporting function should be read-only. Creating or changing transactions during report execution would make results unsafe.

What happens when the function raises an error?

The app records an error and can fill the row with zeros. Treat that state as a failed calculation and investigate before sharing the output.