What a Salesforce Sage Intacct integration actually has to carry

The common assumption at the start of a Salesforce Sage Intacct integration is that the job is to push closed-won opportunities into the finance system as sales invoices. In a one-off, transactional business that assumption is broadly sound. In a subscription business it is wrong in a way that becomes expensive around month four, when the first mid-term upgrades and part-period cancellations arrive and the invoices in Sage Intacct stop matching what the sales team believes it sold.

The unit of work in a subscription business is not the opportunity. It is the contract, and the contract has a life of its own after the deal closes: it renews, it co-terminates with other contracts, it gains and loses lines, it changes quantity halfway through a billing period, and it is occasionally suspended rather than cancelled. An opportunity is a point-in-time record of a commercial decision. A contract is a state machine. The integration has to carry the state transitions, not just the initial sale.

That distinction determines the boundary of record, which is the single most important decision in the project and the one that should be settled in discovery before any code is written. Our usual recommendation is that Salesforce owns the commercial terms of the contract — customer, products, quantities, prices, discounts, start and end dates, billing frequency — and Sage Intacct owns everything downstream of those terms: the billing schedule, the invoice, the tax treatment, the revenue schedule, the receipt and the ledger. The integration moves terms one way and financial status the other way. It does not allow both systems to edit the same field.

Once that boundary is agreed, the object mapping follows fairly naturally. A Salesforce Account maps to a Sage Intacct Customer. A Salesforce Contract or Order maps to an Intacct Contract, with contract lines mapping to contract lines. Where the business uses Salesforce CPQ, quote lines carry the subscription term and prorate multiplier that the mapping needs. Where it does not, the same information usually exists in custom fields and has to be located, documented and, in a surprising number of cases, cleaned before it can be relied upon.

  • Salesforce owns — Customer and contact detail, contracted products, quantity, unit price, discount, term dates, billing frequency, renewal intent and cancellation notice.
  • Sage Intacct owns — Billing schedules, invoice numbering, tax determination, revenue recognition schedules, deferred revenue balances, receipts, credit notes and the general ledger.
  • The integration owns — The mapping between the two identifier sets, the ordering of events, retry and failure handling, and an auditable record of what was sent and what came back.

Mapping the subscription lifecycle, not just the first sale

A subscription contract generates a small number of event types, and the integration should be specified in terms of those events rather than in terms of records. New business creates a contract and its billing schedule. An upgrade adds a line or increases a quantity from an effective date that is rarely the start of a billing period. A downgrade does the reverse and may or may not generate a credit, depending on the commercial terms. A renewal extends the term, often with an uplift. A cancellation ends the contract at a notice date and may leave one final part-period invoice outstanding. Each of those is a different message with a different set of required fields.

Mid-term amendments are where most integrations fail acceptance testing. Suppose a customer on a monthly plan adds fifteen seats on the eleventh of the month. Sage Intacct can prorate the additional seats for the remainder of the period, but it can only do so correctly if the integration sends the effective date, the proration method and the correct relationship to the existing contract line. If the integration instead creates a fresh contract line with a start date of the eleventh and the same billing cycle, the customer now has two invoices on different dates for what the sales team considers one subscription, and the finance team spends the next period reconciling by hand. Decide the proration policy in discovery, write it down, and test it with real amendment dates rather than clean first-of-month examples.

Sequencing matters as much as content. If an upgrade and a cancellation are raised in Salesforce within the same hour, and the integration processes them out of order, Sage Intacct will end up with a contract line that was added after termination. The practical fix is to carry an event timestamp and a monotonic sequence number on every message, process events for a given contract strictly in order, and hold — rather than discard — any event that arrives for a contract whose earlier events have not yet been applied. Parallelism across contracts is fine. Parallelism within a contract is not.

There are also states that exist commercially but have no obvious finance equivalent. A paused subscription, a trial converting to paid, a contract transferred between group entities after an acquisition: each needs an explicit decision about what Sage Intacct should do. The answer is sometimes that the integration does nothing and the change is handled manually by the finance team, and that is a legitimate outcome provided it is agreed in writing rather than discovered in production.

Deferred revenue, dimensions and the reporting the board will ask for

One of the reasons a subscription business chooses Sage Intacct in the first place is its handling of contract revenue and deferred revenue schedules under IFRS 15 and ASC 606. That capability only earns its keep if the integration supplies the inputs it needs. A contract line needs a revenue template, a revenue start and end date, and — where the performance obligations differ — separate treatment for the recurring element, any one-off implementation fee and any usage-based charges. Sending everything as a single line with a single template produces a deferred revenue balance that is arithmetically consistent and commercially meaningless.

Dimensions are the second input. Sage Intacct's dimensional model is what allows a finance team to report annual recurring revenue by product, by region, by customer segment and by entity without building a separate reporting layer. Those dimensions have to be populated at the point the transaction is created, because retrofitting them across twelve months of posted journals is not a pleasant exercise. The integration should map Salesforce fields to Intacct dimensions explicitly and fail loudly when a required dimension cannot be resolved, rather than defaulting to a catch-all value that quietly pollutes the reporting.

