Integrate Microsoft Dynamics 365 Business Central with Medusa

How a Business Central integration with Medusa works

Medusa has no first-party connector for Microsoft Dynamics 365 Business Central. You build the integration as a custom Medusa module that calls the Business Central API v2.0, a REST API on OData v4. Workflows, subscribers, scheduled jobs and API routes then use that module, following Medusa's ERP recipe.

Business Central pushes changes through webhooks:

• You register with Copy to clipboardPOST /api/v2.0/subscriptions, and your endpoint must echo the Copy to clipboardvalidationToken with a Copy to clipboard200 response.
• Subscriptions expire after three days unless renewed with a Copy to clipboardPATCH.
• A notification carries the changed record's URL and a change type, not the record itself, so you Copy to clipboardGET the record afterwards.
• Supported entities include Copy to clipboarditems, Copy to clipboardcustomers, Copy to clipboardsalesOrders and Copy to clipboardsalesInvoices. Item ledger entries, which hold stock movements, are not on the list.
• If more than 1,000 records change within 30 seconds, you get one Copy to clipboardcollection notification with a filter instead of one per record.

Mapping Business Central data to Medusa

Each Business Central entity maps to a Medusa commerce module. Statuses describe the Medusa side.

The standard API v2.0 has no price list or customer price group resource; items expose a single Copy to clipboardunitPrice. To sync customer-specific prices, publish a custom API page in AL. Custom API pages can also send webhooks if they meet Business Central's webhook requirements.

Real-time or scheduled sync for each Business Central flow

Pick the trigger per flow, not per integration:

• Orders: real time. An Copy to clipboardorder.placed subscriber runs a workflow that creates the BC sales order.
• Order status: real time. A Copy to clipboardsalesOrders webhook calls a Medusa API route that fetches the order and updates Medusa. A scheduled job renews the subscription before its three days run out.
• Stock: scheduled, because stock movements don't fire webhooks. For exact stock, check BC in the Copy to clipboardvalidate hook of Copy to clipboardaddToCartWorkflow.
• Prices: scheduled into Medusa price lists, or fetched per cart with a custom item price workflow.

Business Central online allows 6,000 OData requests per user in a 5-minute window, 5 concurrent requests, and 100 operations per Copy to clipboard$batch. Above the limits it returns Copy to clipboard429. Set Copy to clipboardmaxRetries and Copy to clipboardretryInterval on steps that call BC; a Copy to clipboardretryInterval makes the workflow long-running.

Code skeleton: push a Medusa order to Business Central with rollback

This skeleton assumes a custom module registered as Copy to clipboardbc whose service wraps Copy to clipboardsalesOrders create and delete calls. The compensation function deletes the BC sales order if the metadata update fails.

1234567891011121314151617181920
// src/workflows/sync-order-to-bc.ts
import { createStep, createWorkflow, StepResponse, WorkflowResponse } from "@medusajs/framework/workflows-sdk"
import { updateOrderWorkflow, useQueryGraphStep } from "@medusajs/medusa/core-flows"
import { OrderDTO } from "@medusajs/framework/types"

const createBcSalesOrderStep = createStep(
  { name: "create-bc-sales-order", maxRetries: 3 },
  async ({ order }: { order: OrderDTO }, { container }) => {
    const bcOrderId = await container.resolve("bc").createSalesOrder(order)
    return new StepResponse(bcOrderId, bcOrderId)
  },
  async (bcOrderId, { container }) => {
    if (!bcOrderId) return
    await container.resolve("bc").deleteSalesOrder(bcOrderId)
  }
)

export const syncOrderToBcWorkflow = createWorkflow(
  "sync-order-to-bc",
  ({ order_id }: { order_id: string }) => {

123456789
// src/subscribers/order-placed-bc.ts
import type { SubscriberArgs, SubscriberConfig } from "@medusajs/framework"
import { syncOrderToBcWorkflow } from "../workflows/sync-order-to-bc"

export default async function orderPlacedBcHandler({ event: { data }, container }: SubscriberArgs<{ id: string }>) {
  await syncOrderToBcWorkflow(container).run({ input: { order_id: data.id } })
}

export const config: SubscriberConfig = { event: "order.placed" }

Medusa compared with the Shopify Connector for Business Central

When Medusa is not the right choice for Business Central

• You run Business Central online and Shopify, and the connector's syncs cover your order, stock and price flows. Use the connector.
• You have no developer capacity. A Medusa integration is code you own.
• You need a vendor-supported connector. Medusa has none for Business Central today.