Microsoft Dynamics 365 Business Central and UPS integration

What moves between them

The primary flow runs from Microsoft Dynamics 365 Business Central into UPS. ml-connector reads released sales orders, their ship-to addresses, and package details, then calls the UPS Shipping API to create a label, stamping the Business Central order or invoice number into the package reference numbers and passing the 6-digit account number for negotiated rates. The returned 1Z tracking number is written back onto the sales order. The return flow runs from UPS into Business Central: tracking scans and delivery events, pulled from the Tracking API on a schedule or pushed by a Track Alert subscription, update the order so fulfillment status reflects the live package state. UPS holds no financial records and publishes no invoice API, so ml-connector never posts ledger or billing data into the carrier.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the ERP side it requests a Microsoft Entra client-credentials token scoped to the Business Central API and targets the customer's environment name in the base URL. On the carrier side it requests a UPS bearer token using a Basic header of base64(client_id:client_secret) and caches it for its full four-hour life, since UPS allows only about 250 token requests per day and a token per call would exhaust the quota. Shipment methods in Business Central are mapped to UPS service codes first, for example Ground to 03 and Next Day Air to 01, so each order resolves to a valid service, and ship-to addresses can be run through the UPS Address Validation API to settle residential versus commercial classification before rating. Because Business Central does not offer webhooks for purchaseOrders and its other notifications carry no payload, ml-connector polls sales orders with a lastModifiedDateTime filter and follows the odata.nextLink for paging. UPS shipment creation is not idempotent and has no idempotency-key header, so a stable BullMQ job ID and the stored 1Z number prevent a re-read order from creating a duplicate label. Delivery events arrive either from a Tracking API poll or, where the paid Track Alert subscription is active, from a webhook; UPS does not sign those posts, so ml-connector validates the credential header against the stored secret and renews each subscription before its 14-day expiry. Throttling on either side returns HTTP 429, so failed calls back off and retry, every record carries a full audit trail, and a failed write can be replayed.

A real-world example

A mid-sized industrial supplies distributor with about 150 staff runs Microsoft Dynamics 365 Business Central for sales, inventory, and finance, and ships parcels through UPS. Before the integration, a warehouse clerk re-typed each order's ship-to address into the UPS web tool, then pasted 1Z tracking numbers back into Business Central by hand, which slowed dispatch and left customer service guessing at delivery status. With the two connected, a released sales order produces a UPS label automatically with the order number on it, the tracking number appears on the order, and delivery scans flow back so the support team sees real status. Dispatch is faster, the address typos are gone, and tracking is no longer a manual lookup.

What you can do

• •Turn released Microsoft Dynamics 365 Business Central sales orders into UPS shipping labels without re-keying the ship-to address.
• •Stamp the Business Central order or invoice number into the UPS package reference numbers so every label and scan ties back to the source order.
• •Write the UPS 1Z tracking number back onto the originating Business Central sales order.
• •Push UPS tracking scans and delivery events into Business Central so fulfillment status reflects the live package state.
• •Bridge Microsoft Entra client-credentials auth and the UPS bearer token, mapping Business Central shipment methods to UPS service codes.

Questions

Which direction does data move between Microsoft Dynamics 365 Business Central and UPS?

The primary flow is Business Central into UPS: sales orders and ship-to addresses are read and turned into UPS shipments, and the 1Z tracking number is written back onto the order. The return flow is UPS into Business Central, where tracking scans and delivery events update fulfillment status. UPS has no vendor, invoice, or GL objects and no billing API, so ml-connector never writes financial data into the carrier.

How does UPS tie a shipment back to the right Business Central order?

UPS is a carrier API with no ERP records, so the link is carried in the package reference numbers on each shipment. ml-connector stamps the Business Central order or invoice number into a reference field at label creation, then matches scans back using the UPS Tracking API, which can look up packages by that same reference number as well as by the 1Z tracking number.

How are tracking updates delivered, by polling or webhook?

Both are supported. By default ml-connector polls the UPS Tracking API on a schedule, since basic tracking is pull-based. Where the customer has the paid Track Alert subscription, UPS pushes events to a webhook; UPS does not sign those posts with an HMAC, so ml-connector authenticates each one by checking the credential header against the secret it set at subscription time and renews the subscription before its 14-day expiry.