ERPNext and Amazon Seller Central integration

How ERPNext and Amazon Seller Central integration works

Orders and listings live in Seller Central, while stock, invoices and the books live in ERPNext. The ecommerce_integrations app bridges the two by connecting to Amazon through the Selling Partner API (SP-API), pulling marketplace products and orders into ERPNext where they become items, customers and Sales Orders. Once they are there, the rest of the accounting and stock work happens in ERPNext. The exact sync scope, including which marketplaces, order statuses, fulfillment channels and fee lines are brought across, depends on the installed version of the app, so your team should confirm that against the release you plan to run before anything else is designed.

Before building anything, confirm three things with the app documentation and your own Amazon account: which SP-API roles and seller authorization your selling account must grant, which Amazon marketplaces the connector supports for your country, and how it handles orders that are canceled, returned or fulfilled by Amazon. Each of these changes what appears in ERPNext and when. Also confirm which ERPNext version your site runs, since the connector and its dependencies are tied to the Frappe and ERPNext release line. Write the answers down as part of the scope, because they decide the item mapping, the order mapping and the settlement design covered in the sections that follow.

Treat the connector as the start of the data flow, not the whole process. Amazon settlement reports, referral fees, fulfillment charges and refunds arrive on a different timeline from the orders that generate them, so the books need a deliberate plan for how those amounts are posted to ERPNext accounts. The connector's coverage of these lines is one of the first things to verify in a test site, using a few representative orders from each fulfillment path. Gaps found at that stage are cheaper to close in a fixed-scope design than after a month of live orders have been posted to the wrong accounts.

What you need in place before connecting Amazon to ERPNext

The Amazon connection depends on three sides lining up: a supported ERPNext version, a Seller Central account whose owner grants SP-API access, and a server that can reach Amazon's endpoints. Check each one before any credentials are entered, because a gap on any side usually surfaces as a failed sync rather than a clear error.

Supported ERPNext major version

Plan on ERPNext version 15 or version 16. Version 14 reached end of life on January 31, 2026, so a site still on 14 needs an upgrade before the Amazon connector is set up. Confirm the exact ecommerce_integrations app version that matches your ERPNext release, since the app is installed separately and its compatibility is tied to the core version. Record the version in your implementation scope so every later step is tested against it.

Frappe Cloud or self-hosted installation

Decide where the site runs before building the integration. Frappe Cloud hosts the site and manages the bench, while a self-hosted site runs with bench on Linux, Docker Compose or another supported method on infrastructure you control. Self-hosting carries no license fee, but the server, backups, TLS and app updates become your responsibility. Either way, the site needs a background worker and scheduler running, because order and inventory sync jobs execute there.

Matching Frappe Cloud support plan

If you run on Frappe Cloud, or want Frappe warranty coverage for a self-hosted site, the customer must be on a listed version and subscribed to a Frappe Cloud support plan that matches that version. Without it, Frappe does not warrant the platform, which matters when a connector fault reaches production orders. Ask your DeployOpen scope to state whether warranty coverage is part of the plan and which support tier applies to your version.

Seller Central account and owner role

Confirm who holds the Seller Central account and whether that person can create and authorize a private developer application for SP-API. The account owner or a user with equivalent permissions must approve the access grant, and the seller should decide in advance which marketplaces, such as the United States or European Union regions, the integration will cover. Mismatched marketplace or region choices are a common cause of empty order pulls, so write them down before setup.

SP-API credentials and least privilege

Create the SP-API application and generate the refresh token and client credentials that ERPNext will store. Request only the roles the connector needs for catalog, orders and inventory, and avoid granting roles for reports or advertising that no sync uses. Store the client secret and refresh token in a password field or a secrets manager you control, and set a rotation owner. Confirm the exact role names and scopes with Amazon's current SP-API documentation at setup time, because they change.

Outbound network and server access

The ERPNext server must make outbound HTTPS calls to Amazon's SP-API and authentication endpoints, and the background workers must be able to reach them, not only the web process. Check egress rules, proxies, DNS resolution and any firewall allowlists, and test from the same host and container network that runs the workers. Also confirm that the site's public URL and TLS certificate are valid, since callback and token flows fail silently when they are not.

Test site and change control

Before connecting a live seller account, prepare a staging site on the same ERPNext version with restored data or sample items. Run the first product and order pulls there, because the connector creates customers, items and Sales Orders that are hard to undo cleanly in a live ledger. Agree who approves production enablement and who can pause the scheduled sync if fees or orders look wrong.

