Microsoft has set the date: with Dynamics 365 Business Central 2026 Release Wave 1 (version 28, in short BC28), API v1.0 is finally removed from Business Central (Microsoft Learn, 2026). Yet this is exactly the interface that many online shops still rely on to connect to Business Central -- for syncing items, stock levels, prices and orders. API v1.0 was already marked deprecated in 2024 Release Wave 1, with removal announced for 2026 Release Wave 1 (Microsoft Learn, 2026). Anyone who lets the deadline pass risks breaking the order, item and inventory synchronization between ERP and shop. This article explains what the v1.0 deprecation means in practice for Dynamics 365 shop integrations, how the move to API v2.0 and a clean REST connector architecture works, which new 2026 connector features arrive and what a reliable migration roadmap looks like. Unlike our foundational article on the initial connection of Business Central to a shop, this piece focuses specifically on migrating existing connectors to the new API generation.
Key takeaways
- With Business Central 2026 Release Wave 1 (version 28), Microsoft removes API v1.0; the rollout starts in April 2026 (Microsoft Learn, 2026). Any call still targeting /api/v1.0/ returns no data after the update.
- Without the switch, stock levels stop updating in the shop, new orders no longer reach the ERP and price changes never arrive. Microsoft states that v2.0 carries the full functionality of v1.0, so the migration itself is feasible (Microsoft Learn, 2026).
- Migrating is more than swapping a URL: v2.0 replaces multipart and non-GUID keys with GUIDs retrieved via the immutable SystemId, flattens nested fields such as address into first-level properties and returns option fields as strongly typed enums.
- A proven setup splits the traffic: orders arrive event-driven and become a sales order at once, while items, prices and stock are pulled on a schedule as deltas using $filter on the modification timestamp. Authentication runs on OAuth2 via Microsoft Entra ID, not basic auth.
- The 2026 connector generation syncs images per product variant, uses up to three item attributes as product options and takes over the amount actually paid at checkout in foreign currency without conversion (azurecurve, 2026).
- The roadmap runs in four phases: audit every v1.0 call including internal libraries, rebuild key logic and mapping, test in a sandbox alongside production with real data volumes, and cut over in a controlled way before the BC28 update.
What the v1.0 deprecation means for shop integrations
Business Central API v1.0 established the standard way for external systems to communicate with the ERP via REST -- including e-commerce platforms, Power Platform applications, Azure Data Lake and CRM integrations (ArcherPoint, 2026). Microsoft itself describes this mechanism through so-called Connect apps that establish a point-to-point connection between Business Central and third-party solutions (Microsoft Learn, 2026). With BC28, this v1.0 endpoint disappears. For a shop integration this means: any call that still targets /api/v1.0/ will return no data after the update.
Business Central ships in two major release waves per year; 2026 Release Wave 1 rolls out from April 2026 and covers features from April through September 2026 (Microsoft Learn, 2026). In online environments updates are applied on schedule -- postponing them beyond the regular update windows is only possible to a limited extent. That is why the migration should not begin only at the deadline. Faulty data integration is among the biggest ERP challenges across industries: 62 percent (Panorama Consulting, 2025) of companies name data integration as a central problem in ERP projects, and 68 percent (DATAVERSITY, 2024) see data silos as their biggest hurdle.
What actually happens with a missed migration
API v1.0 versus API v2.0: the key differences
API v2.0 was introduced back in 2020 Release Wave 2 and is the long-term, versioned generation of the Business Central interface (Microsoft Learn, 2026). The differences from v1.0 are not cosmetic -- they affect keys, data structure and typing. Migrating therefore means more than adjusting the URL; it means reworking the mapping inside the connector.
| Aspect | API v1.0 (removed with BC28) | API v2.0 (standard) |
|---|---|---|
| Keys | Multipart and non-GUID keys on many entities | Uniform GUID keys, retrieval via SystemId |
| SystemId | Not consistently the primary key | Immutable, platform-enforced, indexed |
| Complex fields | Nested JSON objects (e.g. address) | First-level properties or navigation properties |
| Unit of measure | baseUnitOfMeasure as a complex field | unitOfMeasure as a navigation property via $expand |
| Option fields | Returned as strings | Strongly typed enums (e.g. for dropdowns) |
| Recommendation | Being removed -- stop using it | Standard for integrations |
The most consequential difference concerns the keys. In v1.0, entities such as salesOrderLines, salesInvoiceLines or defaultDimensions used multipart or non-GUID keys. In v2.0 all of these are replaced with unique GUIDs, and records can be retrieved via the SystemId -- an immutable, platform-enforced and indexed value that improves auditing and read performance (Microsoft Learn, 2026). For the connector this means: relationships that were previously built on document number plus line number must be switched to GUID references.
A second point is the complex properties. In v1.0 the address field, for example, returned a nested JSON object because the values were calculated at runtime. In v2.0 these complex properties are replaced by first-level properties (such as addressLine1, city, postalCode) or by navigation properties -- which significantly improves performance because no runtime calculation is needed anymore (Microsoft Learn, 2026). An item's unit of measure, for instance, is no longer delivered as a nested baseUnitOfMeasure but as a navigation property unitOfMeasure that is optionally included via $expand.
GET /api/v1.0/companies({id})/customers({id})
{
"number": "10000",
"displayName": "Example Ltd",
"address": {
"street": "Market Square 1",
"city": "Hanover",
"postalCode": "30159"
}
}GET /api/v2.0/companies({id})/customers({id})
{
"id": "<systemId-guid>",
"number": "10000",
"displayName": "Example Ltd",
"addressLine1": "Market Square 1",
"city": "Hanover",
"postalCode": "30159"
}Finally, option fields in v2.0 are returned as strongly typed enums rather than free strings (Microsoft Learn, 2026). This lets the connector reliably determine the allowed values, for example for dropdown displays, instead of hard-coding them. For the long-term versioning of interfaces this aspect is especially valuable, because new option values no longer immediately force code changes.
REST connector architecture: real-time and scheduled
A robust shop connector for Business Central usually combines two operating modes. Real-time synchronization reacts to events that must take effect immediately -- typically new orders from the shop that should become a sales order in the ERP right away. Scheduled synchronization runs at fixed intervals and suits data volumes that do not need to be up to the second, such as price lists or the entire item master.
In practice, a decoupling middleware between Business Central and the shop is advisable, rather than building every data flow as a rigid point-to-point connection. The middleware encapsulates OAuth2 authentication via Microsoft Entra ID, the field mapping, a queue for load spikes and monitoring in a single place. Which architecture fits in a given case depends on the system landscape -- we explore this in detail in our comparison of REST API and middleware.
Real-time: orders
New shop orders are created as a sales order in Business Central immediately via event -- with no manual re-keying and no delay in order intake.
Scheduled: master data
Items, prices and stock are reconciled at intervals. Using $filter on the modification timestamp, only changed records are loaded (delta sync).
OAuth2 instead of basic auth
Authentication via Microsoft Entra ID with short-lived tokens. The former basic authentication is no longer recommended for new integrations.
GUID-based mapping
Links between shop and ERP records run via SystemId GUIDs instead of document and line numbers -- stable across updates.
Queue and retry
A queue with retry and exponential backoff respects Business Central's API throttling and ensures that no order is lost.
Monitoring the flows
Central logging and alerting make it visible whether a sync completes -- the basis for reliable observability of the interfaces.
GET /api/v2.0/companies({id})/items
?$filter=lastModifiedDateTime gt 2026-07-03T06:00:00Z
&$select=number,displayName,unitPrice
&$orderby=lastModifiedDateTime
Authorization: Bearer <access_token>New 2026 connector features worth having
The 2026 generation of the Business Central shop connector brings not only the new API base but also functional enhancements that are tangible for online shops in day-to-day operations (azurecurve, 2026). Anyone migrating anyway can activate these features right away.
Images for product variants
Images of item variants in Business Central are synchronized with the corresponding product variants in the shop -- per variant instead of just one main image (azurecurve, 2026).
Item attributes as options
On export you can designate up to three item attributes as product options, such as color, size or material -- the basis for clean variants in the shop (azurecurve, 2026).
Checkout currency
For multi-currency scenarios, the amount paid at checkout is taken over exactly, without unnecessary currency conversion when creating the sales documents (azurecurve, 2026).
The current connector generation also builds on a shop-platform API version published in January 2026, which brings more reliable inventory updates, better handling of large product catalogs and clearer return and payout information (azurecurve, 2026). For catalogs with tens of thousands of items and many variants, the improved bulk handling in particular matters -- a point closely tied to a clean product data pipeline and PIM integration.
Use the migration as an opportunity
Risk check: how affected is your connector
Before a migration project starts, an honest inventory pays off. The following checklist helps assess the risk that the BC28 update poses to an existing shop connection.
- Do synchronization calls still target
/api/v1.0/endpoints, or run through a connector that uses v1.0 internally? - Are links between shop and ERP built on document and line numbers rather than GUID keys?
- Does the code rely on nested fields such as address or baseUnitOfMeasure from the v1.0 response structure?
- Are option fields evaluated as fixed strings that become enums in v2.0?
- Is there a test or sandbox environment in which the migration can be verified before the production update?
- Is it documented which entities (items, prices, stock, orders, customers) are synced in which direction?
The more points remain unclear, the more urgent an early analysis becomes. In our experience teams underestimate the effort of reworking the key logic, because GUID references replace the previous mapping by numbers. Doing this cleanly also prevents classic integration errors -- because manual data entry typically carries error rates around 1 percent (Conexiom, 2024), whereas integrated processes can reach order-to-cash accuracy above 99 percent (Conexiom, 2024).
The migration roadmap in four phases
A migration from API v1.0 to v2.0 can be structured into four manageable phases. What matters is that the move is completed before the BC28 update and verified in a test environment -- not only once the old interface has already been switched off.
- Audit and inventory: Identify every place where the connector uses v1.0 -- including internal libraries. Document entities, directions and intervals.
- Rework and mapping: Switch endpoints to v2.0, migrate the key logic to GUID and SystemId, move nested fields to first-level properties or $expand navigation properties, and treat option fields as enums.
- Test in parallel operation: In a sandbox, test the v2.0 synchronization against real data volumes, check delta queries and throttling, and run order, item and stock flows end to end.
- Cut over before BC28: Switch the production connector to v2.0 in a controlled way, arm the monitoring and only then schedule the BC28 update -- so synchronization stays continuously available.
As part of the migration, the idempotency and repeatability of the flows should also be checked, so that a retry after an error does not create duplicates -- a topic we cover in detail under idempotency and retry strategies. For existing connections that we maintain, we take over audit, rework and controlled cut-over as a guided project through our Dynamics 365 shop integration.
An API deprecation is rarely an emergency -- it only becomes one if you wait until the deadline. Anyone who runs the migration as a planned project keeps control over data, timelines and costs.
Sources and studies