HubSpot + Sage X3 integration

Sage X3 is organized around folders. Each folder is a complete set of parameters, rules and data, stored on SQL Server or Oracle and served through the Syracuse web server, and one installation can hold several. It runs on a company’s own servers or as Sage X3 Online. Either way, the people who sell for an X3 business rarely have an X3 login.

What they want is ordinary: the open orders, the last invoice and the credit position on the HubSpot company before a call. Today they ask the office, which answers from an X3 inquiry screen or an exported report, and the answer arrives after the conversation it was needed for.

Two facts about X3 shape this project more than the object list. The first is where it runs, because X3 Online accepts only OAuth2 tokens, while an on-premises server also allows basic or certificate authentication. The second is how far each module has moved from X3’s classic screens to its newer classes and representations. Sage is upgrading the modules progressively, and whether a module has made that move decides whether the Web API or SOAP carries a write. Sage also ships Version 12 update releases twice a year, and the integration has to keep working through each one.

Five objects carry it. Customers, read from the BPCUSTOMER representation, become HubSpot companies and their contacts HubSpot contacts. Sales orders arrive as deals, sales invoices as custom object records, and X3 products as HubSpot products.

Reads can all come through the Web API, because Sage X3 provides read-only representations on every resource, so a first build moves everything one way into HubSpot. A write back, usually a won deal creating a customer or an order, is a second phase, and it uses the Web API only where that module has been upgraded.

Keys are X3’s codes, not names: the customer code (BPCNUM), the order and invoice numbers and the product reference, each held in a custom HubSpot property together with the folder it came from. The folder matters because a test folder copied from production holds the same codes, and a key without it lets a test run overwrite live records.

Sage documents no webhook subscription for X3, so the service polls, one representation at a time. It holds an OAuth2 bearer token for a user mapped to an X3 user with its own security profile, and every hour it queries each representation with the Web API’s query syntax: a GET on the class and representation, a where predicate to narrow it, and an orderBy on the key.

Paging follows the links X3 returns. Each page carries a $next link keyed on the last code read, and the service follows it rather than computing offsets.

Writes into HubSpot are batch upserts on the X3 code in a custom property, and orders and invoices are linked to their company in a second pass. The service tracks each representation with a watermark where it exposes an update date and a row hash where it does not, so a failed run picks up where it stopped. A replay re-reads one representation over a range of codes, and the same code range drives a reconciliation against an X3 inquiry.

On X3 the choice turns on where the system runs and which modules you need to write to. For reading, a custom API integration on the Web API works on premises and on X3 Online alike, and it keeps the mapping, the keys and the run history in one service that can replay.

Commercient’s Sage X3 app is the packaged alternative, a third-party sync that suits a standard customer and order feed with nobody of yours on call.

We steer away from any general automation platform that reaches X3 through SOAP. X3 licenses SOAP traffic by data volume per period, and a platform that polls full records spends that allowance on rows that did not change. Sage 100, despite the shared brand, connects in a completely different way, which the Sage 100 page covers.

1. Scope. We confirm where X3 runs, which folders are live, and which modules have moved to classes and representations, since that decides the write path.
2. Architect. We fix the representations, the keys with their folder, the watermark per representation and the page size, and name any SOAP web service to publish.
3. Build. We develop against a test folder copied from production and a HubSpot sandbox, and the service refuses any folder or portal outside its allowlist.
4. Validate. Customer counts and open order totals per folder are checked against an X3 inquiry, and finance walks the differences with us.
5. Operate. We watch each representation’s run history, keep replay available, and rerun the reads in the test folder before each update release.