Configuration sequence for the Amazon connector

This sequence takes an ERPNext site from a bare install to a scheduled Amazon Seller Central sync, with a check at each stage so that problems surface on a staging site before live orders and stock move. It is the order most sellers follow, but confirm each detail against the connector version you install.

Match the app to your ERPNext version
Confirm your ERPNext major version (currently 15 or 16 are the supported lines in the researched facts) and install the ecommerce_integrations app on a staging site built from that same version. Your implementation lead or internal platform owner does this with the bench command line tool. Done means the app appears in the installed apps list on the staging site and the Amazon connector settings page opens without errors. Check the app's compatibility notes for your exact version before going further.
Register the SP-API application
The seller account owner registers an SP-API application in Seller Central and authorizes it against the seller account the connector will read. Keep the registration in the seller's name and record who holds the credentials. Done means the seller can see the authorization on the Amazon side and you hold the client identifiers and refresh token in a secure location. Confirm the current registration steps with Amazon, since its developer portal changes over time.
Enter credentials in connector settings
Enter the SP-API credentials and seller details in the Amazon connector settings on the staging site, and store secrets only in the fields the app provides, not in code, custom fields or shared documents. Restrict who can open the settings through roles. Done means the connection test succeeds and the settings page shows the seller account as connected. If the test fails, check the refresh token and region settings before changing anything else.
Map marketplaces and warehouses
Map each Amazon marketplace to its ERPNext company, currency, price list and default warehouse, and map fulfillment locations (such as Amazon-fulfilled and seller-fulfilled stock) to separate warehouses so that stock on hand is not double counted. Finance and operations leads sign off these choices. Done means every marketplace and fulfillment location in use has a mapping and no entry is left on a default you did not choose. Test a sample mapping before you rely on it for live stock.
Confirm tax, currency and fee accounts
Set the tax templates, currency handling and accounts for marketplace fees and settlements before the first order sync, since these decide how Sales Orders and invoices are posted. Accounting staff confirm the accounts with the seller's tax adviser. Done means the accounts exist, the tax template matches the marketplace's tax treatment for that market, and the chart of accounts review has been signed off.
Run a test sync on staging
Run a manual sync of a small set of products and recent orders on the staging site. Use a sample product and one or two orders you can trace on the Amazon side, and confirm that items, customers, Sales Orders, taxes, currency and the target warehouse all match what Seller Central shows. Done means each sample record reconciles line by line, and any mismatch has a recorded cause and fix. Repeat the test after each mapping change.
Enable the scheduled sync
Once the test records reconcile, copy the validated settings to production, run one supervised sync, and then turn on the scheduled sync. Ensure background workers and the scheduler are running on that site, since the sync depends on them. Done means the first scheduled run completes, the job log shows no unhandled errors, and a new order placed in a test or live channel arrives in ERPNext with the expected tax, currency and warehouse.

How Amazon products, orders and fees map to ERPNext records

This table maps each Amazon data point to the ERPNext record it should land in, and flags where the connector may leave a field empty. Read the last column as the list of decisions your team must make before go-live, since the connector covers some mappings and leaves others to custom work. Fees, refunds and settlement payouts usually need explicit accounting design before the first live order syncs.

Record or field	Amazon source	ERPNext target	Gap to confirm
Product identity	Seller SKU and ASIN	Item code, with the ASIN kept as a reference	Confirm which identifier becomes the Item code and where the ASIN is stored
Marketplace and fulfillment channel	Marketplace ID and fulfillment channel (merchant or Amazon)	Warehouse and Price List per channel	Define one warehouse per fulfillment channel; confirm the connector sets both
Order header	Amazon order ID, purchase date, buyer details	Sales Order with customer and transaction date	Confirm the Amazon order ID is stored for duplicate checks
Order lines	Order item SKU, quantity and item price	Sales Order item rows	Confirm handling of bundles, promotions and gift wrap lines
Order tax and shipping	Item tax, shipping charges and tax on shipping	Sales Taxes and Charges template lines	Confirm how marketplace-collected tax is represented and which template applies per marketplace
Referral and fulfillment fees	Fee lines in settlement reports	Fee expense accounts through journal entries	Likely not posted by default; define accounts and the posting process
Refunds and returns	Refund events and returned units	Credit note, Sales Return and stock return	Define whether refunds reverse the Sales Invoice and who reconciles returned stock
Settlement payouts	Disbursement amounts paid to your bank account	Payment Entry against a marketplace clearing account	Confirm the clearing account design and how payouts are matched to orders

