1. Home
  2. SAP integration
  3. SAP Business One integration

SAP Business One integration: four routes in, and the Service Layer is SAP's newest

SAP Business One opens four routes to other software: the Service Layer, a web API that speaks OData; the DI API, built on Microsoft COM; DI Server, which serves SOAP; and the optional integration framework (B1i). SAP calls the Service Layer its new generation of extension API, and it now sends webhooks and has sample code for AI agents.

Checked 19 November 2026

Four routes into Business One, and when each fits

Start with the route. Each one has its own rules. SAP’s Service Layer guide says the Service Layer, the DI API and DI Server are all built on the same DI core. So all three describe business records in much the same way.

Scroll the table sideways to see every column.

Route What SAP says it is Where it fits
Service Layer A web API over HTTP and OData. Version 4 lives at /b1s/v2 and version 3 at /b1s/v1. Since feature package 2405, version 4 is the primary protocol and version 3 is deprecated New links, cloud apps and AI agents
DI API Built on Microsoft COM, and fits best in a Windows setup Add-ons that run beside the Windows client
DI Server Aimed at SOAP-based data links Older links built on SOAP web services
Integration framework (B1i) An optional component for dashboards, mobile devices and links to outside services. In the cloud, each service unit needs its own copy Mobile and dashboard set-ups that already use it

The middle column is SAP’s. The right-hand column is our reading of where each route fits today. SAP calls the Service Layer its new generation of extension API, so most of this page covers it.

SAP’s SDK, which includes the UI API, lets programmers connect other applications at the database level and at the user interface level.

How the Service Layer runs and scales

The Service Layer is an application server. SAP says it runs on SUSE Linux Enterprise and on Microsoft Windows, from 10.0 PL01, and is built on the Apache HTTP web server. It installs in one of two ways:

  • Integrated mode. On the same machine as the database, to keep the setup simple.
  • Distributed mode. On separate machines, for more computing power when many requests arrive at once.

Logging in is the slow part. SAP calls a login “a heavy job” in Business One, so the Service Layer keeps each session on one node, which SAP calls sticky sessions. Your link signs in once with three values (the company database, a user and a password) and gets back a B1SESSION cookie to send with every later call. Left idle for 30 minutes, the session ends by default.

For more traffic, SAP recommends several Service Layer instances behind a load balancer. If one node fails, the next one checks the session stored in the database and logs the user back in, with no new password. For an integration, that means one login per job run, reused for every call.

What the Service Layer will not do

Every limit below comes from SAP’s own guide. Each one changes how a link is built.

  • Transactions stay inside one request. Each request, a batch included, runs in its own transaction, and no transaction can span two requests. SAP says user transactions are not supported, so there is no StartTransaction or EndTransaction as in the DI API. Inside a server-side JavaScript extension, SAP caps one transaction at 10 operations.
  • No direct SQL through a RecordSet, unlike the DI API. The DI API’s XML import and export calls are missing too.
  • New custom fields need a restart. A new user-defined field, table or object is not visible until the Service Layer restarts.
  • Old OData and XML are out. OData version 1.0 and 2.0 are not supported, and neither is XML for normal record calls.
  • Long, stateful jobs fit poorly. SAP says the Service Layer may not be a good choice for complex or distributed transactions that need the server to hold state.

Writing records without overwriting someone else’s change

The Service Layer has two kinds of update, and they behave in opposite ways. A PUT replaces the record, so any field you leave out goes back to its default. A PATCH changes only the fields you send. For a link that updates a few fields, PATCH is the safe choice.

Two people can edit the same record at once. So can a person and a link. Since 10.0 FP 2102, the Service Layer supports ETags to stop blind updates. A PATCH that carries an out-of-date ETag in its If-Match header can be rejected, so the link reads the record again instead of writing over newer data.

