ERPNext marketplace integration involves more than receiving an order through an API. Stores selling across Shopee, Lazada, TikTok Shop and their own websites need consistent product identities, dependable stock availability and a plan for incomplete, delayed or duplicated events. Good integration design keeps the operational source of truth clear even when individual platforms report different order and payment statuses.
Assign ownership of each business record
A marketplace owns the customer order event and the statuses it confirms. An OMS may consolidate orders for packing, shipment and exceptions. ERPNext can provide the business document and financial data plane where required. The architecture should specify which system owns item masters, warehouse movements, customer references and payment allocations.
Without these boundaries, two systems may both attempt to change stock or create invoices. Integrations should use validated business APIs and avoid directly writing to core tables outside documented rules.
Map SKUs at the variant level
Two storefronts may display different names for the same physical product. The reliable key is the chosen internal SKU, mapped to each marketplace listing and variant. Treat missing mappings as visible exceptions rather than deleting or hiding the source order.
A bulk mapping process should support preview and verification before automatically applying ambiguous matches. Preserve listing identifiers so historic orders remain traceable even after product names or external listings change.
Understand stock available for a channel
Physical inventory, reserved stock and storefront availability are different quantities. A store may use several warehouses for fulfilment or restrict certain stock to a specific channel. Define the warehouse mapping and allocation policy before enabling inventory updates.
Do not automatically push zero stock to a storefront because an API call failed or the mapping is temporarily unavailable. Error handling, deliberate zero-stock rules and exception notifications protect sales from accidental outages.
Use webhooks and prevent duplicate processing
Webhooks reduce the need for constant polling, but delivery may be repeated, delayed or out of order. Store marketplace event identifiers and process incoming changes idempotently. Where the platform permits, use a bounded recovery scan to close gaps without repeatedly replaying the entire order history.
Queue processing should be observable and resumable. Record why an event failed, which data was accepted and whether retrying is safe. A successful API response is not enough if the downstream ERP document was not committed.
Separate order, payment and fulfilment state
A paid order is not automatically shipped. A shipped order is not proof that a corresponding invoice or payment was posted correctly. Model marketplace payment confirmation, fulfilment and accounting status as related but distinct facts.
Returns, cancellations, refunds and partial payments introduce further transitions. Define a transaction reference to prevent duplicate Payment Entries and a document policy for when Sales Orders, Sales Invoices or Credit Notes are created.
Useful operational dashboards
Track unmapped SKUs, failed order imports, orders waiting for stock, reservations, shipping exceptions, payment discrepancies and API failures. Exception queues should expose the affected store, transaction and safe recovery action so staff are not forced to search server logs.
Measure integration lag and compare counts between the marketplaces, OMS and ERPNext. Differences should be explainable by status and reporting window rather than hidden by a single overall order total.
Roll out marketplace integration in stages
Start with one store and representative item variants. Test order intake, duplicate events, warehouse reservations, partial shipment, cancellation, refund and stock publication. Establish monitoring and rollback before connecting additional channels.
For platform design, see system integration services, PackKUB order management and ERPNext Inventory. Confirm each platform's current API permissions and limits before committing to a specific connector scope.