Accounting for Amazon fees and settlements in ERPNext

Amazon does not pay sellers order by order. It remits a settlement, usually on a fixed cycle, that nets together sales, refunds, marketplace fees, advertising charges and other adjustments. If that payout lands in the bank as a single deposit and ERPNext has no account for the fees and refunds inside it, reconciliation will never match the deposit to the orders it covers. For that reason, plan dedicated accounts before the first sync: a marketplace clearing account that holds the gross sales value until the payout arrives, a fee expense account for commissions and fulfilment charges, and a refunds or returns account for money returned to buyers. Keep these separate from your bank account so each settlement can be traced line by line.

The chart of accounts shapes every entry. Sales of the same product sold through different Amazon marketplaces may carry different tax treatment, and the connector's tax mapping has to reflect that, including whether marketplace facilitator rules mean Amazon collects and remits some taxes itself. Currency matters too: a settlement in one currency for a marketplace selling in another creates exchange differences that need an account of their own. Ask your accountant which tax accounts, currencies and exchange gain or loss accounts apply to each marketplace you sell in, and confirm how the settlement report's line types map to your accounts before go-live.

Before you rely on the connector for books, confirm with your accountant exactly which entries it creates and which you must post manually, such as settlement journal entries, reserve or holdback adjustments, or advertising charges that arrive outside the main report. Test with a settlement period from a sandbox or a closed period, then reconcile the total of the generated entries against the Amazon settlement report and your bank statement. Any difference that the connector does not explain is a gap to close with a documented journal entry, not a balance to absorb in the bank account.

Where sellers usually add custom work

A single Amazon marketplace account usually maps cleanly onto one set of Items, Sales Orders and Sales Invoices, provided the seller's ERPNext company, currency and tax setup match the marketplace. Once a seller runs several marketplace accounts or country stores, the questions multiply: which Amazon account a Sales Order belongs to, whether item codes stay shared across regions, and how stock is split when the same SKU sells in several places. The connector treats each account separately, so the gap is usually in cross-account reporting and item identity rather than in order capture.

Shared item identity: A SKU sold in two countries may need one Item with several marketplace identifiers, which requires a custom field or mapping table.
Cross-account reporting: Sales analysis by marketplace often needs a custom dimension or report built on the Sales Order fields.
Account routing: Orders from a second account may need a rule that sets the correct company, warehouse or price list.
Duplicate prevention: Teams selling the same listing through several accounts should confirm how the connector handles overlapping item records.

Before you commit to a design, ask the vendor or partner which fields the connector stores per account and whether a custom field can carry the marketplace identifier without changes to the app itself.

Securing the Amazon credentials and the ERPNext site

The Amazon sync holds seller credentials and touches order and customer records, so its security depends on a few controls working together. Each card below names one control the team can check on the running site, from how SP-API credentials are stored and rotated to how sync failures are logged and reviewed.

SP-API credential storage and rotation

Keep the SP-API client secret, refresh token and AWS access values out of plain database fields that many users can read. Store them in a restricted place, record who can view or edit the Amazon settings document, and set a dated rotation task for each credential. When a seller authorization is revoked or a developer leaves, rotate the refresh token and secrets the same day and confirm the old values no longer authenticate. Confirm the exact fields and rotation steps with the connector's current documentation.

Least-privilege sync user

Create a dedicated ERPNext user for the connector instead of running the sync under an administrator account. Give it only the roles needed to create or update Item, Sales Order, Customer and Payment Entry records, and remove desk access if the account only runs background jobs. Review the role matrix after each connector update, because new doctypes or fields may be added to the sync path. Illustrative check: an admin can see the sync user's activity log, and the sync user cannot change company or chart of accounts settings.

Restricted read access to orders and customers

Amazon orders contain buyer names, shipping addresses and contact details, which are personal data in most jurisdictions. Use role permissions and user permissions to limit which staff can open Sales Order and Customer records that came from Amazon, and consider field-level restrictions on address and contact fields. Export and print permissions deserve the same review as read access, since a report can copy the data out of the site. Ask your compliance lead which retention and access rules apply to marketplace buyer data before the first full sync.

TLS on the ERPNext site

The SP-API callback and any browser login to the ERPNext site must run over HTTPS with a valid certificate that the Amazon authorization flow can reach. Confirm the site's public hostname matches the redirect URL registered for the connector, and that plain HTTP redirects to HTTPS. Check that the proxy in front of the site sets the forwarding headers ERPNext expects, and that certificate renewal is automated or on a calendar. Verify with an external scan rather than trusting the configuration file.