Several calls can travel together. The Service Layer accepts batch requests, many operations in one HTTP request to the $batch endpoint. And Business One’s approval rules still apply to software. With approvals switched on, a new sales order posted through the Service Layer is saved as a draft, and the call returns error code -2028.

Reading data: OData queries and SQL Query

An OData query reads an entity set, such as Orders or BusinessPartners. A query that spans two sets with no set link goes to $crossjoin, which SAP lists from Business One 9.2, version for SAP HANA, patch level 07. Large reads come back in pages. A request’s odata.maxpagesize setting wins over the PageSize setting in b1s.conf, and a value of 0 turns paging off.

Since 10.0 FP 2011, the Service Layer on SQL Server and SAP HANA also supports SQL Query, which uses a limited subset of SQL. SAP exposes it as the SQLQuery entity.

For data sensitivity and security reasons, not every table and column can be queried. The allowed tables sit in an allowlist file, b1s_sqltable.conf. SAP says tables outside it are not supported, and adding tables to it is outside the scope of support.

Webhooks push changes out, since FP 2602

Since 10.0 FP 2602, the Service Layer can send webhooks. A webhook tells your other system when a record is created or updated, so it does not have to keep asking.

  1. Turn them on. Each company starts with webhooks switched off. SAP’s guide turns them on with the CompanyService_UpdateAdminInfo call.
  2. Subscribe. Send a POST to the EventSubscriptions endpoint, naming the events and the address that should receive them.
  3. Receive. A new background service, the Webhook Messenger Service, runs behind the Service Layer and delivers each notification.

The messenger handles failures for you. It retries a failed notification under the retry policy you set. It checks SSL certificates and signs in to your endpoint with HMAC or OAuth. It keeps events in order within one company, but not across companies. A webhook that keeps failing is switched off, and the resume API turns it back on. By default, notifications go out in batches, and the MessageBatchLimit setting sets how many events each batch holds.

Feature package 2608 made webhooks sharper. A FilterExpr formula, a true-or-false test on event fields, can limit a subscription to one field, such as a changed business partner address. By default, a notification carries only the record’s key. BizObjProps adds top-level fields, such as DocTotal, so the receiver makes fewer calls back. Fields inside sub-objects cannot be added. The EventNotifications entity’s DeliveryDetails field shows each notification’s delivery status and errors.

AI agents reach Business One through SAP’s MCP sample code

Business One’s own AI does not do integration work. SAP says the AI in the Web client cannot read, change, create or delete Business One data, and works only from what the user supplies. Moving records between systems stays with the Service Layer and the software that calls it.

For outside AI agents, FP 2608 added support for an open-source MCP server. MCP, the Model Context Protocol, is a standard way for an AI assistant to call a system’s API. SAP publishes sample code for it.

  • Coverage. Almost all OData entities in the Service Layer become MCP tools.
  • A person approves. The server pauses before writes and sensitive reads, and asks the user to approve in the AI client.
  • Sign-in. It checks OAuth 2.0 bearer tokens for scope and audience.
  • Workflows. Tools chain documents from order to delivery to invoice, and post payments.
  • Several companies. One server can serve several Business One companies, chosen from SAP’s “System Landscape Directory”.
  • Personal data. It flags and hides personal data fields in what it reads.

SAP presents this as examples to start from, so someone still sets it up, limits what the agent may do and runs it. A custom agent that reads emailed orders and saves drafts uses the same Service Layer. See SAP AI agents and what an MCP server is.

Licenses: integration users can count

SAP’s guide treats people who reach Business One indirectly as named users. It says users of every license type can work through any number of add-ons. For a license key for a partner’s solution, SAP says indirect access rights must be in your contract. A named user’s logon limit covers the DI API, and from version 9.2 it covers indirect access licenses too.

Some parts come with user licenses, with no separate request. SAP’s list of those parts includes a B1i indirect access component for one user. A DI Server license works by the number of licensed processor cores. And the SAP Business One mobile apps for iOS and Android are included in the normal user license.

