Microsoft Dynamics 365 F&O and UPS integration

What moves between them

The main flow runs from Microsoft Dynamics 365 F&O out to UPS. When an F&O order or shipment is ready, ml-connector reads the ship-to address and parcel detail, calls UPS Address Validation and Rating, then creates the UPS shipment. The returned 1Z tracking number, service level, label, and freight charge are written back onto the F&O record. After that, delivery events flow the other direction: UPS Track Alert pushes scan events as packages move, and Quantum View can be polled as a backstop, so each F&O order reflects its current status through delivery. Cadence is event-driven on shipment creation and on each UPS scan, with scheduled polling as a fallback.

How ml-connector handles it

ml-connector stores both credential sets encrypted and runs two separate OAuth client-credentials exchanges: Entra ID for the tenant-specific F&O host, and UPS for the carrier, passing the 6-digit account number as x-merchant-id so negotiated rates apply. It caches the four-hour UPS token and refreshes it shortly before expiry to stay well under the roughly 250 tokens per day, and it refreshes the hourly F&O token when a call returns 401. F&O addresses are normalized through UPS Address Validation before rating, because residential versus commercial classification changes the price; the F&O service shipping method maps to a numeric UPS service code such as 03 for Ground. Shipment creation is not idempotent on the UPS side, so every create runs under a BullMQ jobId keyed to the F&O order to prevent duplicate labels, and the tracking number is written back to F&O only after a successful response. Inbound Track Alert webhooks carry no HMAC signature, so the connector validates the secret credential header it set at subscription time, and because those subscriptions expire after 14 days it renews them for shipments still in transit. UPS 429 responses arrive without a Retry-After header, so ml-connector applies exponential backoff with jitter. Every record carries a full audit trail and can be replayed if a downstream call fails.

A real-world example

A mid-sized industrial parts distributor, around 150 staff across two warehouses, runs Microsoft Dynamics 365 F&O for sales orders, inventory, and finance, and ships parcels with UPS. Before the integration, warehouse staff picked an order in F&O, then retyped the customer address into the UPS shipping portal, copied the tracking number back into F&O by hand, and answered status calls by looking each package up on the UPS website. Wrong residential or commercial flags led to surprise surcharges that nobody caught until the monthly UPS bill. With the two systems connected, a confirmed F&O order is address-validated, rated, and labeled through UPS in one step, the 1Z tracking number and freight charge post straight back to the order, and Track Alert scan events update delivery status automatically. Staff stop double-keying, and the rate on the label matches what was quoted.

What you can do

• •Turn a confirmed Microsoft Dynamics 365 F&O order into a rated, labeled UPS shipment without re-keying the address.
• •Write the UPS 1Z tracking number, service level, label, and freight charge back onto the F&O record.
• •Validate and classify each ship-to address with UPS before rating so residential surcharges do not surprise you.
• •Feed UPS Track Alert and Quantum View scan events back into F&O so every order shows its current delivery status.
• •Bridge Entra ID OAuth on the F&O side and UPS OAuth client credentials on the carrier side, with cached tokens, retries, and a full audit trail.

Questions

Which direction does data move between Microsoft Dynamics 365 F&O and UPS?

Order and address data moves from Microsoft Dynamics 365 F&O out to UPS to rate and create the shipment. The UPS tracking number, service level, label, and freight charge are written back onto the F&O record. After that, UPS scan events flow back into F&O through Track Alert and Quantum View so the order shows its current delivery status.

Can ml-connector reconcile UPS invoices against Dynamics 365 F&O?

Not from a billing API, because UPS does not publish one. ml-connector instead captures the freight charge returned on the Rating and Shipping responses and writes it onto the F&O order, which gives you the carrier's quoted cost at label time. Full invoice-level reconciliation still requires the UPS Billing Center, since no download endpoint exists.

How are UPS tokens and tracking subscriptions kept healthy?

UPS tokens last about four hours and an app is capped near 250 token requests per day, so ml-connector caches the token and refreshes it just before expiry rather than per call. Track Alert webhook subscriptions expire after 14 days, so the connector renews them for packages still in transit. Because UPS 429 responses omit a Retry-After header, it backs off exponentially with jitter.