# Sage X3 REST API: Reading Sales Orders Through Syracuse > Source: https://netray.co/erp-help/sage-x3-rest-api-syracuse-read-sales-orders > Publisher: Netray (netray.co), AI and integration engineering for ERP and manufacturing systems. > Section: ERP Help ## 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. ## Kind how-to ## System small-erp ## Erp Sage X3 ## Module Syracuse REST / Web Services ## Query Sage X3 REST API read sales orders Syracuse ## Alternate Queries - 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 ## 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 ## Steps ### Read sales orders through the REST API **Items:** - Find 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). - Identify 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). - Create 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. - Pick 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. - Send a GET to the collection URL with basic authentication, or with the authentication method enabled on your Syracuse, and request JSON. - Add a where clause to filter, and use count to limit rows, then follow the next-page link in the response for further pages. - For one record, request it with its key in parentheses in the path rather than filtering the collection. - Check the HTTP status and the diagnoses array in the response, which carries X3 messages, before trusting the body. ## Sections ### URL pattern and a worked request **Body:** 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. **Code:** 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 Accept: application/json ### REST versus SOAP web services **Body:** 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 **Body:** 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 **Body:** 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. ## 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. ## Ai Angle 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. ## Faq ### What is the Sage X3 REST URL format? **Answer:** 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? **Answer:** 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? **Answer:** 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? **Answer:** 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. ## Search terms Sage X3 REST API, Sage X3 Syracuse API, api1 x3 erp, Sage X3 SORDER, Sage X3 web services, Sage X3 SOAP vs REST, Sage X3 integration, Sage X3 API authentication, Sage X3 JSON, Sage X3 representation --- Talk to an engineer: https://netray.co/contact?intent=erp_ai | Machine catalog: https://netray.co/agent/catalog.json