Sage X3 and Square integration

What moves between them

The main flow is Square into Sage X3. After each payment or order completion in Square, ml-connector reads the order and payment records and posts them into Sage X3 as sales invoices and GL revenue entries, mapped to the matching X3 GL accounts and customers. Customer records are also synced to keep Sage X3 customer master aligned with Square merchant customers. Refunds in Square post as GL reversals in X3. Reference data such as GL accounts and product mappings are established up front so every Square transaction lands on a valid X3 dimension.

How ml-connector handles it

ml-connector stores both credential sets encrypted. On the Square side it uses OAuth2 bearer tokens with the 30-day refresh cycle built in. On the Sage X3 side it uses JWT bearer tokens with the 5-minute refresh window and maintains the token state across requests. Since Sage X3 is poll-only, ml-connector polls Square and X3 on a schedule tied to your payment calendar rather than relying solely on Square webhooks. When Square webhooks are registered and functional, they accelerate the poll interval for critical payment events to near real-time. Customer names and GL account codes are mapped first, so every order and payment references a customer and revenue account that already exists in Sage X3. ml-connector tracks the X3 token expiry and re-authenticates before token timeout causes a failed request. Rate-limit retries on both sides are handled with exponential backoff. Every record carries a full audit trail and can be replayed if a downstream GL posting fails.

A real-world example

A mid-sized specialty goods distributor runs Sage X3 for procurement, inventory, and finance, and uses Square for e-commerce and point-of-sale across three retail locations and an online store. Before the integration, the finance team exported order records from Square each morning and manually entered the revenue and customer details into Sage X3, then spent hours reconciling Square's transaction totals against the X3 revenue ledger. With Sage X3 and Square connected, each Square transaction flows into X3 automatically as a sales invoice, allocated to the correct GL revenue account and customer, and refunds post as reversals. Month-end revenue reconciliation starts with the data already in sync, and the daily manual entry step is eliminated.

What you can do

• •Post Square orders and payments into Sage X3 as sales invoices and GL revenue entries, mapped to the correct customers and accounts.
• •Sync customer records from Square into Sage X3 to keep the merchant customer master aligned with your e-commerce channel.
• •Map Square payment methods and order line items to Sage X3 GL accounts and products so transactions land on valid dimensions.
• •Authenticate Square with OAuth2 bearer tokens and Sage X3 with JWT bearer tokens, managing the 5-minute and 30-day refresh cycles.
• •Poll Square and Sage X3 on a schedule tied to your payment calendar, with webhook acceleration for near-real-time order capture, and full replay on failure.

Questions

Which direction does data move between Square and Sage X3?

The main flow is Square into Sage X3. Orders, payments, and customer records move from Square into Sage X3 as sales invoices, GL revenue entries, and customer master records. Refunds in Square post as GL reversals in X3. GL accounts and customer names are reference data aligned in both directions so every transaction lands on a valid X3 dimension.

How does the integration handle Sage X3's lack of webhooks and short token expiry?

ml-connector polls Square and Sage X3 on a schedule tied to your payment calendar since X3 is pull-only. The 5-minute X3 access token expiry is handled automatically by refreshing the JWT bearer token before it times out. Square webhooks, when enabled, are used to accelerate the poll interval for payment and order events to near real-time detection.

How are Square orders mapped to Sage X3 GL accounts and customers?

Before sync starts, customer names and GL account codes are mapped between Square and Sage X3. When an order or payment flows into X3, ml-connector looks up the customer and GL account from the mapping, ensuring every transaction lands on a valid X3 dimension. If a mapping is missing, the record is held in the audit log for manual review and retry.