Sage X3 and Ramp integration

What moves between them

Ramp bills, purchase orders, and transactions flow into Sage X3. As bills are created or updated in Ramp, ml-connector receives webhook events in real time, matches vendors to Sage X3 suppliers, maps GL accounts and cost centers, and creates corresponding supplier invoices (supplierBpInvoice) and GL journal entries (gaccount entries) in X3. Corporate card transactions can also be ingested from Ramp and recorded in X3 as expense transactions or memo items. The integration is unidirectional from Ramp to X3; Sage X3 remains the system of record for GL balances and supplier master data. Reference data such as vendors, GL accounts, and departments is aligned so every bill and transaction maps to a valid X3 dimension.

How ml-connector handles it

ml-connector accepts OAuth2 client credentials from Ramp, registers a webhook endpoint to receive real-time bill, transaction, and vendor events, and verifies each webhook signature via HMAC-SHA256. On the Sage X3 side, ml-connector uses OAuth2 client credentials (GraphQL, recommended for V12+) or HTTP Basic Authentication (REST api1 legacy path) to connect to the customer's X3 server URL. When a Ramp bill webhook arrives, ml-connector looks up or creates the vendor in X3, maps Ramp GL account codes to X3 gaccount entries, applies the customer's cost center allocations, and posts the invoice and accrual journal. Because X3 access tokens expire in 5 minutes, ml-connector caches and refreshes them before expiry. Corporate card transactions are batched and summarized before posting to X3 to avoid spamming the journal. Purchase orders from Ramp are mapped to X3 purchase orders by line item total; because Ramp POs are read-only from the API, changes originate in Ramp and sync down to X3 in one direction. Every bill, transaction, and PO carries a full audit trail, and failed records are queued for replay once the upstream API recovers.

A real-world example

A mid-sized services company runs Sage X3 for finance and procurement and uses Ramp for corporate spend management and bill pay. Before the integration, when a bill was paid via Ramp, the accounting team had to manually log into X3, find or create the vendor, and re-enter the bill details and GL account allocations - a process that could take 15-20 minutes per bill and led to frequent errors during month-end close. With Sage X3 and Ramp connected, bills are recorded in Ramp by project managers and automatically sync into X3 with the vendor, amount, GL account, and cost center pre-filled. Corporate card charges flow in the same way. The accounting team now spends the first hour of month-end close validating GL balances instead of re-keying bills, and discrepancies between spend and the ledger are caught within hours rather than days.

What you can do

• •Receive Ramp bill webhooks in real time and post them into Sage X3 as supplier invoices and GL journal entries, mapped to the correct vendors and GL accounts.
• •Sync corporate card transactions from Ramp into X3 as expense transactions or journal line items, allocated to the cost centers specified in Ramp.
• •Map Ramp purchase orders into X3 purchase orders by matching vendor, line item, and amount, keeping procurement in sync across both systems.
• •Authenticate Ramp with OAuth2 client credentials and refresh tokens when they expire, and Sage X3 with OAuth2 (GraphQL, V12+) or HTTP Basic auth (REST api1 legacy).
• •Maintain a full audit trail on every bill, transaction, and PO, with idempotency keys to prevent duplicate posts if a webhook is retried or a network call is replayed.

Questions

Which direction does data move between Sage X3 and Ramp?

Data moves from Ramp into Sage X3. Bills, purchase orders, and corporate card transactions created or updated in Ramp are synced to X3 as supplier invoices, purchase orders, and journal entries. Sage X3 remains the system of record for GL balances, supplier master data, and account structures. The integration is unidirectional because Ramp is the source of spend truth and X3 is the financial sink.

Does the integration handle both Sage X3 REST and GraphQL, and does it matter which one I use?

Yes. ml-connector supports both REST api1 (HTTP Basic auth, available on V6+) and GraphQL Xtrem (OAuth2, recommended for V12+). GraphQL is preferred if your X3 instance is V12 or later because it is faster, has richer query support, and uses OAuth2 client credentials instead of HTTP Basic auth. If you are on X3 V6-V11, REST api1 is the available option. Your X3 admin enables Basic auth in nodelocal.js for the REST path.

What happens if a Ramp bill webhook arrives but the vendor does not exist in Sage X3?

ml-connector will attempt to match the Ramp vendor to an existing X3 supplier by name or code. If no match is found, the bill is held in a queue and flagged for review. You can then either create the vendor in X3 and replay the bill, or map the Ramp vendor to an existing X3 supplier in ml-connector configuration. Once the mapping is in place, the bill is posted automatically.