Logging and alerting on sync failures

Failed order pulls, rejected item mappings and expired tokens are easy to miss when they only appear in a background job list. Enable error logging for the connector's scheduled jobs, keep the Error Log retained long enough to investigate settlement gaps, and route repeated failures to a named owner by email or chat. Record which Amazon marketplace and seller account each failure belongs to, so a multi-region seller can tell which sync stopped. Ask the connector maintainers which events are logged by default before you rely on them.

How to test the sync before it touches live orders

Run the Amazon connector against a staging ERPNext site and a test or limited set of Seller Central listings before any live order reaches a Sales Order. The first control is a written test matrix: sample orders for each marketplace you sell in, each fulfillment type you use (merchant-fulfilled and Amazon-fulfilled orders behave differently in your books), and the edge cases your team already handles by hand, such as partial refunds, cancellations and orders with a missing SKU mapping. For each case, record the expected Item, Customer, Sales Order, tax treatment and fee postings before you run it, so the result is checked against a decision rather than against whatever the connector produced. Confirm with your Amazon account team and the connector documentation which SP-API credentials and seller account types are needed for a sandbox, because not every production account has a usable test path.

Reconcile in both directions once the test orders have synced. Compare order counts and order totals per marketplace and per day between Seller Central reports and ERPNext, then compare the fee and settlement amounts against the Amazon settlement report for the same period. Any difference is a mapping or timing issue to resolve before go-live, not a number to adjust by hand. Write down the rollback procedure at the same time: which scheduled sync job to disable, how to cancel or flag Sales Orders created in the test window, who approves the reversal of stock and accounting entries, and how you confirm the books are clean afterward. Historical loads need separate handling. The ERPNext Data Import tool suits controlled loads of masters such as items and customers, but its Data Import documentation advises importing only a few thousand records at a time, so a multi-year order history must be split into batches, each reconciled before the next starts.

Common Amazon sync failures and how to fix them

This table lists the sync failures sellers most often hit when pulling Amazon products and orders into ERPNext, with the likely cause and the first check for each. Read it as a triage sheet: find the symptom, confirm the first check, then move to the fix that matches what you find. Causes are common patterns to verify in your own site, not a diagnosis of any specific installation.

Symptom	Likely cause	First check
Amazon authorization errors after credentials change	The SP-API refresh token, client secret or AWS role was rotated in Seller Central or AWS, but the Amazon Settings record still holds the old values	Re-enter the credentials in Amazon Settings, save, then confirm the connection test passes before the next scheduled pull
Items fail to match Amazon listings	The SKU in ERPNext does not match the seller SKU on the Amazon listing, often because of case, prefixes, trailing spaces or a renamed item code	Compare the Item code in ERPNext with the seller SKU in the Amazon listing report for the same ASIN and check for whitespace or case differences
Duplicate Sales Orders after a retry	A failed or timed-out order pull was run again without checking whether the Amazon order ID already exists on a Sales Order, so the same order was created twice	Search Sales Orders by the Amazon order ID field and check whether two records share it before deleting or cancelling either one
Imported orders have missing or wrong tax	Tax templates were not mapped to the Amazon channel, or the marketplace collects tax under a different rule than the template assumes	Open one imported Sales Order and check the taxes table, the tax template and the tax rule that applied at order date
Imported orders have missing or wrong currency	The marketplace currency was not mapped to the customer or price list, or the order currency differs from the company default currency	Check the currency field on the Sales Order and the price list currency, then confirm the exchange rate used on the order date
Fees do not reconcile to Amazon payouts	Referral, fulfillment and other fee lines were not posted to the expense accounts configured for settlements, or the settlement period was pulled without its adjustments and refunds	Compare one settlement report line by line with the Journal Entry or Payment Entry ERPNext created, starting with the settlement ID and posting dates
Scheduled sync jobs stop running	Background workers or the scheduler are not running, so queued sync jobs never execute even though the Amazon credentials are valid	Check that the scheduler is enabled and that background worker processes are running, then review the error log for the sync job

Questions buyers ask before connecting Amazon to ERPNext

What does ERPNext itself cost to run?

Self-hosting ERPNext is free under its open-source license, so the software itself carries no license fee. The ERPNext pricing page lists Frappe Cloud shared site hosting from 5 US dollars per month and Frappe Cloud servers from 20 US dollars per month for shared instances and 125 US dollars per month for dedicated servers. Your real recurring costs are the infrastructure you choose, staff time to administer it, and any support plan you buy. Ask whether a quote separates one-time build work from recurring hosting, monitoring and maintenance.

