Order Import

Order import is the most critical inbound integration. It pulls new customer orders from the external platform into VARIO ERP, where they can be processed, fulfilled, and invoiced.

Overview

The order import flow consists of three phases:

1. Fetch — Retrieve new orders from the platform's API

2. Transform — Map platform order data to the ERP's expected format

3. Import — Push the transformed data into the ERP using the MultiPart Import API

Triggering Order Imports

There are three common approaches for triggering imports:

Polling

Your app periodically checks the platform for new orders. This is the simplest approach and works with any platform.

// Pseudocode — fetch orders since last import
async function pollForOrders(salesChannelId)
{
  const lastTimestamp = await getLastImportTimestamp(salesChannelId);
  const orders = await platformApi.getOrders({
    createdAfter: lastTimestamp,
    status: 'open'
  });

  if (orders.length > 0)
  {
    await processOrderImport(orders, salesChannelId);
    await setLastImportTimestamp(salesChannelId, new Date().toISOString());
  }
}

Platform Webhooks

If the external platform supports webhooks (most modern platforms do), you can receive real-time notifications when new orders are placed. Your app registers a webhook on the platform side (not to be confused with VARIO ERP webhooks).

Manual Trigger

Provide a button in your app's UI that lets users manually trigger an order import. This is useful for testing and for cases where automatic imports are disabled.

Fetching Orders

When fetching orders from the platform, consider:

• Pagination — Platforms typically paginate results. Fetch all pages.

• Filtering — Only fetch orders in the relevant status (e.g., "paid" or "processing"). Platform-specific statuses vary.

• Timestamps — Use the last successful import timestamp to fetch only new orders.

• Rate limits — Respect the platform's API rate limits. See Performance.

Transforming Orders

The transform step maps platform-specific order data to VARIO ERP's import format. This is where most of the integration-specific logic lives.

Key fields to map:

Platform Field	ERP Field	Notes
Order ID	External reference	Store as custom field for later lookup
Customer email/name	Customer reference	Match or create customer
Line items	Order positions	Map SKU to article number
Shipping address	Delivery address	Map address fields
Payment method	Payment method ID	Use mapping configuration
Shipping method	Shipping method ID	Use mapping configuration
Tax amounts	Tax data	Map tax rates and zones
Discounts	Position adjustments	Handle percentage and fixed discounts

Handling Customer Matching

When importing an order, the ERP needs to associate it with a customer record. Common strategies:

• Match by email — Look up the customer by email address. If found, use the existing customer.

• Match by external ID — If you store the platform customer ID in an EAV field, match on that.

• Create on import — Let the import preset create a new customer if no match is found.

Handling Variants

Platform line items often reference a specific variant (size, color). Map the variant's SKU to the corresponding article number or variant ID in the ERP.

Handling Currency and Prices

• Import prices in the currency used on the platform

• The ERP handles currency conversion if needed

• Include tax information (gross/net, tax rate) as required by the import preset

Importing to ERP

Use the MultiPart Import API to push the transformed orders into the ERP:

const ErpApi = require('@vario-software/vario-app-framework-backend/api/ErpApi');

async function importOrders(transformedOrders, importPresetId)
{
  const result = await ErpApi.fetch('/cmn/data-import/runs/multi-part', {
    method: 'POST',
    useInternalApi: true,
    body: JSON.stringify({
      presetId: importPresetId,
      data: transformedOrders
    })
  });

  return result.data;
}

Import Preset Setup

Create the import preset during installation:

await migrator.setMigration('create-order-import-preset', async (methods) =>
{
  await methods.createMultipartImportPreset({
    name: 'My Shop Order Import',
    entity: 'account-order'
    // Additional preset configuration...
  });
});

The preset defines how incoming data fields map to ERP entity fields. See MultiPart Import for details.

Tracking Import State

Store the last successful import timestamp to enable incremental imports:

// After successful import
await setLastImportTimestamp(salesChannelId, latestOrderTimestamp);

// Before next import
const since = await getLastImportTimestamp(salesChannelId);

Use EAV custom fields or your own storage mechanism to persist this value per sales channel.

Handling Duplicates

To prevent importing the same order twice:

• Check external order ID — Before importing, query the ERP for orders with the same external reference

• Use timestamps carefully — Ensure your timestamp window doesn't miss orders but also doesn't overlap

• Idempotent imports — If the import preset supports it, let the ERP detect and skip duplicates

Error Handling

Common import errors and how to handle them:

Error	Cause	Resolution
Customer not found	No matching customer in ERP	Create customer or check mapping
Article not found	SKU doesn't match an ERP article	Verify SKU mapping
Validation error	Required fields missing	Check transform logic
Rate limit	Too many import requests	Reduce batch size, add delays

For comprehensive error handling strategies, see Error Handling.