EKM Web Shop Integration Specification

A concise overview of the integration's functionality, technical requirements, and configuration options.

Core Integration Tasks (Automated Sync)

• Product Export: New products and amendments (descriptions, prices, special offers, VAT Rate ID).
• Stock Export: Synchronisation of product stock levels.
• Order Import: Imports cash sale (guest checkout) orders. Only orders with a "Paid" status are imported; "Incomplete" or "Cancelled" orders are ignored.
• Customer Import: Imports new customer accounts from EKM and maps them to Merchanter.

Authentication & Authorisation

• Protocol: OAuth 2.0.
• Requirements: Client ID and Client Secret (obtained from the EKM shop backend).
• Authorisation Flow: One-time "Request Authorisation" button > EKM login > User grants permission > Merchanter stores access token.
• Token Management: Access token expires hourly and is automatically refreshed by the link.

Technical Setup Requirements (DeepLink)

• Required Item: A DeepLink.
• Name: Must be exactly CallbackURI_EKM.
• Merchanter Target Microflow: Must call CBK_AcceptAuthResponse.
• Purpose: Provides EKM with a valid redirect URI to return the authorisation code.

Scheduling Automated Tasks (ScheduledJobs)

One instance of a scheduled job runs for all configured EKM links in Merchanter.

• Product Export: QUE_ExportProducts
• Stock Export: QUE_ExportStocks
• Order Import: QUE_ImportSalesOrders
• Customer Import: QUE_ImportCustomerAccounts

Configuration Options

Product Name Source

Determines what updates the web shop product's name/title

• Description - uses the Merchanter product's main description
• Short Description - uses the Merchanter product's short description

Product Description Source

Determines what updates the web shop product's full description

• Description (Main description)
• Description + Additional Description
• Do Not Set

Product Short Description Source

• Do Not Set (Prevents updates to the EKM short description)

Payment Recording

Orders with a status of "Incomplete" (i.e. those with an abandoned cart or other freak failure) will now be ignored

• Not all payments are guaranteed by EKM and they have a traffic light system for the likelihood of fraud per transaction. It would be good that orders are not paid off automatically when imported into UT400. That gives us the option to investigate the transaction before processing
• Payment status is now checked for value "Paid" to deem that the order was successfully paid, If the order was cancelled on the webshop before import, the order will be ignored

Catalogue Products as Live

• Configurable option to allow Merchanter "Catalogue" status products to be sent to EKM as "Live".

Data Handling & Logic

Specialised Stock:

• Length-Controlled Stock (e.g., Timber): Length is appended to the SKU as a suffix with an implied decimal, separated by a hyphen (e.g., SKU-2400).
• Total Length Stock (e.g., Cable Drums): Treated as units, stock level rounded down to nearest metre, and "Add to Cart" flag set to false in EKM.

Order Line Attributes:

• Nett unit price (ex VAT) is set from item_price (unrounded).
• Total line value (inc VAT) = (qty x item_price rounded) + (qty x item_tax rounded).
• item_discount is not used.

Customer Import:

This includes both automapping and the ability to manually map any not automatically mapped. EKM customers should be mapped to Merchanter customer accounts.

• New EKM customers are imported and automatically mapped where possible.
  • we could extend the customer import to handle customer updates as well but this has not been developed yet
• Unmapped customers can be mapped manually.
• Imported customers have a default "Cash Only" account type with standard payment terms of zero days. 
• (Note: Customer updates are not currently synced.)

Minimum Web Stock Logic (EKM, WooCommerce, Shopify):

• If a product's Minimum Web Stock level is set above zero, the stock export will use this value as the quantity sent to the webshop whenever the actual free stock falls below that minimum threshold. This ensures the online shop never displays a stock level lower than the configured minimum.
• Triggering an Update: A stock update is automatically triggered if the Minimum Web Stock level is changed in Merchanter.
• Post-Order Adjustment: The stock export routine also checks for products that have appeared on a web order since the last export. If such a product has a Minimum Web Stock level set, its stock is re-evaluated and, if necessary, updated on the next export cycle.

Recent Fixes & Updates

• Order Query URL: Fixed to be URL-safe with single quotes around the timestamp.
• VAT: Product export now correctly updates the VAT rate ID on the EKM product.
• Order Filtering: The import now ignores orders with "Incomplete" or "Cancelled" statuses.
• Payment Status: Order import checks for a "Paid" status before processing payments.

Limitations and future developments. 

The following items are not supported by the current version of the EKM integration. These are either explicitly deferred or have not been developed.

Product Variants

• Support for product variants (e.g., different colours, sizes) is not included in the current scope.
  • This has been deferred to a potential future development ("phase 2").

Customer Account Updates

• The customer import routine (QUE_ImportCustomerAccounts) imports new customers only.
• Updates to existing customer records (e.g., address or contact detail changes) are not synchronised from EKM to Merchanter.

Item Discounts

• The item_discount field from EKM order lines is not used and is always treated as zero. The integration does not import line-level discounts.

Product Attributes (for Length)

• As EKM does not have a dedicated length attribute, length-controlled stock is handled via a suffix appended to the SKU field. This is a workaround rather than a native attribute mapping.

"Add to Cart" for Total Length Products

• For products where stock is controlled by total length (e.g., cable drums), the "Add to Cart" flag is forcibly set to false in EKM. This prevents online purchase but is a manual override rather than a native EKM setting.

Order Fraud Flags

• While EKM uses a traffic light system for fraud likelihood, Merchanter does not interpret or display these flags. The system can only be configured to not auto-record payments, allowing for manual review elsewhere.

Abandoned or Incomplete Orders

• These are deliberately ignored by the import process and are not available in Merchanter in any form.