AJAX Calls in Frappe Framework v15
What Is an AJAX Call in Frappe?
An AJAX call in Frappe Framework v15 is a mechanism that allows client-side JavaScript to communicate asynchronously with server-side Python code without reloading the page. Frappe provides a built-in wrapper called frappe.call, which securely handles requests, permissions, and responses.
AJAX calls form the backbone of dynamic behavior in ERPNext forms and pages.
Why Use AJAX Calls in ERPNext?
AJAX calls enable real-time interaction between the user interface and backend logic.
Key Benefits
- No page reloads
- Faster user experience
- Secure server-side validation
- Clean separation of frontend and backend logic
They are essential for validations, data fetching, and automation in ERPNext.
Who Should Use Frappe AJAX Calls?
Target Audience
- ERPNext Developers
- Frappe Framework Developers
- ERP Functional Consultants
- Frontend Customization Engineers
Technical Prerequisites
- Frappe Framework v15
- JavaScript (ES6)
- Python basics
- Understanding of DocTypes
How Do AJAX Calls Work in Frappe v15?
Frappe AJAX calls follow a simple request–response lifecycle:
- Client-side JavaScript triggers frappe.call
- Request is sent to the server
- A whitelisted Python method is executed
- Server returns a structured response
- Callback or Promise handles the result
Core API: frappe.call
Source (v15): frappe/public/js/frappe/request.js
How to Make a Basic AJAX Call in Frappe v15?
Client-Side Example
frappe.call({
method: "frappe.client.get",
args: {
doctype: "User",
name: "Administrator"
},
callback: function (r) {
console.log(r.message);
}
});
What this does:
Fetches the Administrator User document from the server and returns it asynchronously to the browser.
How to Call Custom Python Methods Using AJAX?
Step 1: Create a Whitelisted Python Method
import frappe
@frappe.whitelist()
def get_company():
return frappe.defaults.get_global_default("company")
Only methods decorated with @frappe.whitelist() can be called from the client.
Step 2: Call the Method from JavaScript
frappe.call({
method: "my_app.api.get_company",
callback: function (r) {
frappe.msgprint(r.message);
}
});
This pattern is the recommended and secure way to expose backend logic.
How Are Parameters Passed in AJAX Calls?
Arguments are passed using the args object and mapped by name.
frappe.call({
method: "my_app.api.get_customer_credit",
args: {
customer: "ABC Pvt Ltd"
}
});
Frappe automatically validates and parses parameters on the server.
What Does an AJAX Response Contain?
The response object (r) contains:
| Property | Description |
| r.message | Main return value |
| r.exc | Exception details (if any) |
| r._server_messages | System messages |
Always read data from r.message.
Using AJAX Calls Inside Forms (Desk Scripting)
frappe.ui.form.on('Sales Order', {
customer(frm) {
frappe.call({
method: "my_app.api.get_customer_credit",
args: { customer: frm.doc.customer },
callback(r) {
frm.set_value('credit_limit', r.message);
}
});
}
});
This enables dynamic, data-driven form behavior.
Real-World ERPNext Use Cases
Industry Relevance
- Sales: Pricing and discount validation
- Manufacturing: BOM and stock checks
- Finance: Credit limit verification
- HR: Attendance and leave validations
AJAX calls allow ERPNext to remain interactive and responsive.
Best Practices for Frappe AJAX Calls
- Always whitelist server methods
- Keep heavy logic on the server
- Validate permissions in Python
- Return only required data
- Handle errors gracefully
Common Issues and Troubleshooting
AJAX Call Not Working
- Verify method path
- Ensure method is whitelisted
- Check browser console for errors
Permission Error
- Confirm user roles
- Validate DocType permissions
- Avoid bypassing security checks
Advanced AJAX Patterns in Frappe v15
Promise-Based AJAX Calls
frappe.call({
method: "my_app.api.get_data"
}).then(r => {
console.log(r.message);
});
Frappe v15 supports Promise chaining for cleaner async logic.
AJAX Calls vs REST API
| Feature | AJAX Call | REST API |
| Authentication | Session-based | Token-based |
| Usage | Internal UI | External systems |
| Security | Built-in | Explicit |
Use AJAX calls for internal ERPNext UI logic.
Integration Patterns
Frappe AJAX integrates seamlessly with:
- Desk Scripting
- Server Calls
- Workflows
- Reports
- Custom Pages
It is the primary bridge between frontend and backend in ERPNext.
Official References (Verified)
Frappe AJAX Call Guide (v15):
https://docs.frappe.io/framework/user/en/guides/basics/frappe_ajax_call
Frappe GitHub (v15):
