FreshBooks and SAP Ariba integration

What moves between them

The main flow runs from SAP Ariba into FreshBooks. ml-connector reads Ariba suppliers from the Supplier Data API and creates or updates matching FreshBooks bill vendors, then reads Ariba purchase order and invoice header data through reporting jobs and posts it into FreshBooks as AP bills against the right vendor. A secondary flow runs the other way: when FreshBooks marks a bill paid, ml-connector can update the matching Ariba contract accumulator with that committed spend through the Contract Compliance API. Vendor and contract identifiers are aligned first so every bill lands on a real FreshBooks vendor and every spend update lands on the right Ariba contract. Cadence is scheduled polling on both sides, since Ariba has no webhooks and FreshBooks webhook latency is not guaranteed.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Ariba side it fetches a client-credentials Bearer token, caches it, and refreshes before its one-hour expiry, sends the static Application Key in the apiKey header, and appends the realm as a query parameter on every request. On the FreshBooks side it sends the user OAuth Bearer token, refreshes it when needed, and persists the rotated refresh token because each refresh invalidates the prior one, while resolving the accountId and businessId from the FreshBooks identity endpoint. Supplier reads run through the synchronous Supplier Data API with pageToken paging, while purchase orders and invoice headers come from Ariba reporting jobs, which ml-connector submits filtered by an updated-date window, polls until complete, and downloads page by page, keeping a high-water-mark timestamp and respecting the one-year window limit on each job. Each AP bill requires a FreshBooks vendor, so suppliers are mapped first; bills are created with a stable bill_number derived from the Ariba document so re-reads do not double-post, which matters because FreshBooks has no idempotency-key header. Ariba reporting-job submission is rate limited and returns 429, so ml-connector watches the X-RateLimit-Remaining-minute header and backs off, and FreshBooks 429 throttling is handled with exponential backoff. Writes back to Ariba are limited to supplier status and contract accumulators, since PO and invoice writes need cXML or SOAP and are out of scope.

A real-world example

A 40-person specialty engineering firm runs FreshBooks for its books, invoicing, and vendor payments, but it sells into large manufacturers that require all purchasing to flow through SAP Ariba. Before the integration, an office manager logged into the buyer's Ariba realm, exported approved purchase orders and supplier records, and re-keyed each one into FreshBooks as a vendor and a bill, which was slow and left the FreshBooks vendor list out of step with what Ariba actually approved. With FreshBooks and SAP Ariba connected, approved Ariba suppliers and purchase orders flow into FreshBooks as bill vendors and AP bills within the polling window, and once a bill is paid the committed spend updates the matching Ariba contract. The re-keying is gone and the two systems agree on what was ordered and paid.

What you can do

• •Read SAP Ariba suppliers from the Supplier Data API and create or update matching FreshBooks bill vendors.
• •Pull Ariba purchase order and invoice header data through reporting jobs and post it into FreshBooks as AP bills against the right vendor.
• •Push FreshBooks paid-bill spend back to SAP Ariba contract accumulators through the Contract Compliance API.
• •Bridge the Ariba client-credentials token plus apiKey header to the FreshBooks user OAuth token, refreshing both before expiry.
• •Poll on a schedule with date-window reporting jobs, stable bill numbers for dedup, 429 backoff, and a full audit trail on every record.

Questions

Which direction does data move between FreshBooks and SAP Ariba?

The main flow is SAP Ariba into FreshBooks. Suppliers, purchase orders, and invoice headers move from Ariba into FreshBooks as bill vendors and AP bills. A secondary flow sends FreshBooks paid-bill spend back to Ariba contract accumulators through the Contract Compliance API, since Ariba purchase order and invoice writes require cXML or SOAP and are not done over REST.

Does the integration use webhooks or polling?

It is poll-based. SAP Ariba has no general-purpose outbound webhooks, so ml-connector submits reporting jobs filtered by an updated-date window, polls until they complete, and downloads results by pageToken, keeping a high-water-mark timestamp. FreshBooks does offer webhooks, but their delivery latency is not guaranteed, so they are treated as an optional hint while scheduled polling stays the reliable spine.

How does it avoid creating duplicate bills in FreshBooks?

FreshBooks has no idempotency-key header, so ml-connector derives a stable bill_number from the source Ariba document and matches on it before posting. Because each FreshBooks AP bill must reference an existing vendor, suppliers are mapped first so every bill lands on a real FreshBooks bill vendor. Re-reading the same Ariba job result therefore updates rather than duplicates the bill.