← Acumatica integration

Finding the right entity

There is no universal list of Acumatica entities, and any document claiming to give you one is describing a version of a stock instance rather than the one you are connected to. What exists depends on:

  • the edition and licensed modules — Manufacturing entities are simply absent without a Manufacturing licence,
  • the endpoint version, which differs per instance and is not tied to the release the customer is running,
  • customizations, which a partner may have published as an entirely separate endpoint with its own entities.

So discovery is a step, not a formality.

The order that works

  1. acumatica_discover — the resolved endpoint version, whether Manufacturing answers at all, and how many entities each endpoint holds. Run it once against an unfamiliar tenant before anything else.
  2. acumatica_list_entities — the real list, read from the instance's own swagger.json. Filter it ("order", "inventory") rather than reading two hundred names.
  3. acumatica_describe_entity — fields, their types, and the entity's actions.

Guessing an entity name and getting a 404 costs the same round trip as asking, and tells you less.

Expandable fields are the usual surprise

describe_entity marks some fields expandable. Those are detail collections (Details, Operations, Materials) and linked entities (Contact, ShipToAddress). They do not come back at all unless you name them in expand.

The failure mode is quiet: you query a sales order, get a clean record, see Details missing or empty, and conclude the order has no lines. It has lines. You did not ask for them.

Expand when you are fetching one document. Do not expand a page of fifty — each expansion multiplies the work the server does per row, and you are spending a licensed concurrency slot for the whole duration.

Where custom fields hide

Fields a partner added for this customer — the margin percentage someone calculates on every order, the batch code the food-safety process needs — do not appear in swagger. The contract predates them.

They surface two ways:

  • acumatica_describe_entity with include_custom: true, which reads one live record with $adHocSchema and reports what it declares.
  • The custom parameter on a query, taking View.Field pairs, e.g. Document.UsrMarginPct.

They come back under custom in the same View.Field form, so what discovery reports is what you pass back. If a number the customer talks about daily is nowhere in the field list, this is where it is.

When the entity genuinely is not there

Then the data is probably reachable another way: a Generic Inquiry the finance team already built over it (see the inquiries guide), or the screen-based API via acumatica_request. An entity missing from the contract is not the same as data missing from the ERP.