Acumatica REST API vs OData
When to use what? A practical guide for integration developers
I just wanted to share a few points to explain the difference between REST APIs and OData, as it might be helpful to understand how they differ and when to use each.
QUICK TAKEAWAY Use REST API when an external application needs to interact with Acumatica business entities and perform supported business operations. Use OData when the requirement is to query and extract data exposed through Generic Inquiries.
1. Understand the two approaches
REST API exposes Acumatica business entities through endpoints. Depending on the entity and supported operations, an external application can retrieve, create, update, or delete records. Entity operations use Acumatica business logic and validations applicable to the exposed entity.
OData (Open Data Protocol) provides a query interface for data exposed through Acumatica Generic Inquiries (GIs). It is designed primarily for reading structured data and supports query options such as filtering, selecting fields, sorting, and paging where supported.
2. Key differences
| Area | REST API | OData |
| Primary purpose | Business entity operations | Querying GI data |
| Create / update | Supported where entity allows | Not used for transactional writes |
| Read data | Yes | Yes |
| Data source | Exposed Acumatica entities | Published Generic Inquiries |
| Typical use | Order entry, customer updates, integrations | Reporting, dashboards, data extraction |
| Business processing | Entity operations invoke applicable business logic | Primarily read/query oriented |
3. Choose based on the requirement
Choose REST API when:
- Creating a Sales Order from an eCommerce platform.
- Creating AP Bills or updating customer/vendor records.
- Executing supported business actions that require Acumatica entity processing.
- Returning the result of a transactional operation to the calling system.
Choose OData when:
- Supplying order, customer, or inventory data to reporting tools.
- Extracting selected GI columns for an external dashboard.
- Filtering and paging through read-oriented datasets.
- Providing a purpose-built data view without retrieving an entire business document.
Example: An online store needs to submit a new order—use REST API. A dashboard needs order number, date, customer, total, and status for analysis—consider a GI exposed through OData.
4. Practical endpoint examples
REST API – retrieve Sales Orders:
GET /entity/Default/25.200.001/SalesOrder?$filter=OrderType eq 'SO'
OData – query a published Generic Inquiry:
GET /t/production/api/odata/gi/CustomerDetails?$filter=Status eq 'Active'&$top=100
Note: Replace the endpoint, tenant, endpoint version, and GI name with values configured in your Acumatica environment. Confirm supported query options for the endpoint in use.
5. Performance and API-consumption best practices
- Retrieve only the fields you need. Use $select where supported. Smaller responses reduce data transfer and parsing overhead.
- Filter at the source. Use $filter rather than downloading all rows and filtering in your integration code.
- Use pagination. Process large datasets in manageable pages. Follow the paging mechanism and continuation links provided by the endpoint; do not assume every endpoint behaves identically.
- Monitor usage and failures. Track request volume, response times, errors, retries, and overlapping scheduled jobs. Use bounded retries with backoff for transient failures.
- Test with realistic volumes. Measure response size and duration with representative data. A GI with complex joins or filters can also be expensive; OData is not automatically faster than REST.
6. Common mistakes to avoid
Using REST API for every reporting query, even when a focused GI is more suitable; expecting OData to create or update business documents; retrieving full records when only a few columns are needed; ignoring paging and repeatedly downloading unchanged data; and assuming there is one universal API request limit for every Acumatica deployment.
7. A simple decision guide
| Question | Recommended approach |
| Need to create or update an Acumatica business document? | REST API |
| Need to query GI data for reporting or analytics? | OData |
| Need both transactional processing and reporting? | Use both, each for its intended purpose. |
Final thoughts
REST API and OData are complementary—not competing—tools. Select the interface based on whether the requirement is a business transaction or a data query. Design integrations to retrieve only what they need, page through large results, avoid repeated calls, and monitor actual resource consumption. Check the capabilities and policies of the specific Acumatica version and deployment.
COMMUNITY members Which approach do you use most often—REST API, OData, or a combination? What has helped you reduce API calls and improve integration performance?
