Description
n8n-nodes-erpnext-buying
Community n8n node package for ERPNext/Frappe Buying v15-v16.
This package is part of the n8n2erpnext ecosystem. It focuses on ERPNext procurement and supplier-side workflows, while keeping generic escape hatches for custom DocTypes and whitelisted Frappe methods.
Connected Ecosystem Coverage
Buying is live-tested as part of a connected ERPNext business lifecycle, not as a standalone procurement helper.
The Stock validation suite includes end-to-end workflows that connect Buying, Stock, Selling, and Accounting:
- Standard Product Lifecycle: Supplier -> Purchase Receipt -> inventory increase -> Purchase Invoice -> Customer Sale -> Sales Invoice
update_stock = 1-> inventory decrease. - Exception / After-Sales Lifecycle: sale -> return credit note -> warranty warehouse -> defective warehouse -> repair/virtual workshop -> disposal.
- Cross-module lock validation: linked Purchase Invoice blocks unsafe Purchase Receipt cancellation.
- Ledger validation:
Bin,Stock Ledger Entry, Purchase Receipt, Purchase Invoice, Sales Invoice, and Stock Entry documents are verified after submit. - ERP administrators who maintain ERPNext/Frappe.
- Procurement, warehouse, finance, or operations teams that need supplier, RFQ, purchase order, receipt, or invoice workflows.
- Integration teams that want repeatable n8n automations without writing custom Frappe client code for every buying process.
This proves the Buying node participates in the full operational chain: purchasing goods into the business, handing inventory to Stock, and preserving accounting integrity after invoicing.
Live-Tested Status
This package has been live-tested end to end on the project ERPNext/Frappe test environment:
| Area | Status |
| — | — |
| ERPNext/Frappe target | Live-tested on ERPNext v16/Frappe v16 behavior |
| n8n runtime | Live-tested on self-hosted n8n 2.20.7-exp.0 |
| Infrastructure | Live-tested through LXD ERPNext container at http://10.192.135.2:8001 with host header erp.thaiduy.digital |
| API coverage | Live-tested with Frappe API v1 read workflows and API v2 document workflows |
| Module lifecycle | Supplier, RFQ, Supplier Quotation, Purchase Order, Purchase Receipt, Purchase Invoice bridge, and amendment/negative cases |
| Ecosystem coverage | Buying -> Stock -> Selling -> Accounting end-to-end workflows |
| Cross-module lock coverage | Linked Purchase Invoice blocks unsafe Purchase Receipt cancellation |
| Security response policy | Public webhook responses were allowlisted summaries; securityFindings: [] |
| Cleanup | Temporary workflows were deactivated and verified as 404 Active version not found |
The live verification used traceable demo records in the ERPNext LXD test instance. The README intentionally includes test infrastructure routing values and document IDs, but no API keys, API secrets, Authorization headers, database passwords, npm tokens, or credential material.
Who This Is For
This package is built for teams that run ERPNext Buying and want controlled procurement automations in n8n.
Typical users:
The node is intentionally conservative: it exposes standard Buying document operations, supports Frappe API v1 and v2, and allows controlled fallback access to custom DocTypes and whitelisted Frappe methods.
Architecture At A Glance
Read workflow from left to right:
ERPNext / Frappe Buying <---- API token ----> n8n ERPNext Buying node <---- webhook/API ----> Client / App / Report
Common read pattern:
Client
-> n8n Webhook
-> ERPNext Buying node
-> Frappe REST API
-> ERPNext Buying DocType
-> filtered JSON response
Common procurement lifecycle pattern:
n8n Webhook / Schedule / App Event
-> validation / mapping / approval logic
-> ERPNext Buying node
-> Supplier, Material Request, RFQ, Supplier Quotation, Purchase Order, or Purchase Receipt
-> safe summary response or downstream system
Recommended production network pattern:
Public Client
-> HTTPS reverse proxy / VPN / allowlist
-> n8n
-> private network or internal VPS address
-> ERPNext / Frappe site
Supported Resources
Custom DocType is used when a procurement workflow crosses into another ERPNext module, such as Purchase Invoice or Payment Entry.
Node Identity
All n8n2erpnext module nodes use the same ERPNext-style logo shape. Each module changes only the main background color.
| Module | Color | Hex | Reason |
| — | — | — | — |
| Core | ERPNext blue | #2490EF | Foundation package, closest to the ERPNext brand color. |
| HRMS | People green | #2E7D5F | Human operations, employees, attendance, leave, payroll. |
| Accounting | Finance orange-red | #D94A2B | Ledger, journals, invoices, financial control. |
| Buying | Procurement amber | #C47F00 | Purchase flow, suppliers, RFQs, purchase orders, receipts, spend. |
| Selling | Commerce teal | #00A6A6 | Customer-facing pipeline, quotations, sales orders, revenue. |
| Stock | Frappe black | #171717 | Warehouses, items, inventory movement; aligned with Frappe black. |
When building another module, copy the HRMS/Accounting SVG structure and change only the main background fill to that module color.
Operations
For Buying doctypes:
For Frappe methods:
API Versions
The node supports both ERPNext/Frappe document API styles:
v1: /api/resource/:doctypev2: /api/v2/document/:doctypeUse v1 for broad compatibility. Use v2 when your ERPNext/Frappe v16 environment is ready for the newer document API behavior.
Submit and cancel use the shared n8n2erpnext helper rule:
{ doc } to frappe.client.submit.{ doctype, name } to frappe.client.cancel.Reference:
Credentials
Create an API key and secret in ERPNext/Frappe, then configure:
https://erp.example.comerp.example.comThe node authenticates with:
Authorization: token apikey:apisecret
Credential fields are marked as password fields where appropriate. Do not expose API keys, API secrets, Authorization headers, tokens, or passwords in webhook responses, logs, README examples, or package artifacts.
Internal URL With Public Host Header
When n8n and ERPNext run on the same VPS, you can point n8n at the internal ERPNext address and still send the public ERPNext host header:
http://erpnext.internal:8001erp.example.comThis avoids public reverse-proxy authentication while still letting ERPNext receive the expected site host.
For the current VPS/LXD test setup:
Site URL: http://10.192.135.2:8001
Site Host Header: erp.thaiduy.digital
This is infrastructure routing information for the project test environment, not credential material. API keys and API secrets are not included in this README.
For production, create a dedicated ERPNext integration user instead of using a daily admin account. Give that user only the roles required for the workflows it runs.
Official Frappe references:
Examples
Get recent suppliers:
{
"resource": "supplier",
"operation": "getMany",
"apiVersion": "v1",
"fields": "name,suppliername,suppliergroup,supplier_type,country,disabled",
"filtersJson": "[]",
"returnAll": false,
"limit": 20,
"orderBy": "modified desc"
}
Get submitted purchase orders:
{
"resource": "purchaseOrder",
"operation": "getMany",
"apiVersion": "v2",
"fields": "name,supplier,transactiondate,grandtotal,status,per_received",
"filtersJson": "[["docstatus","=",1]]",
"returnAll": false,
"limit": 20,
"orderBy": "transaction_date desc"
}
Run a whitelisted Frappe method:
{
"resource": "frappeMethod",
"operation": "runMethod",
"methodName": "frappe.client.get_value",
"argumentsJson": {
"doctype": "Purchase Order",
"filters": { "name": "PUR-ORD-2026-00003" },
"fieldname": ["name", "supplier", "grand_total", "status"]
}
}
Use Custom DocType for procurement-adjacent documents:
{
"resource": "customDocType",
"customDocType": "Purchase Invoice",
"operation": "get",
"apiVersion": "v2",
"documentName": "ACC-PINV-2026-00002"
}
Webhook From n8n To ERPNext Buying
Use this pattern when you want an HTTP endpoint in n8n that reads or writes Buying data in ERPNext.
Client / Browser / App
-> n8n webhook URL
-> ERPNext Buying node
-> Frappe REST API
-> ERPNext Buying DocType
-> JSON response or safe summary
1. Configure The ERPNext Credential
In n8n, create or edit an ERPNext API credential:
http://erpnext.internal:8001erp.example.comfalseFor the current VPS/LXD test setup:
Site URL: http://10.192.135.2:8001
Site Host Header: erp.thaiduy.digital
2. Create A Read Workflow
Create a workflow with these nodes:
GET Webhook -> ERPNext Buying
Webhook node:
GETerpnext-buying-get-suppliersWhen Last Node FinishesAll EntriesERPNext Buying node:
ERPNext API credentialSupplierGet Manyv1name,suppliername,suppliergroup,supplier_type,country,disabled[]false20modified desc3. Activate And Test
Activate the workflow, then call:
curl -i https://n8n.example.com/webhook/erpnext-buying-get-suppliers
On the local VPS, you can test without going through the public proxy:
curl -i http://127.0.0.1:5678/webhook/erpnext-buying-get-suppliers
The tested workflow artifact is included in this repository:
n8n-webhook-erpnext-buying-get-suppliers.workflow.json
Webhook From ERPNext v16 To n8n
Use this pattern when ERPNext should call n8n automatically after a Buying document is created or updated. For example, ERPNext can call a n8n workflow whenever a Purchase Order, Purchase Receipt, or Supplier Quotation changes.
ERPNext Doc Event
-> Frappe Webhook
-> POST n8n webhook URL
-> n8n workflow
-> validation, notification, sync, approval, audit, or downstream automation
1. Create The n8n Webhook Receiver
Create a workflow in n8n with a Webhook trigger:
Webhook -> your processing nodes
Webhook node:
POSTerpnext-buying-eventNone for a private/internal test, or Header Auth for productionImmediately or When Last Node FinishesThe production webhook URL will look like:
https://n8n.example.com/webhook/erpnext-buying-event
On this VPS, if ERPNext and n8n are on the same host/network, you can also use an internal n8n URL from ERPNext.
2. Add The Webhook In ERPNext/Frappe v16
In ERPNext/Frappe Desk:
1. Open the global search bar.
2. Search for Webhook.
3. Open Webhook from the Integrations area.
4. Click New.
Configure the Webhook:
Purchase Order, Purchase Receipt, Supplier Quotation, or another Buying DocTypeonsubmit, oncancel, afterinsert, or onupdate depending on the workflowPOSTJSONExample JSON body:
{
"event": "purchaseordersubmitted",
"doctype": "{{ doc.doctype }}",
"name": "{{ doc.name }}",
"supplier": "{{ doc.supplier }}",
"company": "{{ doc.company }}",
"transactiondate": "{{ doc.transactiondate }}",
"grandtotal": "{{ doc.grandtotal }}",
"status": "{{ doc.status }}",
"modified": "{{ doc.modified }}"
}
For production, add a shared secret header and validate it in n8n:
X-ERPNext-Webhook-Secret: your-long-random-secret
If you use Frappe’s Webhook Secret field, Frappe adds an X-Frappe-Webhook-Signature header generated from the payload and secret. You can verify this signature in n8n with a Code node if needed.
Official Frappe reference:
Tested Workflow Artifacts
The repository includes workflow artifacts used during live ERPNext LXD testing.
Read-only artifact:
n8n-webhook-erpnext-buying-get-suppliers.workflow.json
Write-test artifacts:
n8n-webhook-erpnext-buying-v2-procurement-lifecycle-test.workflow.json
n8n-webhook-erpnext-buying-v2-real-procurement-flow-test.workflow.json
n8n-webhook-erpnext-buying-v2-purchase-order-amend-test.workflow.json
Negative/security artifact:
n8n-webhook-erpnext-buying-v2-negative-cases-test.workflow.json
Buying write-test workflows create real demo/test documents in the ERPNext LXD test instance. Activate them only during testing and deactivate them after verification unless a trusted operator intentionally keeps them active.
GET Suppliers Test
Workflow artifact:
n8n-webhook-erpnext-buying-get-suppliers.workflow.json
Test shape:
GET Webhook -> ERPNext Buying
ERPNext Buying node:
SupplierGet Manyv1name,suppliername,suppliergroup,supplier_type,country,disabled20modified descVerified result:
HTTP/1.1 200 OK.N8N-ACC-LIFECYCLE-1778752708065 Supplier.The test workflow was deactivated after verification.
Procurement Lifecycle Test
Workflow artifact:
n8n-webhook-erpnext-buying-v2-procurement-lifecycle-test.workflow.json
Test shape:
POST Webhook
-> Create Supplier
-> Create Item
-> Create and submit Material Request
-> Create and submit Supplier Quotation
-> Create and submit Purchase Order
-> Create and submit Purchase Receipt
-> Return safe summary
Verified result:
HTTP/1.1 200 OK.N8N-BUY-LIFECYCLE-1779032443792.MAT-MR-2026-00002, submitted.PUR-SQTN-2026-00002, submitted, grand total 90.PUR-ORD-2026-00002, submitted, grand total 90.MAT-PRE-2026-00002, submitted, grand total 90.2 units of N8N-BUY-LIFECYCLE-1779032443792-PROC-ITEM into Stores - TDD.securityFindings: [].The test workflow was deactivated after verification.
Real Procurement Flow Test
Workflow artifact:
n8n-webhook-erpnext-buying-v2-real-procurement-flow-test.workflow.json
This workflow tests Buying as an ERP process, not only CRUD:
Supplier with Vietnamese/special characters
-> Supplier get/update
-> Disabled Supplier readback
-> Two purchase Items with Vietnamese/spaces
-> Multi-item Material Request submit
-> Multi-supplier RFQ submit/cancel
-> Multi-item Supplier Quotation submit
-> Multi-item Purchase Order with tax template and discount
-> Partial Purchase Receipt from Purchase Order
-> Purchase Invoice via Custom DocType
-> Partial Payment Entry submit/cancel via Custom DocType
-> Full Payment Entry via Custom DocType
-> Purchase Order readback via Custom DocType "Purchase Order"
The first run exposed a real ERPNext validation issue:
Request for Quotation.subject is required.stockuom, uom, and conversionfactor.After fixing the workflow payload, the live test passed.
Verified result:
HTTP/1.1 200 OK.N8N-BUY-REAL-1779033077692.N8N-BUY-REAL-1779033077692 NCC Đặc biệt & Space / Test.disabled: 1.PUR-RFQ-2026-00001 was submitted then cancelled.PUR-SQTN-2026-00003 submitted with grand total 490.PUR-ORD-2026-00003 submitted with two items, discount 5, grand total 485, and per_received 40.MAT-PRE-2026-00003 submitted as partial receipt with stock ledger rows for both items.ACC-PINV-2026-00002 submitted and paid, grand total 205, outstanding amount 0.ACC-PAY-2026-00003 was submitted then cancelled.ACC-PAY-2026-00004 was submitted for 205.Custom DocType with DocType Purchase Order returned PUR-ORD-2026-00003.securityFindings: [].ERPNext DB verification:
Supplier special name updated successfully; disabled supplier has disabled=1.
RFQ PUR-RFQ-2026-00001: docstatus 2, Cancelled.
Supplier Quotation PUR-SQTN-2026-00003: docstatus 1, Submitted, grand_total 490.
Purchase Order PUR-ORD-2026-00003: docstatus 1, status To Receive and Bill, grandtotal 485, discountamount 5, per_received 40.
Purchase Order items:
N8N-BUY-REAL-1779033077692 Hàng mua đặc biệt A | qty 2 | rate 125 | amount 250
N8N-BUY-REAL-1779033077692 Item With Spaces B | qty 3 | rate 80 | amount 240
Purchase Receipt MAT-PRE-2026-00003: docstatus 1, Completed, grand_total 205.
Stock Ledger:
Item A actual_qty 1 into Stores - TDD
Item B actual_qty 1 into Stores - TDD
Purchase Invoice ACC-PINV-2026-00002: docstatus 1, Paid, grandtotal 205, outstandingamount 0.
Payment Entry ACC-PAY-2026-00003: docstatus 2, Pay, paid_amount 103.
Payment Entry ACC-PAY-2026-00004: docstatus 1, Pay, paid_amount 205.
The test workflow was deactivated after verification.
Purchase Order Amend Test
Workflow artifact:
n8n-webhook-erpnext-buying-v2-purchase-order-amend-test.workflow.json
Test shape:
Create Supplier
-> Create Item
-> Create Purchase Order
-> Submit Purchase Order
-> Cancel Purchase Order
-> Create amended Purchase Order with amended_from
-> Submit amended Purchase Order
-> Return safe summary
Verified result:
HTTP/1.1 200 OK.N8N-BUY-AMEND-1779033301954.PUR-ORD-2026-00004 was submitted then cancelled.2.PUR-ORD-2026-00004-1 was created with amended_from: PUR-ORD-2026-00004.1.2.The test workflow was deactivated after verification.
Negative Cases Test
Workflow artifact:
n8n-webhook-erpnext-buying-v2-negative-cases-test.workflow.json
Test shape:
POST Webhook
-> Try duplicate Supplier create
-> Try Purchase Order missing required Supplier
-> Try cancel linked Purchase Order
-> Try delete submitted Purchase Receipt
-> Try get fake Purchase Order name with slash/spaces
-> Return safe negative summary
Verified result:
HTTP/1.1 200 OK.PUR-ORD-2026-00003.MAT-PRE-2026-00003.PUR-ORD-2026-00003 failed as expected.MAT-PRE-2026-00003 failed as expected.securityFindings: [].Wrong API key was tested directly against ERPNext/Frappe:
GET /api/resource/Purchase%20Order?limitpagelength=1
Authorization: token invalidkey:invalidsecret
HTTP/1.1 401 UNAUTHORIZED
{"exc_type":"AuthenticationError"}
The test workflow was deactivated after verification.
Development
npm install
npm run lint
npm run build
npm pack
The package declares n8n-workflow as both:
peerDependencies: host n8n provides runtime packagedevDependencies: local TypeScript/lint/build supportform-data is pinned through overrides to avoid the unsafe boundary random vulnerability reported by Dependabot on older transitive versions.
Release Checklist
Before tagging a release:
npm ci
npm run lint
npx @n8n/node-cli lint
npm run build
npx @n8n/node-cli build
npm audit --omit=dev
npm pack --dry-run
For provenance publishing, push a semver tag that matches package.json:
git tag v0.1.x
git push origin main
git push origin v0.1.x
The GitHub Actions workflow publishes to npm with provenance:
npm publish --access public --provenance
Test Policy
The ERPNext LXD environment used by this project is allowed to receive realistic demo/test procurement data. Buying workflow tests should use traceable test prefixes and should avoid leaking raw ERPNext documents or credential-like fields in public webhook responses.
Temporary write-test workflows should be deactivated after verification. Current live tests confirmed these endpoints returned 404 Active version not found after cleanup:
/webhook/erpnext-buying-v2-real-procurement-flow-test
/webhook/erpnext-buying-v2-negative-cases-test
/webhook/erpnext-buying-v2-purchase-order-amend-test
Security Notes
Recommended baseline:
Get Many with explicit Fields over Get when exposing webhook responses, because Get can return full documents including comments, owners, child tables, totals, stock, and accounting metadata.Site Host Header.Security Notice
This package pins transitive form-data resolution with an npm overrides entry so npm audit --omit=dev reports no known vulnerabilities at release time. Keep this override in place until upstream dependencies resolve to a safe version without assistance.
In this package’s tested deployment model, security risk is also reduced by:
Do not treat this mitigation as a permanent substitute for dependency maintenance. Re-run npm audit --omit=dev before publishing a new package version and upgrade compatible n8n dependencies when the upstream dependency chain allows it without breaking n8n node compatibility.
Deployment Checklist For SME And Mid-Market Teams
Before going live:
v1 or v2.Site Host Header if ERPNext is served by a named Frappe site.Suggested production approach:
Troubleshooting
401 or 403: verify API key, API secret, user roles, and DocType permissions in ERPNext.EPROTO or tlsv1 alert internal error: use the internal ERPNext HTTP URL from n8n when the public domain is protected by a reverse proxy or VPN layer.Site Host Header to the public ERPNext site name.Request for Quotation create fails: verify subject and child item fields such as stockuom, uom, and conversionfactor.Purchase Order submit fails: verify supplier, item purchase flags, schedule date, warehouse, UOM, tax template, and company.Purchase Receipt submit fails: verify stock item settings, accepted warehouse, purchase order item references, and over-receipt rules.Purchase Invoice or Payment Entry fails through Custom DocType: verify payable account, expense account, supplier, linked receipt/invoice, and fiscal period.Scope Boundaries
This package is intentionally Buying-focused. Other ERPNext modules should live in separate packages so each module can evolve independently:
n8n-nodes-frappe-coren8n-nodes-erpnext-hrmsn8n-nodes-erpnext-accountingn8n-nodes-erpnext-buyingn8n-nodes-erpnext-sellingn8n-nodes-erpnext-stockUse Custom DocType for adjacent documents when a Buying workflow needs to cross into another module, such as Purchase Invoice and Payment Entry. If a workflow is mostly financial, prefer the Accounting package.
References
Frappe / ERPNext:
n8n:
Maintainer Notes
Prepared and reviewed with care by Codex for the n8n2erpnext ERPNext Buying integration work.
