FreshBooks and UPS integration

What moves between them

Shipment data flows from FreshBooks into UPS. When an invoice is created or updated in FreshBooks and tagged for shipment, ml-connector extracts the client address, invoice total, and items, then creates a shipment in UPS. Tracking data flows back from UPS into FreshBooks via Track Alert subscriptions or polling, with tracking numbers inserted into invoice line items or notes so clients and internal staff can see delivery status. Reference data such as UPS account numbers and shipping address overrides are stored encrypted per customer, keyed to FreshBooks client records.

How ml-connector handles it

ml-connector receives FreshBooks webhook events on invoice.create and invoice.update, checks for a shipping flag in the invoice metadata or line items, and validates the client address against UPS Address Validation to catch formatting errors before shipment. It then calls the UPS Shipment API to create the shipment, passing the client address, invoice weight estimate or items, and service level. The UPS account number is retrieved from encrypted customer config and sent as the x-merchant-id header on every call. ml-connector handles OAuth2 token refresh for both systems independently: FreshBooks tokens are user-delegated and require periodic reauthentication per the user's credential lifetime, while UPS tokens expire every four hours and are cached to avoid hitting the 250-request daily limit. Tracking numbers are pulled via Track Alert subscriptions (which require renewal every 14 days) or Quantum View polling, then written back into FreshBooks invoice line items or notes. Because FreshBooks webhook delivery is not real-time and can be delayed, ml-connector also polls FreshBooks periodically to catch shipment requests that arrived out of band. All requests carry an audit trail: the shipment creation call, the UPS reference number, the tracking subscription refresh, and any address validation or rate-quote calls.

A real-world example

A small-to-mid-sized e-commerce retailer invoices orders through FreshBooks and ships them via UPS. Before this integration, the operations team created shipments manually in the UPS portal when invoices were issued, then copied tracking numbers back into FreshBooks invoice comments. This was error-prone and meant tracking visibility was not available to customers until someone manually pasted the link. With FreshBooks and UPS connected, issuing an invoice with a shipping flag automatically creates the shipment in UPS, and tracking numbers appear in FreshBooks within minutes of the shipment being picked up, so customers can see status directly from their invoice.

What you can do

• •Automatically create UPS shipments when FreshBooks invoices are issued and tagged for shipping.
• •Validate delivery addresses against UPS Address Validation before shipment to catch formatting errors.
• •Map FreshBooks clients to UPS account numbers and retrieve tracking data via Track Alert or Quantum View polling.
• •Refresh UPS OAuth2 tokens within the 4-hour lifetime and renew Track Alert subscriptions every 14 days.
• •Insert tracking numbers and delivery status back into FreshBooks invoice line items or notes with a full audit trail.

Questions

How does ml-connector know which FreshBooks invoices need to be shipped to UPS?

Invoices are marked for shipment through a custom flag in the invoice metadata or a specific line item attribute. ml-connector receives the invoice.create and invoice.update webhook events from FreshBooks, checks for this flag, and triggers UPS shipment creation. If webhook delivery is delayed, ml-connector also polls FreshBooks periodically to ensure no shipments are missed.

What happens if a FreshBooks client address fails UPS address validation?

ml-connector calls UPS Address Validation before creating the shipment. If the address is invalid or ambiguous, it halts shipment creation and logs the validation error to the audit trail so the operations team can correct the address in FreshBooks and retry. This prevents shipments from being created to the wrong location.

How are UPS account numbers and tracking subscriptions managed across multiple customers?

UPS account numbers are stored encrypted in ml-connector per FreshBooks client and are retrieved on each shipment request. Track Alert subscriptions are maintained per customer with automatic renewal every 14 days to prevent expiry. All credentials and subscription state are stored in the audit log so renewals and token refreshes can be traced if a shipment tracking issue arises.