Integrating ERPNext With Mobile Apps: Complete Technical Guide

Why Mobile Integration Matters in Modern ERP Systems

Modern businesses are shifting from desktop-only ERP usage to mobile-first workflows. Sales executives, field service engineers, delivery agents, inventory managers, and operations teams often work away from the office. They need real-time access to ERP data: stock levels, customer details, order status, tasks, and tickets.

ERPNext, built on the Frappe Framework, is a web-based ERP that exposes a powerful set of REST APIs. These APIs allow mobile apps to:

• Read and write data (Customers, Items, Sales Orders, Tasks, etc.).
• Trigger business workflows (approvals, submissions, notifications).
• Integrate with third-party services (Firebase, SMS gateways, logistics APIs).

In this guide, we will design an end-to-end architecture for ERPNext + Mobile App integration and implement it step by step.

ERPNext REST API Architecture Explained

ERPNext follows a REST-style API structure where each DocType is treated as a resource, and each document is an instance of that resource. The API endpoints are predictable and consistent, which makes mobile integration easier.

Generic resource URL pattern:

/api/resource/<DocType>/<Name>

Example:

/api/resource/Customer/CUST-0001

All API interactions go through the Frappe ORM layer, which ensures that validations, permissions, and DocType logic are applied consistently whether data comes from the web UI or a mobile app.

ERPNext Authentication Methods for Mobile Apps

Before a mobile app can access ERPNext data, it must authenticate itself. ERPNext supports multiple authentication methods, but for mobile applications we typically use token-based authentication.

For mobile apps, we avoid storing user passwords directly. Instead, we use API keys generated per user in ERPNext and send them via Authorization headers.

Generating API Keys for a Mobile User

Follow these steps inside ERPNext:

1. Login as a System Manager or Administrator.
2. Go to Users → open the user that will be used for mobile API access (for example, mobile.api@yourcompany.com).
3. Scroll down to the API Access section in the user form.
4. Click on Generate Keys.
5. ERPNext will create:
   • API Key
   • API Secret
6. Copy and securely store these values. Do not expose secrets in client-side code or public repositories.

In a secure architecture, these credentials should be used by your backend (Node.js, Python, etc.), and the mobile app communicates with your backend instead of directly talking to ERPNext. However, in simpler setups, mobile apps can directly call ERPNext with these tokens.

Sample Mobile Authentication Call (Flutter / JavaScript)

Below is a sample request using JavaScript fetch, which is also conceptually similar to Flutter's HTTP client usage.

JavaScript Example

fetch("https://erp.example.com/api/resource/Item", {
  method: "GET",
  headers: {
    "Authorization": "token API_KEY:API_SECRET",
    "Content-Type": "application/json"
  }
})
  .then(response => response.json())
  .then(data => {
    console.log("Items:", data);
  })
  .catch(error => {
    console.error("Error:", error);
  });

Expected JSON Response (Sample)

{
  "data": [
    {
      "name": "ITEM-001",
      "item_name": "Laptop Sleeve",
      "stock_uom": "Nos"
    },
    {
      "name": "ITEM-002",
      "item_name": "Wireless Mouse",
      "stock_uom": "Nos"
    }
  ]
}

Testing ERPNext APIs Using Postman

Before building mobile screens, always validate APIs using tools like Postman. This helps to confirm endpoints, headers, and responses.

1. Open Postman and create a new request.
2. Select the HTTP method (for example, GET).
3. Enter the URL, e.g.:

   https://yourerp.com/api/resource/Customer

4. Go to the Headers tab and add:

   Key	Value
   Authorization	token API_KEY:API_SECRET
   Content-Type	application/json

5. Click Send.
6. Check the response JSON and status code. If successful, you can safely reuse the same structure inside your mobile application.

Mobile to ERPNext Data Flow (High-Level Workflow)

At a high level, the mobile-to-ERPNext request lifecycle looks like this:

This ensures that all business rules are enforced centrally in ERPNext, with the mobile app acting as a thin client layer.

Designing Mobile App Modules for ERPNext Integration

Think of the mobile app as a collection of business modules. Each module will map to one or more ERPNext DocTypes and API endpoints.

Creating Customers From Mobile App (Step and Code)

For field agents, creating customers from the mobile app is a very common requirement.

Steps

1. Design a mobile form to capture basic customer details (name, phone, email, territory, customer group, etc.).
2. On form submission, validate data locally (mandatory fields, phone number format).
3. Send a POST request to the ERPNext Customer DocType API.
4. Handle success (show success message, store ERPNext customer name) and errors (validation, permission issues).

Example JavaScript Code

fetch("https://erp.example.com/api/resource/Customer", {
  method: "POST",
  headers: {
    "Authorization": "token API_KEY:API_SECRET",
    "Content-Type": "application/json"
  },
  body: JSON.stringify({
    "customer_name": "Alex Mathew",
    "customer_group": "Individual",
    "territory": "India",
    "mobile_no": "9876543210",
    "email_id": "alex@test.com"
  })
})
  .then(response => response.json())
  .then(data => {
    console.log("Customer created:", data);
  })
  .catch(error => {
    console.error("Error:", error);
  });

Sample Response

{
  "data": {
    "name": "CUST-0021",
    "customer_name": "Alex Mathew",
    "customer_group": "Individual",
    "territory": "India"
  }
}

Integrating Mobile Sales Order Creation With ERPNext

A sales app typically allows users to select a customer, add items, and submit an order from the mobile device. That order must then be created as a Sales Order in ERPNext.

Steps