How long does an Amazon connection take to set up?

Duration depends mostly on how much of your catalogue and order flow needs custom handling. A basic connection to the ecommerce_integrations app covers credentials, item mapping, order import and settlement accounting, while extra work grows with the number of marketplaces, SKU complexity, bundles, returns handling and the chart of accounts you need for fees. Testing against your own historical orders usually takes longer than the initial configuration. Ask for a written scope and timeline before work starts, since most engagements are fixed-scope.

What does the seller need to provide before the work starts?

You need an active Amazon Seller Central account with permission to register a developer application and authorize access for your ERPNext site. Gather the marketplaces you sell in, a sample of listings with their SKUs and variants, your current fee and settlement reports, and the accounts your accountant wants fees posted to. You also need a clean ERPNext site with a known version, a hosting decision, and a named person who can approve item and tax mappings. Confirm the exact credential steps against the current Amazon developer documentation for your region.

Can our internal team connect Amazon to ERPNext without a partner?

Yes, a team with ERPNext administration experience can install the app and follow its configuration screens, especially for a single marketplace with simple products. The harder parts are fee and settlement accounting, reconciling refunds and reimbursements, handling multi-currency marketplaces, and deciding how returns affect stock. Those gaps are where sellers usually add custom scripts or apps. Assess whether your team has someone who can read Frappe documentation, test in a staging site, and maintain the work through ERPNext upgrades.

Which gaps in the connector do sellers usually fill with custom work?

Sellers most often build custom logic for Amazon fees that do not map cleanly to standard accounts, settlement payouts that need grouping by period, multi-warehouse inventory rules, bundled or kitted products, and returns that must adjust stock and tax. They also add reports that match how their finance team closes the books. Treat each gap as a separate requirement with its own test case. Ask a potential partner to list which of these gaps are covered by the stock connector and which would need a custom app or server script.

What should a quote for this work include?

A useful quote lists the ERPNext version and target hosting, the marketplaces and accounts in scope, the item and order mapping rules, the fee and settlement accounting design, and the test plan with sample orders. It should name the deliverables, such as configured records, documentation and handover, and state what is excluded, including ongoing support and future upgrades. Ask which costs are one-time and which recur, and whether custom code is delivered with source and documentation. DeployOpen provides fixed-scope quotes based on this written scope.

Do custom scripts for Amazon fees need special enablement?

Yes, if you use Server Scripts. According to the Frappe Framework documentation, starting from version 15 Server Scripts are disabled by default and must be enabled with the server_script_enabled setting. Frappe Cloud public shared benches do not allow them, so a custom script approach needs self-hosting or a dedicated bench. Confirm this before choosing a design, because a custom app may be the better route for logic that must survive upgrades and be version controlled.

How DeployOpen scopes and delivers the Amazon integration

DeployOpen plans, implements, customizes, integrates, hardens, backs up and documents self-hosted open-source platforms inside your own infrastructure, and ERPNext with the Amazon connector follows the same approach. We agree the scope in writing before work starts, so your accounting, stock and marketplace owners know exactly what will be built, tested and handed over.

How we scope

Inventory the Amazon marketplaces, seller accounts and fulfillment models you actually sell through before choosing mappings.
Document which items, orders, fees and settlements sync, and which stay manual, in the written scope.
Confirm your ERPNext version, hosting model and whether Server Scripts will be enabled for custom gap work.

How we build

Configure SP-API credentials with least-privilege access in a staging site, then test them against a sandbox or limited sample first.
Map Amazon SKUs, customers, tax and fee accounts to your chart of accounts, and test order-to-invoice flows with reconciliation checks.
Build the custom work your gaps need as a versioned custom app, with tests covering fee postings and settlement entries.

How we hand over

Deliver a runbook covering credential rotation, mapping tables, sync schedules and the steps for re-importing failed orders.
Walk your finance and operations staff through how settlements post to ledgers and how to reconcile them each period.
Hand over source code, configuration exports and documentation in your own repositories, with the deployment steps written down.

How we support

Plan upgrades of ERPNext and the ecommerce_integrations app together, reviewing release notes before each version change.
Offer ongoing support and continuous testing as a retainer, sized to the marketplace changes and volume you expect.
Review credential expiry, failed sync logs and fee changes with your team on an agreed schedule under the support arrangement.