Business Central APIs and web services for retail data: which route to use

Data & integrations · 9 min read

Every retail integration request sounds simple: "get the items and prices out," "feed sales back in," "let the report tool read yesterday's numbers." Business Central offers three different doors for that data — the REST API, OData web services, and legacy SOAP — and picking the wrong one costs weeks later, when a report breaks after an update or a new tool cannot connect at all. This guide starts from the retail job, not the protocol.

The three routes, in plain terms

Web services are how Business Central makes its functionality available to external systems. Several objects are exposed as web services by default, and more can be added as the business requires. Once a service is published it is available to authenticated users: any authorized user can see the service's metadata, but only users with sufficient Business Central permissions can read or change the actual data.

• The REST API (API pages and API queries). Microsoft's preferred route. If the API stack is enabled — and it is enabled by default in Business Central online — no extra setup is needed to make an API web service available. API pages expose records for reading and writing; API queries expose read-only, shaped result sets.
• OData web services (ODataV4). The publishing route most admins know: take a page, a query, or (since version 16.3) a codeunit, publish it from the Web Services page, and consumers query it over OData. This is also the route behind many Excel and reporting connections.
• SOAP web services. The oldest route. Support for SOAP endpoints is deprecated in Business Central and will be removed in an upcoming release, so it belongs in this guide for one reason: so existing integrations can be recognised and planned off it, not built on it.

Comparison: API vs OData vs SOAP

Every row in this table comes from Microsoft's own Business Central documentation — documented behaviour only, no benchmarks and no vendor claims.

One stability point matters for retail reporting in particular. Basing a report on a UI page exposed as OData is fragile: fields on UI pages can change between updates — by the app publisher or by an extension — and Business Central does not track report dependencies on page objects, so the change can silently break the report. API pages and queries do not carry that problem, because they are built as data contracts rather than screens. Microsoft also advises against using standard UI pages as web service endpoints at all: parts of a page such as fact boxes are not returned in web service results but still consume resources to prepare.

Which route for which retail job

Use the job to decide, in this order:

1. Recurring reporting extract (items, prices, sales history into a report tool or spreadsheet). Start with an API query or API page. If the consumer is Power BI, this is Microsoft's explicit recommendation, for both speed and stability. Reach for OData only when the consuming tool already speaks OData and cannot use the API.
2. A shaped, read-only result (several tables combined, totals pre-calculated). Publish a query. Queries are read-only on both the API and OData routes, which is a safety feature here: a reporting consumer physically cannot write back through it.
3. Record-level read and write (an external system creates or updates records). Use an API page, or a writable page published as OData when the consumer is already OData-based. Writing requires the caller to name the company — in the URI or as a query parameter; both forms point to the same endpoint.
4. An operation, not records (run a defined action). A codeunit exposed as an OData v4 unbound action is the documented route — available from version 16.3, with the caveat that no URL is shown in the interface for it.
5. An existing SOAP integration. Keep it running, but plan the move: Microsoft directs SOAP solutions to ODataV4 or API pages/queries, and SOAP support will be removed in an upcoming release. New work never starts on SOAP.

Publish a page or query as an OData web service, step by step

This is the documented publishing procedure, and the verification step at the end is the part most often skipped:

1. Open the Web Services page. In the Business Central client, search for Web Services and open the related link.
2. Choose New and set the Object Type to Page or Query for OData (Codeunit and Page are the SOAP types).
3. Select the Object ID of the object to expose. Microsoft's own example: object ID 21 exposes the customer card. In a multi-company database, an object ID specific to one company can be chosen.
4. Give it a meaningful Service Name (Microsoft's example: Customers for the customer card). The name is visible to consumers and is how services are identified and distinguished, so name it for the consumer, not the object number.
5. Select the Published check box. The OData URL and SOAP URL fields now show the generated URLs. Copy the OData URL and keep it with the integration's documentation.
6. Test it immediately. Choose the link in the OData URL field, or paste the URL into a browser, and confirm the service responds and shows the service you created. The documented online URL shape is https://api.businesscentral.dynamics.com/version/tenant/Production/ODataV4/Company('CompanyName')/entity.
7. Mind the company reference. The company name in the URL is case-sensitive. For on-premises OData URLs Microsoft recommends the Company(Id=guid) form instead, because a company ID never changes while an administrator can rename a company. If a record needs a unique, stable identifier in the feed, include the SystemId field — a GUID that is unique and immutable for each record.

What success looks like: the browser call returns the published service and its data for a user with the right permissions, the service name in the response matches the name chosen in step 4, and the same URL works for the consuming tool — not just in the browser. To retire a service later, clear its Published check box; that makes it inaccessible. One caution when unpublishing: unpublishing a service marked for All Tenants also unpublishes other services that use the same object, even though their Published boxes still appear selected.

Two page-level settings are worth knowing about for OData-published pages: Exclude Non-Editable FlowFields and Exclude Fields Outside of the Repeater. They keep those fields out of eTag calculations and can prevent problems when users edit multiple lines, for example in Excel. Both are hidden on the Web Services page by default and are shown through personalization. And if an exposed object must never be reachable from Business Central online, its methods must be marked [Scope('OnPrem')] in code — a developer task, but an admin decision.

Authentication basics: OAuth first, access keys are legacy

Authentication is where older guides mislead most. The documented position:

• OAuth is the recommended authentication method for all Business Central web service endpoints, and it is supported on both OData and SOAP endpoints. Security is managed by Microsoft Entra ID, multi-factor authentication is fully supported, it supports non-interactive (service-to-service) accounts, no license is required for service-to-service integrations, and requests carry a short-lived access token rather than a password.
• Basic authentication with web service access keys is deprecated. Since October 2022 it is deprecated and not supported in Business Central online. Where it still exists (on-premises credential types such as NavUserPassword or AccessControlService), understand its shape: the key is a random 44-character string tied to an interactive, licensed user account, generated on that user's account in the client; it never expires unless an expiration is set; and the secret travels in the HTTP request — if SOAP or OData traffic under those credential types is intercepted and decoded, the user name, password, and key can be exposed, which is why Microsoft directs those setups to SSL.
• Permissions still decide what data flows. Authentication gets a caller in the door; Business Central permissions decide what it can read or change. A reporting integration should run as an identity whose permissions match the job — read access for extracts — because every write call still checks permissions and the page's InsertAllowed, ModifyAllowed, and DeleteAllowed properties.

Writing data back: what changes

Data can be written to Business Central through an OData web service that exposes a writable page, and the same record logic applies on API pages. The documented OData operations are: POST creates a new entity, PATCH modifies an existing one, and DELETE removes one. PATCH calls require the If-Match header, set from a retrieved ETag or with *. Every write call fails if the user lacks the relevant permission or the page property (InsertAllowed, ModifyAllowed, DeleteAllowed) is set to No — so a "the integration cannot update items" error is usually a permissions or page-property answer, not a network answer. Plan write-back integrations to specify the company on every call, in the URI or as a query parameter.

FAQ

What is the difference between OData and the API? OData web services are objects you publish yourself from the Web Services page — pages, queries, and codeunits. The REST API is a separate stack of API pages and queries that needs no publishing step when the API stack is enabled, and it is the route Microsoft recommends, including for Power BI.

Is SOAP still supported? For now, but it is deprecated and will be removed in an upcoming release. Microsoft's direction is to move SOAP solutions to ODataV4 or API pages/queries.

Can a query write data back? No. Queries are read-only on both the API and OData routes. Write-back needs a writable page.

Does the report user need a full licence and a password-style key? Not under OAuth: service-to-service integrations need no license, and requests carry a short-lived token. The licensed-user, long-lived-key model is the deprecated basic authentication route.