ERPNext IntegrationDocumentation
Book a meeting

02Start

Getting started

11 min read

Create an API key in ERPNext, paste it into the app, pick the defaults the app should use for new records, then switch on the sync areas and ERPNext webhooks you want. Finish by placing a test order.

Step 1: Create an API key in ERPNext

The app signs in to ERPNext with an API key and secret belonging to one ERPNext user. Use a dedicated integration user so you can see in ERPNext which changes the app made.

  1. Open the user the app will sign in as

    In ERPNext, go to the User list and open (or create) the user for the integration. Make sure the user is enabled and has the roles described below.

  2. Generate the keys

    In recent ERPNext versions, open the Settings tab of the user, find the API Access section and click Generate Keys. ERPNext shows the API Secret once, in a pop-up.

  3. Copy both values

    Copy the API Secret from the pop-up straight away — ERPNext does not show it again. The API Key stays visible on the user record. If you lose the secret, generate new keys; the old secret stops working.

The API user needs enough permission

The app reads and creates Customers, Addresses, Items, Sales Orders, Sales Invoices, Delivery Notes and Payment Entries, and it creates Custom Fields and Webhooks in ERPNext. The app does not check the user's roles: the connection test only checks that the key and secret sign in. If a role is missing, that part of the sync fails later with ERPNext's permission error in the logs. As general ERPNext guidance, creating Custom Fields and Webhooks usually needs the System Manager role; ask your ERPNext consultant if you prefer a narrower custom role.

Step 2: Connect on the Configuration page

Open Configuration in the app's left-hand navigation. Until you are connected and the Default Company and Default Warehouse are saved, the same form is also shown on the Home page, under “Welcome to ERPNext Integrator”.

  1. Enter the ERPNext Host URL

    The address of your site, including https:// — for example https://yourcompany.erpnext.com. Use the site address only, without /app or any other path.

  2. Paste the API Key and API Secret

    Paste the two values from step 1. As you type, the app tests the connection — the Setup guide card shows “Testing connection...” and then one of the badges below. Nothing is stored yet.

  3. Save

    Click Save in the save bar that appears at the top of the page. The app checks the credentials with ERPNext again before storing them; if the check fails, the reason is shown in a red banner on the form and nothing is saved. On success, your Companies, Warehouses and other masters load into the ERPNext Defaults dropdowns.
On the Setup guide cardWhat it means
SuccessERPNext Account is Connected
ERPNext accepted the API key and secret.
CriticalConnection Failed
The test did not sign in. The start of the reason is shown next to the badge — for example ERPNext's own error, “Invalid ERPNext credentials”, “Could not connect to ERPNext instance” or “Connection timed out. Check that ERPNext is reachable.” Click Save to see the full message in a banner.
InfoNot Configured
Host URL, API Key or API Secret is still empty.
Testing connection...Shown with a spinner while a test is running — when the page opens and shortly after you change the Host URL, API Key or API Secret.

The Setup guide card also links to this Documentation and to Schedule a meeting, where you can book a call with the support team.

Your ERPNext site must be reachable from the internet

The app connects from the cloud. A site that only works inside your office network, behind a VPN, or on localhost cannot be connected, and the test ends with “Could not connect to ERPNext instance” or “Connection timed out. Check that ERPNext is reachable.” Real-time updates also need the reverse path: your ERPNext site must be able to send webhooks out to the app.

Getting the Host URL right

A wrong Host URL is a common cause of failures. Include https://, use the address you open ERPNext with in your browser, and leave off paths such as /app or /desk. If the test reports “Invalid ERPNext credentials” or an authentication error from ERPNext, the address is right and the key or secret is wrong — generate new keys and paste both again.

Step 3: Choose your ERPNext defaults

Defaults are the ERPNext values the app uses when it creates something new — a Sales Order, an Item, a Customer. All six are marked required. Four start pre-selected with ERPNext's standard values, so on a new store you usually only pick Default Company and Default Warehouse. Once the dropdowns have loaded, Save stays disabled, under a warning to select all six, until each one has a value.

SettingWhat it doesDefault
ERPNext Host URLThe address of your ERPNext site, including https://.Empty
API Key / API SecretThe keys generated for your ERPNext API user in step 1.Empty
Default CompanyThe company Sales Orders, Sales Invoices and Payment Entries from Shopify are booked to. Also used for new Items and stock.None (“Select a company...”)
Default WarehouseThe warehouse used on order lines and for shipping and fee lines, and for stock of newly created Items. Used as a fallback when an Item has no warehouse of its own.None (“Select a warehouse...”)
Default Item GroupThe item group given to Items the app creates in ERPNext, for example from an order line that has no matching Item.All Item Groups
Default Unit of MeasureThe stock UOM given to Items the app creates in ERPNext.Nos
Default Customer GroupThe customer group given to new Customers, whether they come from a Shopify order or from Export Customers to ERPNext.All Customer Groups
Default TerritoryThe territory given to new Customers, whether they come from a Shopify order or from Export Customers to ERPNext.All Territories

On the very first save the dropdowns are still empty, so the app usually saves your connection and then shows “Please complete ERPNext Defaults: Default Company, Default Warehouse are required.” That is expected: the dropdowns are now filled — pick the values and click Save again. A successful save shows “ERPNext credentials saved successfully!”

A dropdown that says nothing was found

