.png)
Acumatica Integration Guide
Connect Acumatica Cloud ERP with enterprise applications through contract-based REST APIs, configured business-event callbacks, legacy SOAP services, and controlled file or OData-based workflows.
Acumatica integration options at a glance
Acumatica's primary integration mechanism is its tenant-specific, versioned contract-based REST API for reading, creating, updating, and processing business entities such as Customer, SalesOrder, Invoice, and StockItem. Configured business events and push notifications can send selected changes to a Martini REST API, while SOAP remains available for legacy requirements. OData-style Generic Inquiries and import or export facilities support reporting, extraction, and controlled batch operations. Files and attachments are available for applicable contracts. Martini can manage OAuth 2.0 credentials, call Acumatica endpoints, receive callbacks, schedule incremental synchronization, map data, and apply reconciliation and retry rules.
| Integration point | Supported by Acumatica? | Common use cases | How Martini supports it |
|---|---|---|---|
| Contract-based REST APIs | Yes | Primary integration method for listing, retrieving, creating, updating, deleting where permitted, invoking actions, and processing related details on Acumatica business entities. Common resources include Customer, SalesOrder, Invoice, StockItem, Vendor, and PurchaseOrder. | Martini can consume the tenant-specific Acumatica REST endpoint from workflows, manage versioned endpoint configuration, paginate and filter collections, map payloads, and handle responses and retries. |
| Authentication | Yes | OAuth 2.0 is the preferred method for durable REST integrations. Session-based or username/password login may be available depending on version and configuration. | Martini can store client credentials, secrets, tokens, and environment-specific endpoint settings securely, and implement token acquisition, refresh, and request authorization. |
| Webhooks / outbound callbacks | Limited | Configured Acumatica business events and push notifications can notify external systems about selected qualifying conditions; coverage is not universal for every entity or field. | Martini can expose a REST API to receive callbacks, validate and acknowledge requests, retrieve the authoritative Acumatica entity, and start follow-up workflows. |
| SOAP APIs | Legacy | SOAP web services remain relevant for existing integrations or capabilities not available through a selected REST contract, but REST is generally preferred for new work. | Martini can consume Acumatica SOAP services where legacy compatibility is required, with XML mapping, authentication configuration, and SOAP-specific error handling. |
| OData / Generic Inquiries | Limited | OData-style feeds can support read-oriented reporting, analytics, and extraction scenarios. They are not generally a replacement for transactional REST writes. | Martini can schedule retrieval, parse and transform feed data, apply checkpoints, and deliver results to databases, files, or downstream APIs. |
| Import and export facilities | Limited | Import scenarios and file-based processing support controlled migration, batch operations, and cases where an API operation is inconvenient or unavailable. | Martini can orchestrate file creation or consumption, validation, transformation, transfer, and reconciliation around Acumatica application-level processing. |
| File and attachment APIs | Limited | Applicable entities and endpoint contracts can expose files or attachments, subject to version, permissions, file-size, and contract-specific behavior. | Martini can transfer attachment metadata or binary content through controlled workflows and apply payload-size, naming, and error-handling rules. |
| Bulk, asynchronous, or batch processing | Limited | Batch behavior can be implemented through API operations, import scenarios, and application processing features, but exact availability depends on the endpoint and operation. | Martini can schedule batches, control concurrency, checkpoint progress, and reconcile partial successes without assuming a universal Acumatica bulk API. |
How Acumatica exposes data and business events
Acumatica REST APIs
Acumatica's contract-based REST API exposes versioned, tenant-specific endpoint contracts for business entities, fields, related details, and actions. Exact entity availability and behavior depend on the endpoint configuration, edition, customization, and permissions.
Martini implementation pattern
Martini workflows authenticate with OAuth 2.0 or an available session mechanism, call the configured endpoint, apply filters and pagination, map the JSON response into a canonical model, and write or route the result to downstream systems. Reusable workflows can centralize token handling, endpoint version settings, retries, and reconciliation.
Implementation sequence
Acumatica Business Events and Push Notifications
Acumatica can send notifications for configured business events and push-notification conditions. These are selected, administrator-configured callbacks rather than a universal event stream for every entity change.
Martini implementation pattern
Martini exposes a REST API to receive the callback, validates the source and payload, responds promptly, and starts a workflow that retrieves the current Acumatica entity when the notification is incomplete. The workflow then applies business rules and forwards the authoritative result.
Implementation sequence
Acumatica SOAP Web Services
Acumatica provides older screen-based and contract-based SOAP services for existing or legacy integrations. SOAP should generally be evaluated after REST for new application development.
Martini implementation pattern
Martini consumes the required SOAP operation, configures the applicable authentication and XML handling, maps request and response structures, and isolates legacy service logic in reusable workflows. SOAP errors and application validation responses are classified separately from transport failures.
Implementation sequence
Acumatica OData and Generic Inquiries
Generic Inquiries and OData-style feeds can expose read-oriented Acumatica data for reporting, analytics, and extraction where enabled. They are not generally intended to replace contract-based REST operations for transactional writes.
Martini implementation pattern
Martini schedules feed retrieval, applies an incremental checkpoint or overlap window, transforms inquiry rows, and delivers them to a database, file, analytics platform, or downstream API. The workflow records the source configuration and reconciliation status.
Implementation sequence
Acumatica Files and Attachments
Files and attachments are available for applicable entities and endpoint contracts, subject to version, permissions, file-size, and customization constraints.
Martini implementation pattern
Martini checks the entity contract before transfer, retrieves or submits attachment metadata and binary content as supported, and separates large-file handling from document-field synchronization. Failed transfers can be retried without repeating the associated business transaction.
Implementation sequence
Common Acumatica integration patterns
Pattern 1: Send commerce orders to Acumatica
When to use this pattern
Use this pattern when an online storefront must create ERP customers and sales orders while preserving external order identifiers. It supports event-driven or scheduled intake and should account for taxes, freight, discounts, payment status, warehouses, and duplicate retries.
Integration direction
Example Mapping
| Acumatica Field | Canonical Field | Target Field |
|---|---|---|
| order.id | externalOrderId | SalesOrder.ExternalReference |
| customer.email | customerEmail | Customer.Email |
| line_items[].quantity | orderedQuantity | SalesOrder.Details[].OrderQty |
| financial_status | paymentStatus | SalesOrder.PaymentStatus |
Martini implementation pattern
Martini receives or retrieves the commerce order, looks up the external customer and order key, creates or reuses the Acumatica Customer, maps the order and lines to SalesOrder, and applies branch, tax, and payment rules. A timeout is reconciled by querying the external reference before another create request; permanent validation errors are routed for review.
Martini capabilities used
- workflows
- API consumption
- data mapping
- business rules
- error handling
Pattern 2: Synchronize Acumatica invoices to a customer system
When to use this pattern
Use this pattern when a CRM, portal, or customer-facing application needs invoice balances and statuses without direct ERP access. A scheduled incremental read is appropriate when callback coverage is unavailable or incomplete.
Integration direction
Example Mapping
| Acumatica Field | Canonical Field | Target Field |
|---|---|---|
| Invoice.ReferenceNbr | invoiceNumber | Salesforce.Invoice_Number__c |
| Invoice.Customer | customerId | Salesforce.Account_External_Id__c |
| Invoice.Balance | outstandingBalance | Salesforce.Balance__c |
| Invoice.Status | invoiceStatus | Salesforce.Status__c |
Martini implementation pattern
A scheduled Martini workflow queries Invoice entities with server-side filters and pagination, maps document numbers, balances, due dates, and statuses, and upserts the downstream object using a stable external key. It stores a checkpoint, uses an overlap window where needed, and retries transient failures without reprocessing confirmed results.
Martini capabilities used
- scheduled workflows
- API consumption
- pagination
- data mapping
- checkpointing
- retry handling
Pattern 3: Publish Acumatica inventory availability
When to use this pattern
Use this pattern when commerce or planning applications need warehouse-aware StockItem quantities. The workflow should define whether the target receives on-hand, available, available-to-promise, or projected quantities and should treat the result as eventually consistent unless relevant notifications are configured.
Integration direction
Example Mapping
| Acumatica Field | Canonical Field | Target Field |
|---|---|---|
| StockItem.InventoryID | sku | BigCommerce.sku |
| StockItem.WarehouseDetails[].Warehouse | warehouseCode | BigCommerce.locationCode |
| StockItem.WarehouseDetails[].QtyOnHand | onHandQuantity | BigCommerce.inventoryLevel |
| StockItem.BaseUnit | unitOfMeasure | BigCommerce.measurementUnit |
Martini implementation pattern
Martini retrieves StockItem and warehouse data incrementally, converts units and warehouse identifiers, applies availability and negative-quantity rules, and publishes updates in controlled batches. Failures are isolated by item or batch, logged with the source key, and retried according to the error class.
Martini capabilities used
- scheduled workflows
- API consumption
- data transformation
- conditional routing
- batch processing
- monitoring
Pattern 4: Reconcile Acumatica business-event callbacks
When to use this pattern
Use this pattern when a configured Acumatica business event should initiate downstream processing for conditions such as released invoices, shipment changes, or approvals. It is useful when the callback payload is only a notification and the authoritative document must be retrieved separately.
Integration direction
Example Mapping
| Acumatica Field | Canonical Field | Target Field |
|---|---|---|
| event.entityType | sourceObjectType | workflowRoute |
| event.entityKey | sourceDocumentKey | ShipStation.orderKey |
| Shipment.Status | fulfillmentStatus | ShipStation.shipmentStatus |
| Shipment.TrackingNumber | trackingNumber | ShipStation.trackingNumber |
Martini implementation pattern
Martini validates the callback, acknowledges it promptly, retrieves the current Acumatica Shipment or related document, and routes the normalized result to the downstream application. It uses an event key or document identifier for idempotency and schedules reconciliation when the source record is temporarily unavailable.
Martini capabilities used
- exposed APIs
- webhook consumption
- workflows
- data mapping
- idempotency
- error handling
Applications commonly integrated with Acumatica
Acumatica commonly participates in commerce, CRM, tax, shipping, and service architectures. The products below represent typical integration targets or established ecosystem scenarios; exact support depends on the Acumatica edition, tenant configuration, marketplace package, and selected endpoint contracts.
| Application | Scenario | Direction | Martini Pattern |
|---|---|---|---|
| Shopify | Synchronize online orders, customers, products, inventory, fulfillments, and refunds with ERP processes. | Shopify → Martini → Acumatica | Martini receives Shopify events or polls for new orders, maps customers and line items to Acumatica Customer and SalesOrder entities, performs lookup-before-create checks, and publishes inventory or fulfillment updates back to Shopify. |
| BigCommerce | Bring storefront orders and customer information into Acumatica while returning inventory and order status to the storefront. | BigCommerce → Martini → Acumatica | A Martini workflow retrieves or receives BigCommerce transactions, transforms tax, address, payment, and line data, submits Acumatica documents, and reconciles the resulting document numbers and statuses. |
| Salesforce | Synchronize CRM accounts, contacts, opportunities, customers, orders, invoices, and fulfillment status across sales and finance processes. | Salesforce → Martini → Acumatica | Martini consumes Salesforce API data and Acumatica REST resources, applies ownership, branch, and external-ID rules, and routes validation or duplicate conflicts for review. |
| Adobe Commerce / Magento | Exchange catalog, inventory, customer, sales-order, shipment, and return data between commerce operations and the ERP. | Adobe Commerce / Magento → Martini → Acumatica | Scheduled or event-driven workflows map commerce payloads to Acumatica Customer, StockItem, and SalesOrder entities, then send Acumatica inventory and fulfillment results downstream. |
| Avalara | Request tax calculations and reconcile tax results or transaction references for taxable sales orders and invoices. | Acumatica → Martini → Avalara | Martini assembles a tax request from Acumatica document and address data, calls the tax service, validates the response, and maps tax results and references back to the appropriate Acumatica process. |
| ShipStation | Exchange fulfillment requests, shipment details, tracking numbers, and carrier status between Acumatica and shipping operations. | Acumatica → Martini → ShipStation | A workflow sends eligible Acumatica orders or shipments to ShipStation, receives tracking callbacks or scheduled updates, and writes fulfillment status back with duplicate and retry safeguards. |
| Vertex | Support tax determination and reconciliation for ERP transactions where Vertex is the selected tax platform. | Acumatica → Martini → Vertex | Martini transforms Acumatica transaction, customer, and location data into Vertex requests, handles response validation, and maps tax decisions and references into the downstream Acumatica workflow. |
How to build a Acumatica integration in Martini
Objective
Establish access to the tenant-specific Acumatica endpoint and keep environment-specific configuration separate from workflow logic.
Instructions in Martini
- Configure the Acumatica instance, tenant, endpoint name, and contract version as environment values
- Create OAuth 2.0 or approved session credentials with only the required entity and action permissions
- Store client secrets, refresh tokens, and other credentials in protected Martini secrets configuration
- Test access against the target tenant and verify branch, company, warehouse, and field permissions
Objective
Select an event-driven, scheduled, API-led, or file-based trigger based on the availability and reliability of the required Acumatica event coverage.
Instructions in Martini
- Use a Martini REST API for configured Acumatica callbacks
- Use a scheduler for incremental reads, OData extraction, inventory synchronization, or reconciliation
- Use an inbound API when another application submits orders or master data
- Use file processing for controlled imports, exports, or attachment flows
Objective
Obtain the authoritative Acumatica entity or related data while avoiding full-collection reads and incomplete event payload assumptions.
Instructions in Martini
- Apply server-side filters, field selection, expansion, and pagination where supported
- Retrieve the current Customer, SalesOrder, Invoice, StockItem, Vendor, or PurchaseOrder after a callback when needed
- Persist a modification checkpoint, status marker, or overlap-window boundary
- Validate that the entity and fields are exposed by the configured contract
Objective
Coordinate calls, lookups, transformations, target writes, and reconciliation as a maintainable Martini workflow.
Instructions in Martini
- Separate transport, mapping, business rules, and target-write stages
- Use reusable workflow logic for authentication, endpoint calls, and response classification
- Control concurrency and batch size for large synchronization jobs
- Route asynchronous or slow processing through an appropriate follow-up workflow or queue pattern
Objective
Convert Acumatica's contract-based JSON, XML, OData, or file structures into canonical and target-specific models.
Instructions in Martini
- Map stable external identifiers and document numbers
- Normalize addresses, units, currencies, dates, statuses, and warehouse identifiers
- Distinguish on-hand from available inventory and draft from released documents
- Handle custom fields only after confirming their endpoint names, types, and permissions
Objective
Preserve Acumatica validation and processing semantics while making downstream behavior explicit.
Instructions in Martini
- Check branch, company, warehouse, location, customer, and vendor relationships
- Separate document creation from actions such as approval, release, or shipment confirmation
- Use lookup-before-create and deterministic idempotency keys
- Route permanent validation, permission, and duplicate errors for operational review
Common Acumatica data objects used in integrations
| Object | Typical Use | Common target systems | Martini handling |
|---|---|---|---|
| Customer | Customer master data, contacts, billing settings, credit information, and addresses. | Shopify, BigCommerce, Salesforce, Adobe Commerce / Magento | Martini maps stable external identifiers, locations, addresses, and customer attributes; it uses lookup-before-create logic and routes validation conflicts for review. |
| SalesOrder | Sales orders, lines, pricing, quantities, shipping, discounts, tax, and status. | Shopify, BigCommerce, Salesforce, ShipStation | Martini transforms order headers and lines, validates branch and warehouse data, separates creation from processing actions, and stores the resulting Acumatica order number for reconciliation. |
| Invoice | Accounts receivable invoices, lines, taxes, payment terms, balances, and status. | Salesforce, customer portals, Avalara, Vertex | Scheduled or event-driven workflows retrieve invoices incrementally, map balances and statuses, and distinguish business validation errors from transient request failures. |
| StockItem | Inventory item descriptions, units of measure, warehouse quantities, and replenishment information. | Shopify, BigCommerce, Adobe Commerce / Magento, planning applications | Martini applies warehouse and unit conversions, uses server-side filtering and pagination, and publishes on-hand or available quantities according to the target model. |
| Vendor | Supplier master data, contacts, payment terms, and addresses. | Procurement applications, reporting platforms, databases | Martini synchronizes vendor data through the configured endpoint contract, normalizes addresses and terms, and tracks external identifiers and modification checkpoints. |
| PurchaseOrder | Purchasing documents, purchase lines, vendors, expected dates, and receipt-related information. | Procurement applications, reporting platforms, databases | Martini maps purchase headers and details, validates vendor and branch relationships, and uses idempotency and reconciliation controls for retries. |
Authentication and security considerations
Authentication and access control
Acumatica supports OAuth 2.0 for REST API access and may also support session-based authentication depending on the version and configuration. OAuth 2.0 is generally preferable for durable integrations because it avoids embedding a user password in workflows.
- Store client IDs, client secrets, refresh tokens, and session credentials in protected Martini environment configuration.
- Grant the Acumatica user or OAuth application only the endpoint, entity, field, branch, warehouse, and action permissions required by the integration.
- Use separate credentials and endpoint settings for development, test, and production tenants.
- Plan for token expiration, credential rotation, revoked applications, and permission changes.
Operational considerations for Acumatica integrations
Reliability and lifecycle considerations
Acumatica endpoint contracts are versioned and customizable, so entity fields and actions must be confirmed in the target tenant. Use filtering, pagination, controlled concurrency, and checkpoints for large collections such as Customer, StockItem, SalesOrder, and Invoice.
- Use stable external identifiers and lookup-before-create logic to make retries idempotent.
- Separate transient timeouts, rate-limit responses, and availability failures from permanent validation or permission errors.
- Use overlap windows and deduplication when modification timestamps are not sufficiently reliable.
- Test custom fields, statuses, actions, branches, warehouses, attachments, and document-processing behavior after endpoint or tenant changes.
- Treat business-event callbacks as triggers to reconcile authoritative data rather than assuming every payload is complete.
- Avoid direct database writes to Acumatica Cloud ERP because they can bypass validation, audit, workflow, and security behavior.
Why use Martini instead of scripts or point-to-point integrations?
Maintainable integration orchestration
Scripts and point-to-point integrations often duplicate authentication, pagination, mapping, retry, and reconciliation logic for each system. Martini provides a workflow-based integration layer that can consume Acumatica APIs, receive callbacks, expose controlled APIs, and coordinate downstream writes.
- Centralize endpoint configuration, OAuth handling, secrets, transformations, and reusable API logic.
- Apply business rules consistently across commerce, CRM, tax, shipping, finance, and reporting flows.
- Support scheduled, API-led, event-driven, and batch synchronization patterns in a common runtime.
- Use structured error handling, checkpoints, monitoring, and reconciliation rather than relying on ad hoc retry scripts.
- Keep Acumatica-specific mappings isolated from target-system models so endpoint versions and tenant customizations are easier to maintain.
Frequently asked questions
Acumatica is primarily integrated through its tenant-specific, versioned contract-based REST API. Configured business events and push notifications can send selected callbacks, while SOAP supports legacy integrations. OData-style Generic Inquiries, import scenarios, exports, and file or attachment operations support read-oriented, batch, and document-transfer use cases.
Yes. Martini can consume Acumatica REST APIs, receive configured business-event callbacks, consume SOAP services for legacy requirements, and orchestrate OData, file, import, export, and attachment workflows where the tenant configuration supports them.
No. A dedicated Acumatica connector is not required. Martini can use Acumatica's native REST APIs, configured callbacks, SOAP services, OData or Generic Inquiry feeds, supported import and export facilities, and authentication mechanisms.
Lonti does not charge an additional per-connector or per-vendor fee to integrate Acumatica. The integration is subject to the provisioned capacity of the Martini environment. Separate costs may apply from Acumatica, cloud infrastructure, commerce or tax platforms, and other third-party services.
Start with the contract-based REST API and the endpoint version configured in the target tenant. Use SOAP when an existing integration depends on it or a required capability is not available through the selected REST contract. OData and Generic Inquiries are better suited to read-oriented extraction than transactional writes.
Acumatica supports configured business events and push notifications for selected conditions, but not a universal event stream for every object or field. Martini can receive these callbacks through an API and then retrieve the authoritative entity; scheduled reconciliation may still be needed.
Martini can use a supported modification field, status transition, external reference, or synchronization marker with filtering and pagination. It can retain checkpoints and use an overlap window with deduplication when timestamp precision or event coverage is insufficient.
Martini maps Acumatica entities into canonical and target-specific models, applies branch, status, warehouse, and document rules, and distinguishes validation errors from transient failures. Stable external identifiers, lookup-before-create logic, checkpoints, controlled retries, and reconciliation workflows help prevent duplicate Customers, SalesOrders, Invoices, or shipments.
Related Martini documentation
Acumatica APIs
Events and Workflows
Data Processing
Security and Reliability
Connect Acumatica with your enterprise systems
Use Martini to build maintainable Acumatica integrations around REST APIs, business-event callbacks, legacy SOAP services, scheduled workflows, data mapping, and reliable error handling.