Ask SAP or your reseller, in writing, how the users of the other system will be counted before the link goes live.

Mobile apps, web shops and SAP Ariba

For mobile, SAP names B1i as the component that lets Business One work with mobile devices, and SAP’s own apps come with the user license.

This page names no Business One connector for a web shop or for SAP Ariba, because we read no SAP page that documents one. SAP’s help search loads by script and gave our fetcher no text for either, and SAP’s community site refuses our fetcher. A link of that kind would run over one of the four routes above.

Finding the Service Layer, and keeping B1i keys fresh

Add-ons need to know where the Service Layer lives. FP 2608 added a UI API method, GetServiceLayerURLs, that returns the Service Layer addresses for the connected company, on-premise or in the cloud. When several instances are registered, it returns them all, separated by commas.

B1i got key rotation in the same release. It now rotates the OAuth keys and certificates it uses to sign in. The rotation interval is set in a configuration file, and SAP recommends a yearly interval.

Plan around SAP’s dates

SAP Business One 10.0 is in mainstream maintenance until 31 December 2028, a date SAP marks as subject to change. Version 11 follows, with no date given. The Service Layer guide we read is version 1.29, dated 27 July 2026, and the newest feature package in SAP’s notes is FP 2608. A link built today on OData version 4 and the Service Layer is built on what SAP calls its main protocol.

What our team has done

Our team has taken SAP Business One live, and can run an SAP implementation end to end.

Our team’s data and cloud work covers AWS, Azure, Google Cloud and private servers.

For licenses, user rights and add-ons, see SAP Business One consulting. For other SAP products and their APIs, see SAP integration. For builds our team has finished, see our case studies.

Questions

What are SAP B1 modules?

SAP lists the areas Business One covers as accounting and financials, purchasing, inventory, sales and customer relationships, and reporting and analytics. For an integration, each area means records the Service Layer can read and write, such as orders, purchase orders, business partners and incoming payments. SAP's Service Layer reference names each one as an entity, the record type an outside system works with.

What are AddOns in SAP?

In Business One, an add-on is software that extends the product. SAP's SDK lets programmers connect other applications at the database level and the screen level. In the cloud, SAP also offers Business One Script, a light JavaScript system. One license rule applies to all of them: every user who works through an add-on not registered at SAP must hold a valid user license.

How much does SAP B1 cost?

SAP does not publish a Business One price on its product page. It asks you to request a quote. SAP's license guide says the product is licensed per named user, and it counts people who use it indirectly, through another system, as named users too. So for an integration, ask how the users of the other system are counted before you sign.

Is SAP B1 outdated?

Not by SAP's dates. Version 10.0 is in mainstream maintenance until 31 December 2028, a date SAP marks as subject to change, and SAP says version 11 follows. The interface keeps moving too. OData version 4 has been the Service Layer's main protocol since feature package 2405. Webhooks arrived in 2602, and support for an MCP server for AI agents came in 2608.

Should we use the Service Layer or the DI API?

For a new web or cloud link, the Service Layer. SAP calls it its new generation of extension API, and it speaks OData over HTTP. The DI API is built on Microsoft COM and fits a Windows setup. Both share the same core, so records look much the same. SAP lists four gaps against the DI API: no direct SQL through a RecordSet, no XML import and export, no user transactions that span calls, and new custom fields that wait for a restart.

Are SAP BTP and CPI the same?

No. SAP BTP is SAP's cloud platform: SAP says it brings together application development, data and analytics, integration, and AI in one platform. SAP's tool for links there is SAP Integration Suite. SAP says it is delivered as a cloud service. The SAP pages we read never use the name CPI, so we cannot map it from SAP's own words. For Business One, SAP's own link tool is B1i.

Sources

Every source behind a figure or a vendor fact on this page, with the day we read it.

Talk to us about your Business One link

Bring your Business One version, the system you want to connect and what should move between them. The first call is free.

Book an integration call