Sage X3 × HubSpot
How customers, products, quotes, sales orders and invoices in Sage X3 can flow into HubSpot, how closed deals can become X3 orders, and how a multi-company, multi-site X3 setup maps to one HubSpot portal.
Does Sage X3 integrate with HubSpot?
Sage X3 runs finance, sales, purchasing, inventory and manufacturing for mid-sized and large companies, often across several companies and sites. There is no HubSpot-built app for X3, so the integration is a custom build on X3's own APIs.
Public documentation. The client's own admin issues credentials, with no vendor approval needed.
Open API. The GraphQL and SOAP APIs are documented publicly. The client's X3 administrator sets up a dedicated user or connected application.
Based on the vendor's public documentation. Access terms are confirmed with the vendor and the client in discovery.
Sage X3 can give HubSpot a complete quote-to-cash picture, with sales working in HubSpot and finance staying in X3.
Campaign Creators assessment
X3 exposes its data through a GraphQL API (Sage X3 Services, authenticated with a connected application) and through SOAP web services, including import and export services that run X3's own templates. That makes customers, products, quotes, orders and invoices readable, and lets a won HubSpot deal create an X3 sales order. Two things set the pace: many X3 systems run on premises, so the integration needs a secure route to the X3 server, and the company, site and folder structure has to be mapped before any data moves.
Ratings are CC judgments from Sage's public documentation. GraphQL availability depends on the client's X3 release and hosting; endpoints, pool sizes and throughput are confirmed in discovery.
Documented APIs on both sides of the deal
GraphQL queries read business partners, products and sales documents, and SOAP web services can import a sales order through X3's own template, so X3 validation still applies to every order HubSpot sends.
Companies, sites and folders
One X3 install can hold several folders, each with its own companies and sites. Every HubSpot record needs a rule for which folder, company and site it belongs to.
Network access and an API user come first
An on-premises X3 server must be reachable over HTTPS from the integration layer, and the client's X3 administrator sets up a dedicated user, connected application or SOAP connection pool.
Which Sage X3 APIs does the integration use?
Seven X3 areas are relevant to HubSpot. Four carry quote-to-cash, two support it, and one is a scope decision to make early.
Customers & contacts
Business partners · GESBPC · x3MasterDataCustomer records (code BPCNUM, company name BPCNAM, category BCGCOD), their addresses, sales reps and contacts.
- GraphQL
businessPartnerqueries with cursor paging - Bill-to, pay-by and ship-to roles on the customer
- Customer code becomes the HubSpot match key
Products & prices
Products · GESITM · price listsThe sellable catalog (product reference ITMREF) and the prices sales should quote from.
- Product reference becomes the HubSpot SKU
- Price-list price feeds the HubSpot product library
- Low change rate, sync daily
Sales quotes & orders
GESSQH · GESSOH · SOH templateQuotes (SQHNUM) and sales orders (SOHNUM) with sold-to customer, sales site, currency and status fields.
- Delivery (DLVSTA) and invoice (INVSTA) status
- Credit (CDTSTA) and hold (HLDSTA) status
- Orders created through the SOH import template
Invoices & payments
GESSIH · customer receivablesPosted sales invoices and the open balance on each customer, so sales and service see who owes what.
- Invoice number, dates and amounts
- Open balance per invoice and per customer
- Read-only in HubSpot; X3 stays the ledger
Import & export services
AOWSIMPORT · AOWSEXPORT · AOWSBATGETSOAP services that run X3 import and export templates, such as BPC for customers and SOH for sales orders.
- Bulk backfill of customers and history
- Create orders with X3's own validation
- Batch status checked with AOWSBATGET
Companies, sites & dimensions
Folders · companies · sites · analyticsThe legal and operational structure every document carries: folder, company, sales site and analytical dimensions.
- Sales site (SALFCY) on every order
- Company and currency on every invoice
- Drives HubSpot business units, teams and reports
Where orders are created
Scope decisionDecide whether a won HubSpot deal creates the X3 sales order, or whether orders are still keyed in X3 and only flow back to HubSpot.
- HubSpot to X3: faster, needs price and credit rules agreed
- X3 only: simpler, HubSpot reflects orders after entry
- Either way, X3 owns pricing, tax and credit
How does the Sage X3 HubSpot integration work?
HubSpot and X3 never talk directly. A CC-built integration layer reaches X3 through a secure gateway, reads and writes through the GraphQL API or SOAP services, routes each record to the right folder, company and site, and writes to HubSpot in batches.
Each record has one owner
HubSpot owns the relationship, the pipeline and the quote. X3 owns customer accounts once created, prices, tax, credit, orders and invoices.
One key per record
The X3 customer code is stored on the HubSpot company and the product reference on the HubSpot product, so every later update matches without guesswork.
X3 rules still apply
Orders from HubSpot go in through X3's own APIs and templates, so X3 validation, pricing and credit checks run as if the order were keyed in X3.
What does Sage X3 HubSpot integration setup involve?
Each phase ends on a gate the client signs off before the next begins. Read-only flows go live first, so sales sees X3 data in HubSpot before HubSpot writes anything back.
Discovery & structure
List the X3 folders, companies and sites in scope, the hosting model, the X3 release, and which teams need which X3 data in HubSpot.
Access & security
The client's X3 administrator sets up a dedicated API user, a connected application or SOAP connection pool, and a secure HTTPS route from the integration layer.
Ownership & match rules
Agree which system owns each field, how customers match (customer code, then domain), and how HubSpot owners map to X3 sales reps.
HubSpot data model
Create the x3_ properties, product library, deal pipeline stages tied to X3 order status, and the order and invoice views in a HubSpot sandbox.
Build read flows
Build customer, product, order and invoice reads with change detection, idempotent writes and an error replay queue.
Build write flows
Build new-customer and won-deal-to-sales-order creation, using X3's APIs or import template so X3 validation runs.
Backfill, parallel run & launch
Load customers, products and an agreed order and invoice history window, run two weeks in parallel, then switch on writes.
What does the Sage X3 HubSpot integration sync?
X3 field codes come from Sage's online help for the Customers, Quotes, Orders and Invoices functions. GraphQL property names differ from these codes and are confirmed against the client's X3 release in discovery.
| Sage X3 field | HubSpot property | Object | Direction | Notes |
|---|---|---|---|---|
| Customers & contacts | ||||
| Customer (BPCNUM) | x3_customer_code | Company | ↔ Both | Primary match key. Written back when HubSpot creates the customer. |
| Company name (BPCNAM) | name | Company | ↔ Both | HubSpot fills blanks only once the customer exists in X3. |
| Category (BCGCOD) | x3_customer_category | Company | X3 → HS | X3 customer category. |
| Active (BPCSTA) | x3_customer_status | Company | X3 → HS | Inactive customers are flagged, not deleted. |
| Address lines, city, postal code, country | address, city, zip, country | Company | ↔ Both | Default address. Other addresses stay in X3. |
| Currency (CUR) | x3_currency | Company | X3 → HS | Customer's trading currency. |
| Sales rep (REP) | hubspot_owner_id | Company | ↔ Both | Mapped through an owner-to-rep table. |
| Contact name, email, phone | firstname, lastname, email, phone | Contact | ↔ Both | Contacts tab on the customer. Confirm field codes in discovery. |
| Products & pricing | ||||
| Product (ITMREF) | hs_sku | Product | X3 → HS | Primary match key for products. |
| Product description | name, description | Product | X3 → HS | Confirm which description field the client uses. |
| Product category | x3_product_category | Product | X3 → HS | Confirm in discovery. |
| Price-list price | price | Product | X3 → HS | From the agreed X3 price list, per currency. |
| Quotes & orders | ||||
| Quote number (SQHNUM) | x3_quote_number | Deal | X3 → HS | Set when a quote is raised in X3. |
| Order number (SOHNUM) | x3_order_number | Deal | ↔ Both | Written to the deal when X3 creates the order. |
| Sold-to (BPCORD) | Deal ↔ Company association | Deal | ↔ Both | Matched on customer code. |
| Sales site (SALFCY) | x3_sales_site | Deal | ↔ Both | Required on orders sent to X3. |
| Currency (CUR) | deal_currency_code | Deal | ↔ Both | Must match the customer's currency rules. |
| Order lines: product, quantity, price | Line items (hs_sku, quantity, price) | Line item | ↔ Both | HubSpot lines become X3 order lines; X3 reprices. |
| Order total | amount | Deal | X3 → HS | X3 total after pricing and tax overwrites the HubSpot estimate. |
| Delivery status (DLVSTA) | x3_delivery_status | Deal | X3 → HS | Not shipped, partially shipped, shipped. |
| Invoice status (INVSTA) | x3_invoice_status | Deal | X3 → HS | Not invoiced, partially invoiced, invoiced. |
| Credit status (CDTSTA) | x3_credit_status | Deal | X3 → HS | Blocked orders alert the deal owner. |
| Invoices & balances | ||||
| Invoice number | x3_invoice_number | Invoice | X3 → HS | One HubSpot invoice record per X3 invoice. |
| Invoice date and due date | x3_invoice_date, x3_due_date | Invoice | X3 → HS | Confirm field codes in discovery. |
| Invoice amount | x3_invoice_amount | Invoice | X3 → HS | Including tax, in invoice currency. |
| Open balance per customer | x3_open_balance | Company | X3 → HS | Rolled up in the integration layer. |
| Structure | ||||
| Folder | x3_folder | Company | X3 → HS | Set per connection; one folder per pool or endpoint. |
| Company (CPY) | x3_company | Deal | ↔ Both | Legal entity on orders and invoices. |
How are authentication and API limits handled?
X3 is usually run by the client or a hosting partner, so access is set up by the client's X3 administrator. Values Sage does not publish are marked for confirmation.
| Topic | Sage X3 | HubSpot |
|---|---|---|
| Access model | Client-owned. On premises or Sage-hosted. A dedicated X3 user for the integration, with rights limited to the objects in scope. | Self-serve in the client portal. Custom objects need an Enterprise hub. |
| Interfaces | GraphQL API through Sage X3 Services (endpoint path /xtrem/api). SOAP web services through connection pools, including AOWSIMPORT and AOWSEXPORT for templates. | REST APIs: CRM objects, products, line items, associations, imports. |
| Authentication | GraphQL: JWT bearer token from a connected application (client ID and secret, token lifetime set per app). SOAP: OAuth2 or the method the X3 server is configured for. | Private app access token or OAuth 2.0 public app, scoped per object. |
| Network | An on-premises X3 server needs an HTTPS route the integration layer can reach (gateway or allow-listed address). Confirm with the client's IT team. | Cloud service; no network setup. |
| Change detection | Polling on update timestamps or X3 export templates. Event or push options: not published. Confirm in discovery. | Webhooks for HubSpot changes such as deal stage. |
| Rate limits | Not published. Throughput depends on the X3 server and connection pool size. Confirm with Sage or the client's X3 partner. | Per-10-second burst and daily limits by subscription tier. |
| Structure | Each folder is a separate dataset; companies and sites sit inside a folder. Confirm which folders are in scope. | One portal; business units or teams can separate companies. |
What should you plan for, and what does the integration unlock?
Severity reflects impact on the SOW, not technical difficulty alone.
Challenges to plan for
Many X3 servers sit behind the client's firewall. Make the HTTPS route and security review a client-owned dependency with a date in the SOW.
The same customer can exist in more than one folder or company. Agree the structure map and match rules before building, or HubSpot ends up with duplicate companies.
Orders sent from HubSpot must pass X3 pricing, tax and credit rules. Finance approves the order template, default values and error handling before writes go live.
GraphQL coverage depends on the client's X3 release and hosting. Where a node is missing, the build uses SOAP for that object. Confirm in the access phase.
Many X3 systems carry custom fields and screens. Inventory them in discovery so the field list reflects the client's X3, not the standard one.
Changes are found by polling. Agree a sync interval per object (minutes for orders, daily for products) so HubSpot stays current within API limits.
Opportunities in HubSpot
Sales closes in HubSpot and the order lands in X3 with the right customer, site and lines, without rekeying.
Delivery, invoice and credit status show on the deal, so reps answer customer questions without asking operations.
HubSpot products carry X3 references and list prices, so quotes start from the same catalog finance invoices from.
The customer's open balance on the company record tells reps when to call finance before promising more.
Last order date and order history drive HubSpot lists for reorder reminders and win-back campaigns.
Pipeline in HubSpot and booked orders from X3 meet in one dashboard, split by legal company and sales site.
Sales works in HubSpot. Finance works in X3.
Each step hands the record to the system that owns it. HubSpot runs the pipeline and the quote; X3 runs the order, the invoice and the ledger, and reports back.
- Customers and products sync from X3, so every HubSpot quote uses a real customer code, product reference and price.
- A won deal creates the X3 sales order, or a new customer first if the company has no customer code.
- X3 prices, taxes and credit-checks the order, then writes the order number and status back to the deal.
- Invoices and open balances flow back to HubSpot, so sales and service see the whole account.
Which HubSpot properties does the integration create?
All custom properties use the x3_ prefix in a Sage X3 property group. Rollups such as open balance are calculated in the integration layer so every report agrees.
| Internal name | Label | Object | Type | Source / logic |
|---|---|---|---|---|
| x3_customer_code | X3 Customer Code | Company | Single-line text | BPCNUM; unique |
| x3_customer_category | X3 Customer Category | Company | Dropdown | BCGCOD |
| x3_customer_status | X3 Customer Status | Company | Dropdown | BPCSTA (active / inactive) |
| x3_currency | X3 Currency | Company | Dropdown | Customer currency (CUR) |
| x3_folder | X3 Folder | Company | Dropdown | Folder the customer belongs to |
| x3_open_balance | X3 Open Balance | Company | Number (currency) | Sum of open invoice balances |
| x3_order_number | X3 Order Number | Deal | Single-line text | SOHNUM; unique |
| x3_sales_site | X3 Sales Site | Deal | Dropdown | SALFCY |
| x3_company | X3 Company | Deal | Dropdown | Legal company on the order |
| x3_delivery_status | X3 Delivery Status | Deal | Dropdown | DLVSTA |
| x3_invoice_status | X3 Invoice Status | Deal | Dropdown | INVSTA |
| x3_credit_status | X3 Credit Status | Deal | Dropdown | CDTSTA |
Interactive scope builder
Choose the X3 areas and fields for this engagement and the direction each one syncs. Required fields are the keys the integration cannot run without. Copy the summary into the SOW or a reply to the client.
Scope summary
Sources & verification
Based on public documentation from Sage and HubSpot. Each item marked for confirmation is verified against the client's X3 release during the access phase.
- Sage X3 GraphQL API: creating a connected application
- Sage X3 GraphQL API: example queries for business partners
- Sage X3 import/export guide: developing with web services
- Sage X3 import/export guide: exporting sales orders with web services
- Sage X3 online help: Customers (GESBPC)
- Sage X3 online help: Sales orders (GESSOH)
- HubSpot Knowledge Base: create and manage orders
Sage X3 HubSpot integration FAQ
Does Sage X3 integrate with HubSpot?
Yes, through a custom integration. There is no HubSpot-built app for Sage X3, so Campaign Creators builds on X3's GraphQL API (Sage X3 Services) and its SOAP web services, including the import and export services that run X3's own templates.
What data syncs between Sage X3 and HubSpot?
X3 customers and products sync to HubSpot companies and products, with X3 customer codes and product references as the match keys. Won HubSpot deals create X3 sales orders, and order numbers, delivery, invoice and credit status, invoices and open balances are written back to HubSpot.
Can the integration work with an on-premises Sage X3 server?
Yes. The integration layer needs a secure HTTPS route to the X3 server, such as a gateway or an allow-listed address, which the client's IT team sets up. Sage-hosted X3 needs no extra network setup. The folders, companies and sites in scope are mapped before any data moves.
What does setting up the Sage X3 HubSpot integration involve?
Seven phases, each closed by a client sign-off: discovery and structure, access and security, ownership and match rules, the HubSpot data model, read flows, write flows, and backfill with a two-week parallel run. Read-only flows go live first, so sales sees X3 data before HubSpot writes anything back.
How long does the integration take and what does it cost?
Timeline and cost depend on the X3 release and hosting, the folders, companies and sites in scope, and the history to load. Campaign Creators confirms these in discovery and provides a fixed scope before the build starts.
Ready to Get More From HubSpot?
Whether you’re implementing HubSpot, optimizing what you already have, connecting systems, or scaling your customer experience, we’ll help you figure out the right next step.
.png?width=1920&height=553&name=cc-logo-color%20(2024).png)