Multi-entity groups add a further constraint. If the Salesforce instance is global and Sage Intacct is configured with multiple entities and a shared chart of accounts, the integration needs a deterministic rule for which entity a contract belongs to, derived from something stable such as the selling legal entity on the opportunity rather than the owner's territory. Currency follows from that: the contract currency, the entity's base currency and the group reporting currency are three different things, and the integration should only ever send the contract currency and let Sage Intacct perform the translation with its own rates.

It is worth noting what should not cross the bridge. Invoice numbers, tax codes, nominal codes and revenue schedules are finance artefacts and should be generated in Sage Intacct. Where sales users need visibility of them — and they usually do, for collections conversations — the integration can write a read-only summary back onto the Salesforce Account or Contract record. That back-flow typically includes invoice number, invoice date, gross amount, amount outstanding and days overdue, refreshed daily. It is a display copy, not a second source of truth, and the field-level security should say so.

Reconciliation, failure handling and proving the bridge is correct

Every integration of this kind will fail at some point, usually because of something mundane: a required custom field left blank by a new sales hire, an API session expiring during a long batch, a customer record created in Sage Intacct manually and now duplicated. The question is not whether failures occur but whether they are visible within hours rather than at quarter end. A subscription business that discovers in March that January's upgrades never reached the finance system has a revenue restatement problem, not an IT problem.

We build three controls into this class of work. The first is a message log that records every outbound payload, the response, and the resulting Sage Intacct record key, retained long enough to satisfy audit. The second is a daily reconciliation job that counts contracts and contract-line values on both sides for the previous period and reports any divergence by contract, rather than reporting a single aggregate figure that hides offsetting errors. The third is a dead-letter queue with a human owner: failed messages are held, not dropped, and someone in the finance team is named as responsible for clearing it.

Acceptance testing should be run against a copy of real data and should include a full month-end close in a sandbox. That is the point at which mismatched proration, missing dimensions and incorrectly templated revenue lines surface. Testing with five clean new-business contracts proves very little; testing with a hundred contracts that include mid-term upgrades, a downgrade with a credit note, two cancellations mid-period and one multi-entity transfer proves a great deal. We would generally expect the finance team, not the integration supplier, to sign off the resulting trial balance.

A parallel run of one full period is the final control. During that period the existing manual process continues alongside the integration, and the two sets of output are compared line by line. It is not free, and clients sometimes ask whether it can be skipped. Our answer is that it can, on integrations where the cost of a wrong number is low. On a subscription ledger feeding deferred revenue and investor reporting, it is the cheapest insurance available.

Scoping the work so it does not drift

The scope of a Salesforce Sage Intacct integration is set almost entirely by the number of lifecycle events in play and the complexity of the commercial terms behind them. New business only, annual billing in advance, single entity, single currency: that is a contained piece of work with a predictable estimate. Add monthly billing, mid-term amendments with proration, usage-based charges, multi-entity and multi-currency, and the surface area grows considerably — not because any individual rule is difficult, but because the interactions between them have to be specified and tested.

This is why we insist on discovery and data mapping before an estimate is given. Discovery on this type of project produces a documented field-level map between the two systems, a written proration and credit policy, a list of lifecycle events in scope and explicitly out of scope, the dimension mapping, the entity determination rule, and a set of acceptance test cases drawn from the client's own historical contracts. That document is what the fixed scope and estimate are built on, and it is what protects both sides when someone asks, in week six, whether suspensions could also be handled.

Comparisons with other finance platforms are sometimes useful at this stage. A business evaluating Sage Intacct against NetSuite for subscription billing will find that the integration effort is broadly similar in shape — the same lifecycle events, the same need to keep the commercial record and the financial record separate — while differing in the specifics of the contract and revenue objects. The decision should be made on finance requirements, not on the perceived ease of connecting to Salesforce, because in both cases the difficulty lies in the business rules rather than the transport.

On completion we hand over the code, the field mapping, the runbook for the reconciliation job and the dead-letter process, and the credentials and configuration, so the client is not dependent on us to keep the bridge running. If you are working through a project of this kind and would like to discuss how the scope is likely to break down, we can be reached on 01303 883111 or at hello@api-integrations.co.uk.

Key points

  • Model the contract, not the opportunity: subscription integrations must carry amendments, renewals and cancellations as ordered events, not one-off invoice pushes.
  • Agree the boundary of record in writing — Salesforce owns commercial terms, Sage Intacct owns billing, tax and revenue schedules — and never let both systems edit the same field.
  • Populate revenue templates and Sage Intacct dimensions at the point of creation, and prove the bridge with a full month-end close in a sandbox plus a one-period parallel run.