Order Status Sync

Order status sync pushes fulfillment updates from VARIO ERP to the external platform. When an order is shipped, partially fulfilled, or cancelled in the ERP, the platform needs to be updated so the customer sees the correct status and tracking information.

Trigger

Order status sync is triggered when document statuses change in the ERP. This happens when:

• A delivery note (shipping document) is created from an order

• A tracking number is assigned

• An order is marked as shipped

• An order is cancelled or partially cancelled

The exact webhook event depends on the document type and status transition.

app.apiServer.post('/webhooks/order-status-change', async (req, res) =>
{
  res.status(200).send({ success: true });

  const { entityId } = req.body; // document ID
  await addToQueue('order-status.sync', entityId);
});

Fetching Fulfillment Data

When processing an order status update, fetch the relevant data from the ERP:

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

async function fetchOrderStatus(documentId)
{
  const result = await ErpApi.fetch(`/erp/documents/${documentId}`, {
    useInternalApi: true
  });

  return result.data;
}

Key data to extract:

Field	Purpose
Order reference / External order ID	Identify the order on the platform
Status	Current fulfillment status
Tracking number	Shipment tracking code
Carrier	Shipping carrier (DHL, UPS, etc.)
Shipped items	Which line items were included in this shipment
Shipped date	When the shipment was dispatched

Mapping Order Status

ERP document statuses don't map directly to platform order statuses. Create a mapping between them:

ERP Status	Typical Platform Status
Order confirmed	Processing
Partially shipped	Partially fulfilled
Fully shipped	Fulfilled / Shipped
Cancelled	Cancelled
Returned	Refunded

The exact mapping depends on the platform. Store it in your mapping configuration.

Pushing to the Platform

Full Fulfillment

When all items in an order have been shipped:

async function syncFullFulfillment(documentData, salesChannelId)
{
  const externalOrderId = getExternalOrderId(documentData);

  if (!externalOrderId)
  {
    return; // Order was not imported from this platform
  }

  await platformApi.fulfillOrder(externalOrderId, {
    status: 'shipped',
    trackingNumber: documentData.trackingNumber,
    carrier: documentData.carrier,
    shippedAt: documentData.shippedDate
  });
}

Partial Fulfillment

When only some items are shipped (split shipments):

async function syncPartialFulfillment(documentData, salesChannelId)
{
  const externalOrderId = getExternalOrderId(documentData);

  await platformApi.createFulfillment(externalOrderId, {
    lineItems: documentData.shippedItems.map(item => ({
      sku: item.articleNumber,
      quantity: item.shippedQuantity
    })),
    trackingNumber: documentData.trackingNumber,
    carrier: documentData.carrier
  });
}

Cancellation

When an order is cancelled in the ERP:

async function syncCancellation(documentData, salesChannelId)
{
  const externalOrderId = getExternalOrderId(documentData);

  await platformApi.cancelOrder(externalOrderId, {
    reason: documentData.cancellationReason || 'Cancelled by seller'
  });
}

Finding the External Order ID

To update an order on the platform, you need the platform's order ID. If you stored it during order import (as an EAV custom field or in the import data), retrieve it:

async function getExternalOrderId(documentData)
{
  // Check EAV custom fields
  const externalId = documentData.custom?.myShop?.externalOrderId;

  if (externalId)
  {
    return externalId;
  }

  // Alternative: Query by order reference
  // ... your lookup logic
  return null;
}

Marketplace-Specific Considerations

Marketplaces often have strict requirements for order status updates:

• Acknowledgment — Some marketplaces require you to acknowledge orders before you can fulfill them

• Shipping confirmation deadline — Marketplaces may penalize sellers who don't confirm shipping within a certain timeframe

• Carrier validation — Marketplaces may only accept specific carrier names or codes

• Tracking URL format — Some marketplaces require full tracking URLs, not just tracking numbers

Handle these platform-specific requirements in your transform layer.