Acumatica and UPS integration

What moves between them

The main flow runs from Acumatica to UPS. When an Acumatica shipment is released, ml-connector reads its recipient address, packages, and service preference, calls the UPS Shipping API to create the label, and stamps the Acumatica sales order or shipment number onto the package as a UPS reference number. The returned 1Z tracking number and the base64 label are written back onto the Acumatica shipment. The return flow brings UPS tracking and delivery events into Acumatica: ml-connector polls the Track API, or receives Track Alert webhooks where the customer subscribes, and posts scan events and the actual delivery date and signature back onto the matching order so status reflects what UPS reports.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Acumatica side it accepts the full tenant URL and the exact endpoint version per customer, since a mismatched version returns 404, and it wraps every field value in the required value object. On the UPS side it requests a client-credentials bearer token and caches it for its full four-hour life, refreshing five minutes before expiry, because UPS caps token generation at roughly 250 requests per day and fetching one per call exhausts that budget fast; the 6-digit account number is sent as x-merchant-id at token time and as AccountNumber in requests so negotiated rates apply instead of retail. Acumatica recipient addresses can be run through the UPS Address Validation API before a label is created, which also classifies residential versus commercial so a surcharge does not surprise you later. Because UPS cannot be queried by ERP document, ml-connector relies on the reference number it stamped at ship time to match a tracking number back to its Acumatica order. Acumatica rate limits are license-tier dependent and UPS returns 429 with no retry-after header, so calls back off with exponential jitter, and because shipment creation is not idempotent ml-connector dedupes each request by job id and stores the returned tracking number before any resubmit. Track Alert subscriptions expire after fourteen days, so the connector renews them for shipments still in transit.

A real-world example

A mid-sized industrial parts distributor runs Acumatica Cloud ERP for orders, inventory, and finance, and ships every customer order through UPS. Before the integration, warehouse staff re-typed each shipment's address into UPS WorldShip, printed the label, then pasted the tracking number back into the Acumatica order by hand, and customer service had no delivery status without logging into UPS separately. With Acumatica and UPS connected, releasing a shipment creates the UPS label automatically with the order number attached as a reference, the 1Z tracking number lands on the order, and delivery scans flow back so service reps see status inside Acumatica. The manual re-keying and the swivel-chair lookups are gone.

What you can do

• •Create UPS shipping labels automatically from released Acumatica shipments, with no re-keyed addresses.
• •Stamp the Acumatica sales order or shipment number onto the package as a UPS reference number so packages map back to ERP documents.
• •Write the returned 1Z tracking number and label onto the matching Acumatica shipment.
• •Post UPS scan events and the actual delivery date and signature back into Acumatica order status.
• •Validate and classify recipient addresses through UPS before a label is created, and cache the UPS token to stay under the daily token cap.

Questions

Which direction does data move between Acumatica and UPS?

The main flow is Acumatica to UPS: released shipments become UPS labels, and the order number is stamped onto the package as a UPS reference number. The return flow brings UPS tracking numbers, scan events, and delivery confirmation back onto the matching Acumatica order. UPS holds no vendor, invoice, or GL data, so ml-connector never posts financial records into it.

Can ml-connector match a UPS package back to its Acumatica order?

Yes, by using the reference number it sets at ship time. UPS cannot be queried by ERP document directly, so ml-connector writes the Acumatica order or shipment number onto the package and then looks shipments up by that value through the Track API reference lookup. That reference is how a 1Z tracking number is tied back to the correct Acumatica shipment.

Does the integration use UPS webhooks or polling for delivery status?

Either, depending on the customer's UPS setup. Track Alert is a paid service that pushes delivery events to a callback URL, authenticated by a credential header you supply at subscription time rather than an HMAC signature, and its subscriptions expire after fourteen days so ml-connector renews them while a shipment is in transit. Where Track Alert is not enabled, ml-connector polls the Track API on a schedule, and on the Acumatica side it polls or receives Push Notifications since Acumatica change events use a shared-secret header rather than a signed payload.