1. Fetch allowed customers and items from ERPNext (and cache if needed).
2. Let user build a cart: select items, enter quantities, view totals.
3. Generate JSON payload matching ERPNext Sales Order schema.
4. Send POST request to /api/resource/Sales Order.
5. Optionally submit the Sales Order (if your business allows direct submission).

Sample Payload

{
  "customer": "CUST-0021",
  "company": "My Company",
  "delivery_date": "2025-01-10",
  "items": [
    {
      "item_code": "ITEM-001",
      "qty": 3,
      "rate": 220
    },
    {
      "item_code": "ITEM-002",
      "qty": 1,
      "rate": 450
    }
  ]
}

Once the Sales Order is created, ERPNext can handle pricing rules, taxes, discounts, and further workflows like delivery notes and sales invoices.

Building an Offline Sync Mechanism for Mobile Apps

Many businesses operate in regions with poor or intermittent internet connectivity. Mobile apps must continue working offline and sync data when the network is available.

Offline Architecture

Key considerations for offline sync:

• Use a local database (like SQLite in Android / Flutter) to store unsynced records.
• Track sync status (e.g., PENDING, SYNCED, FAILED) for each record.
• Implement a background job or scheduled task in the mobile app to push pending records periodically.
• Handle conflicts (for example, when data on server changed after local caching).

Using ERPNext Webhooks for Real-Time Mobile Notifications

Instead of mobile apps constantly polling ERPNext, we can use webhooks to push data out whenever key events occur (for example, Sales Order submitted, Ticket assigned, Task updated).

Example Use Case

Whenever a new Sales Order is submitted in ERPNext, notify the mobile backend, which then sends a push notification to the salesperson.

Sample Webhook Payload

{
  "doc": {
    "name": "SO-0005",
    "customer": "Alex Mathew",
    "grand_total": 540,
    "status": "Submitted"
  },
  "event": "on_submit",
  "doctype": "Sales Order"
}

The mobile backend receives this payload, processes it, and can store or transform the data according to the app’s requirement.

Integrating Firebase Push Notifications With ERPNext Events

To alert users instantly on their mobile devices, you can combine ERPNext webhooks with Firebase Cloud Messaging (FCM).

Typical Notification Flow

Examples of events to trigger mobile notifications:

• New Task assigned to a technician.
• Sales Order approved or rejected.
• Support Issue updated with new comments.
• Stock transfer created for a warehouse.

Using GraphQL (If Enabled) for Complex Mobile Data Fetch

In some advanced setups, GraphQL is used to optimize data transfer by fetching exactly the required fields in a single request.

Sample GraphQL Query (Conceptual)

query {
  Employee(name: "EMP-0001") {
    employee_name
    department
    attendance {
      date
      status
    }
  }
}

This approach reduces over-fetching and under-fetching, which is beneficial in bandwidth-sensitive mobile scenarios.

Securing API Access With Role-Based Permissions

Instead of giving broad access to all DocTypes, create a dedicated role for mobile users and assign only necessary permissions.

Example Role Setup

Create a role named Mobile User and configure permissions as below:

Note: Apply least-privilege principle. Give only minimum permissions required for mobile app usage.

API Rate Limiting and Performance Tuning

High traffic from mobile users can overload the server if not controlled. You can configure API rate limiting using Nginx in front of ERPNext.

Example Nginx Snippet

limit_req_zone $binary_remote_addr zone=api_limit:10m rate=10r/s;

server {
  ...

  location /api/ {
    limit_req zone=api_limit burst=20 nodelay;
    proxy_pass http://frappe-bench;
  }

  ...
}

Additionally, enable Redis caching in ERPNext to reduce database load and speed up frequently requested data.

Using Background Jobs for Heavy Mobile Sync Operations

Certain operations, such as syncing thousands of items or bulk stock transfers, should not be executed in a single HTTP request. Instead, trigger a background job in ERPNext.

Python Example Using enqueue

import frappe
from frappe import enqueue

def start_bulk_sync():
  enqueue("my_app.api.sync_inventory",
          queue="long",
          timeout=800)

The mobile app can trigger an API that starts the background job and then poll or subscribe to the job status if needed.

Implementing Pagination for Large Data Sets

When loading large lists (like thousands of Items or Customers), always use pagination in your mobile app to avoid slow and heavy responses.

ERPNext Pagination Parameters

• limit_start — starting offset
• limit_page_length — number of records to fetch

Example Request

GET /api/resource/Item?limit_start=0&limit_page_length=50

In the mobile UI, you can implement “Load More” or infinite scroll using these parameters.

Error Handling and Logging ERPNext API Calls

Proper error handling is essential for a good mobile user experience and easier troubleshooting.

Common HTTP Status Codes

Checking Logs in ERPNext Bench

bench --site site1.local logs

You can also integrate with external monitoring tools (like Sentry) using Frappe’s logging hooks to capture exceptions and performance issues.

Deployment Checklist for ERPNext + Mobile Integration

Before going live with your mobile app integration, review the following checklist to ensure stability, security, and performance.

Conclusion & Key Takeaways

ERPNext, combined with a well-designed mobile application, becomes a powerful engine for real-time, field-friendly business operations. With REST APIs, webhooks, role-based permissions, background jobs, and proper error handling, you can build robust, secure, and scalable mobile solutions on top of ERPNext.

By following the steps and patterns in this guide—authentication setup, API testing, offline sync, webhooks, notifications, background jobs, and deployment best practices—you can design a production-ready ERPNext mobile integration that supports sales teams, field service technicians, warehouse staff, and management users across your organization.