Until the connection is saved, or while it is not working, every dropdown reads, for example, “No companies found - please check ERPNext configuration” and is greyed out. If it still says that with a working connection, ERPNext returned no records of that type to the API user: either they do not exist yet, or the user's roles cannot read them. Create them or fix the role in ERPNext, then reload the Configuration page.

Sync pages warn until the defaults are complete

Until all six defaults are saved, the sync pages show a banner reading “ERPNext defaults are incomplete — set Company, Warehouse, Item Group, Unit of Measure, Customer Group, and Territory before syncing.” with a Configure button that opens this page. Finish this step before you enable any sync.

Optional: field mappings and collections

Two more cards on the Configuration page. Both apply when data comes from ERPNext into Shopify, and both can be left empty. Set them on the Configuration page itself: their field lists only load there, once the connection is saved.

Field mappings

Copy an ERPNext field into Shopify when customers or products are imported from ERPNext. Click Add mapping rule, choose Customer or Product under Map, search for the ERPNext Customer field or ERPNext Item field, then set Shopify target to Standard field (and pick the Shopify field) or Metafield (and pick the customer or product metafield). Remove deletes a rule. For an alternate unit of measure, pick the ERPNext field labelled “UOM conversion factor (…)”. Rules are saved with the Save button like the rest of the page.

Shopify Collections

Pick an ERPNext Item field in ERPNext Item field for collections, and each imported product is added to the Shopify collections named in that field. Separate several names with commas — “Summer, Sale” adds the product to both. Collections that do not exist yet are created as manual collections. Leave it on Disabled (no collections) to skip this.

Step 4: Turn on each sync area

Once your connection is saved, Products Sync, Customer Sync and Order Sync appear in the navigation. Each has an Enable / Disable choice at the top and saves on its own.

PageWhat to do before you enable it
Order SyncChoose the Order Naming Series, decide which documents to create (Sales Invoice, Payment Entry, Delivery Notes) and complete the invoice and payment fields those need. Enable Order Sync stays greyed out until the required fields are filled.
Products SyncSet Enable Products Sync to Enable and save. The Import Products from ERPNext, Sync inventory only and Import last 24 hours modified buttons then appear at the top of the page, and stay disabled until at least one Shopify location is mapped to an ERPNext warehouse under Products Location Mapping. Choose which Items and fields to sync, then run Import Products from ERPNext.
Customer SyncSet Enable Customer Sync to Enable and save. The Export Customers to ERPNext and Import Customers from ERPNext buttons then appear at the top of the page.

You do not need every area

Areas are independent. A store that only wants its orders in ERPNext can enable Order Sync and leave the rest off. Orders still create the Customers and Items they need.

Step 5: Switch on the ERPNext webhooks

ERPNext webhooks are what let changes made in ERPNext reach Shopify straight away. Each one is a switch that takes effect at once, without the Save button: turning it on creates the Webhook in your ERPNext site, set up to tell the app which store it belongs to, and turning it off deletes it again. The switches are available once your ERPNext credentials are saved. Create them from the app rather than by hand in ERPNext, so they carry the headers and fields the app needs.

WebhookWhereWhat it does for you
Inventory (Stock Ledger Entry → on_update)Products Sync, under Enable ERPNext webhooks (products sync)When stock moves in ERPNext — a sale, a receipt, a stock entry — the new quantity is pushed to the mapped Shopify location.
Order cancel (Sales Order → on_cancel)Order Sync, under ERPNext webhooks for real-time syncCancelling a Sales Order that came from Shopify cancels the matching Shopify order. The Shopify order is tagged erpnext_cancelled so the cancel is not sent back to ERPNext.
Delivery note (Delivery Note → on_submit)Order Sync, under ERPNext webhooks for real-time syncSubmitting a Delivery Note in ERPNext marks the Shopify order fulfilled. A return Delivery Note records a return on the Shopify order.
Delivery note cancel (Delivery Note → on_cancel)Order Sync, under ERPNext webhooks for real-time syncCancelling a Delivery Note in ERPNext cancels the fulfilment on the Shopify order.

Switching to a different ERPNext site

Webhooks live in the ERPNext site they were created in. If you ever change the Host URL to another site, switch the ERPNext webhooks off first, then connect the new site and switch them back on — otherwise the old site keeps its webhooks and keeps sending updates.

Step 6: Check it with a test order

The quickest way to confirm the whole chain works.

  1. Place a test order in Shopify

    Use a product whose SKU matches an ERPNext Item code, so you can also see that line items match.

  2. Watch the order log

    On the Home page, open the Order sync tab of the Logs. The order usually appears within a few seconds, with a Sync Status of SUCCESS, FAILED or SKIPPED and the reason when it fails.

  3. Find the Sales Order in ERPNext

    Click the ERPNext Order link on the log row, or open the Sales Order list in ERPNext. The new order uses the Order Naming Series you chose (the app suggests SO-Shopify-) and carries the Shopify order number.

  4. Try the way back

    If you switched on the Delivery note webhook, submit a Delivery Note for the order in ERPNext and check that the Shopify order shows as fulfilled. Each ERPNext webhook the app receives is listed in the ERPNext webhooks tab of the Logs.

If the order did not arrive

  • Check that Enable Order Sync is set to Enable and saved on the Order Sync page. While it is off, orders are logged as SKIPPED with “Order sync is disabled in settings”.
  • Read the failure message in the Order sync log — a permission error points at the API user's roles, a missing account or series points at Order Sync settings.
  • Once fixed, press Resync on the log row instead of placing another order.

Next steps