Sage X3 and SPS Commerce integration

What moves between them

Outbound documents flow from Sage X3 to SPS Commerce. Purchase order acknowledgments and invoices are read from Sage X3 on a schedule and posted to SPS Commerce, wrapped in RSX envelopes and routed to the appropriate retail trading partner. Inbound documents flow from SPS Commerce into Sage X3. Purchase orders from trading partners are polled from SPS Commerce at regular intervals (5-15 minutes) and mapped into Sage X3 as purchase orders, keeping inventory and fulfillment commitments aligned. Reference data such as trading partner identifiers and item mappings are configured during setup.

How ml-connector handles it

ml-connector maintains two separate OAuth2 credential sets: one for Sage X3 (with the customer-specific server URL) and one for SPS Commerce. For outbound documents, ml-connector polls Sage X3's purchase order acknowledgments and invoices using the updatedDate field to detect changes, wraps each document in the RSX 7.7.7 envelope required by SPS, and posts it to https://api.spscommerce.com with the correct trading partner ID. For inbound documents, ml-connector polls /fulfillment/v1/purchaseorders at SPS Commerce using cursor-based pagination, extracts the order details, and creates or updates purchase orders in Sage X3 via the REST api1 endpoint. Both sides handle token expiry: Sage X3 tokens last 5 minutes and refresh tokens are cached for 30 days; SPS tokens are JWT-based and refreshed on each 401 response. Item numbers and cost centers must be mapped between the two systems during setup so inbound orders land on valid Sage X3 products. ml-connector tracks every document in an audit trail and can replay failed posts if downstream validation fails.

A real-world example

A mid-market apparel distributor runs Sage X3 for inventory and order management and ships to Walmart, Target, and Amazon through SPS Commerce. Before the integration, the operations team received purchase orders from SPS via an SFTP drop, manually imported them into Sage X3, and exported fulfillment confirmations and invoices back to SPS after each shipment. With Sage X3 and SPS Commerce connected, purchase orders arrive automatically in Sage X3, inventory allocations are visible in real time, and fulfillment documents flow back to SPS on a schedule. The manual import-export cycle is eliminated, order-to-cash latency drops, and trading partner visibility improves.

What you can do

• •Read purchase order acknowledgments and invoices from Sage X3 and post them to SPS Commerce, wrapped in RSX 7.7.7 envelopes for each trading partner.
• •Receive purchase orders from retail trading partners via SPS Commerce and create corresponding purchase orders in Sage X3.
• •Map item numbers, costs centers, and trading partner identifiers between Sage X3 and SPS Commerce so orders land on valid dimensions.
• •Authenticate Sage X3 with OAuth2 bearer tokens against the customer-specific server URL, and handle SPS Commerce OAuth2 with separate token and API endpoints.
• •Poll both systems on a configurable schedule with cursor pagination, deduplication, and a full audit trail on every document.

Questions

How do trading partner identifiers work in SPS Commerce, and how are they mapped to Sage X3?

Trading partner IDs (retailer identifiers like Walmart, Target) are provisioned during onboarding with SPS and are not discoverable via API. ml-connector stores the mapping between SPS trading partner IDs and Sage X3 customer or supplier records, so inbound purchase orders are routed to the correct vendor master record and outbound documents are sent to the correct trading partner. The mapping is configured once during setup.

Why is the RSX 7.7.7 envelope format required, and how does ml-connector handle it?

SPS Commerce wraps all documents in RSX 7.7.7 JSON envelopes, which add trading partner context, document type, and routing metadata. Raw JSON fields cannot be posted directly to SPS. ml-connector automatically wraps outbound purchase order acknowledgments and invoices from Sage X3 in RSX envelopes with the correct document type code (855 for acknowledgments, 810 for invoices) and trading partner ID before posting.

How does the integration handle the difference between Sage X3's 5-minute token expiry and SPS Commerce's JWT tokens?

Sage X3 tokens expire in 5 minutes and refresh tokens are valid for 30 days. ml-connector caches the refresh token and reuses it until it expires, then obtains a fresh token pair. SPS Commerce uses longer-lived JWT tokens and returns 401 if a token is invalid, which triggers a refresh. ml-connector handles both patterns transparently and never lets token expiry interrupt a scheduled sync.