Sage X3 REST API: Reading Sales Orders Through Syracuse
Sage X3 REST API read sales orders Syracuse
Also searched as
- Sage X3 api1 x3 erp endpoint SORDER
- Sage X3 REST vs SOAP web services
- Sage X3 REST API authentication basic OAuth
- Sage X3 API $query where filter
Short answer
Sage X3 (version 7 and later) exposes data through Syracuse at a URL of the form /api1/x3/erp/ENDPOINT/REPRESENTATION, where the endpoint is the folder and the representation is a published object such as SORDER. A GET with credentials returns JSON, and you filter with a where clause and page with count and a link to the next page. Your integration user needs the right Syracuse and X3 rights for that representation.
Applies to: Sage X3 version 7, 9, 11 and 12 with Syracuse web server; representation names and available fields depend on the folder, the patch level and the publication in your solution
Read sales orders through the REST API
- 1Find the Syracuse base URL and port used by your site (a default port of 8124 is common on standard installs; your administrator may have changed it or put a proxy in front).
- 2Identify the endpoint name: the X3 folder as published in Syracuse administration (for example the folder name used in your solution, such as SEED for the sample folder).
- 3Create a dedicated integration user in Syracuse linked to an X3 user with only the rights needed to read sales orders. Do not reuse a person's account.
- 4Pick the representation. SORDER is the sales order representation in the standard solution; custom folders may use different ones, so check Syracuse, Administration, endpoints and published representations.
- 5Send a GET to the collection URL with basic authentication, or with the authentication method enabled on your Syracuse, and request JSON.
- 6Add a where clause to filter, and use count to limit rows, then follow the next-page link in the response for further pages.
- 7For one record, request it with its key in parentheses in the path rather than filtering the collection.
- 8Check the HTTP status and the diagnoses array in the response, which carries X3 messages, before trusting the body.
URL pattern and a worked request
The collection URL combines the Syracuse host and port, the fixed api1/x3/erp segment, the endpoint (the folder), and the representation name. The same pattern applies to other representations such as customers (BPCUSTOMER), products (ITMMASTER) and purchase orders (PORDER) when published, but verify the exact names in your own solution.
A where clause uses X3 field names and a small expression syntax. String values are quoted, and the whole where parameter must be URL-encoded. Combine conditions with and, and use the order-by parameter to control sorting so paging is stable. Responses are JSON with a resources array and URL links for paging.
GET http://syracuse-host:8124/api1/x3/erp/SEED/SORDER?representation=SORDER.$query&count=20&where=(SALFCY eq 'FR011' and ORDDAT ge '2026-01-01') Authorization: Basic <base64 user:password> Accept: application/json
REST versus SOAP web services
X3 has two integration styles. Classic SOAP web services are published from the X3 runtime and call subprograms and objects; they have long been used for create and update, and support very precise control over objects such as sales orders with a defined set of fields. REST through Syracuse is lighter, easier from modern tools, and good for reading, and for create and update where the representation allows it.
Pick REST when the consumer is a web app, Power Automate, a mobile client or a data pipeline that speaks JSON. Pick SOAP when an existing integration already uses it, or when a particular object method is only exposed there. Many sites use both. Treat the REST representation as the contract: only fields in the representation are returned, so a missing field often needs a representation change, not a different URL.
Authentication, rights and the common errors
A 401 means authentication failed at Syracuse: a wrong password, a user not enabled for the method, or a user locked out. A 403 or an empty collection usually means rights: the user is authenticated but cannot read that representation, endpoint or site. A 404 usually points to a wrong endpoint name, an unpublished representation, or a wrong case in the URL.
If the call succeeds but returns an error in the diagnoses array, the X3 runtime rejected it, for instance because the runtime service is down or the folder is under maintenance. Check the Syracuse log and the X3 runtime connectivity before debugging the query. For production, put TLS in front, do not send basic credentials over plain http, and rotate the integration password on a schedule.
Paging, volume and write-back
Do not request unbounded collections. Use count and follow the next link, or filter by date or status so each call returns a modest number of orders. For nightly extracts, filter on a changed-date field if your representation exposes one rather than rereading all orders.
For writes, test in a non-production folder first. Create and update calls run X3 validation, and failures return diagnoses text you should log. Sales orders have dependencies on customer, site, pricing and stock settings, so a payload that works in one folder can fail in another.
Common pitfalls
- !Using a personal login as the integration account, which breaks when the person leaves or changes password.
- !Sending basic credentials over plain http outside a test network.
- !Assuming representation and endpoint names from the sample folder match your production folder.
- !Requesting all orders without count or a filter, which is slow and can time out.
- !Skipping the diagnoses array and treating any HTTP 200 as success.
- !Forgetting URL-encoding on the where clause, leading to parse errors that look like server faults.
How an ERP-grounded AI assistant handles this
A grounded assistant for Sage X3 (ERPray with an X3 connector, or a custom build) can use the same read path: it is given a read-only integration user, translates a question such as open orders for a customer into a filtered query, shows the request it ran, and respects X3 rights. Netray does not need to write back for most questions; where a write is wanted, it is staged for human approval.
Frequently asked questions
What is the Sage X3 REST URL format?
It is the Syracuse host and port, then api1/x3/erp, then the endpoint (folder), then the representation, such as SORDER for sales orders. Add query parameters such as where and count. Confirm the endpoint and representation names in your own Syracuse setup.
Why do I get 401 from the Sage X3 REST API?
Syracuse rejected the credentials. Check the user and password, that the user is active, and that the authentication method you use is enabled on your installation. A 403 or empty result usually indicates missing rights instead.
Should I use REST or SOAP web services for X3?
REST is simpler for JSON clients and reading data. SOAP web services remain common for existing integrations and for object methods exposed only there. Many projects use both, chosen per task.
How do I filter or page results?
Use a where parameter with X3 field names and a count parameter to limit rows, then follow the next-page link returned in the response. Order the results explicitly so paging is stable between calls.
Related
Sage X3 Syracuse Service Won't Start: Troubleshooting Guide
When Sage X3 users reach no login page, check the Syracuse Windows service and its dependencies in order: the MongoDB service that holds Syracuse configuration, the port and certificate Syracuse binds to, then the connection from Syracuse to the X3 runtime. Syracuse log files normally state which step failed, so read the log before restarting things repeatedly.
How-toHow to Run a Physical Inventory Count in Sage X3
Sage X3 physical counts run through Stock > Counts: create a count session scoped to a site, category, or zone, generate the count sheet to freeze theoretical quantities, enter counted quantities, review the variance report, then validate to post stock and valuation adjustments. Blocking movements against the counted locations during the window keeps the variance meaningful.
How-toSage 100 Business Object Interface (BOI): Working VBScript Example
The Sage 100 Business Object Interface exposes the same business objects the screens use through a COM object called ProvideX.Script. You initialise it with the MAS90\Home path, create an SY_Session object, log on, set the company, then create a business object such as AR_Customer_bus and read or write through it. Because it runs the real business logic, it is the supported way to write data in code, unlike direct file or ODBC writes.
Error fixFix Sage 100 SOTAMAS90 ODBC Connection Errors
Most Sage 100 ODBC failures are one of four things: the DSN was created in the wrong 32-bit or 64-bit ODBC administrator for the tool you use, the DSN path or company code is wrong, the Windows account cannot read the MAS90 folder, or the Sage 100 user lacks external access. Recreate the DSN in the matching administrator and test with the driver's own Test button before blaming Excel or Power BI.
How-toHow to Create a Generic Inquiry in Acumatica
Generic Inquiries (GI) are Acumatica's no-code query builder for joining tables, adding filters, and exposing the result as an inquiry screen, dashboard data source, or API endpoint. Open System > Customization > Generic Inquiry, add your base table, define joins and conditions, then run and save. No SQL or customization project is required.
Error fixFix Odoo AccessError: You Are Not Allowed to Access Records
Odoo raises AccessError when a user's security groups do not grant a CRUD right on a model through ir.model.access.csv, or when an ir.rule record rule filters the specific record out for that user or company. Fix it by adding the user to the group named in the error, editing the model's access rights, or reviewing the record rule's domain under Settings > Technical > Security.
AI for ERPAI for Sage X3, Grounded in Your Own Ledgers and Stock Data
Add AI to Sage X3 finance and stock data without exporting it to a public model. On-prem and private-cloud LLMs for Sage X3 in the UK and France.
Stuck on Sage X3?
Talk to engineers who work inside Sage X3 every week, and who build private AI that answers these questions from your own ERP data.