SAP Business One integration with your online store, through the Service Layer

What SAP Business One is and who runs it

SAP Business One is SAP's ERP for small and midsize companies: accounting, sales, purchasing, inventory, warehousing and production in one database per company. SAP positions it apart from S/4HANA, which it sells to organizations of all sizes, and implementation runs through SAP partners. It is common at wholesale distributors, importers and manufacturers, often as the system of a subsidiary inside a larger group.

It runs on your own server or at a hosting partner, on SAP HANA or on Microsoft SQL Server. Those two choices, database and version, decide which API an integration gets. A HANA installation has the Service Layer. A SQL Server installation has it from version 10.0 PL01. Below that, the DI API and the DI Server are what is left.

What connects to SAP Business One

SAP Business One is the system of record for items, stock, prices and invoices. The store owns the order and new customers. These are the flows we build as part of an e-commerce ERP integration, with the Service Layer entity each one uses:

An order goes in with its lines in one call:

POST /b1s/v2/Orders
Cookie: B1SESSION=PTRzIjYK-weN6-1Lx1; ROUTEID=.node1
Content-Type: application/json

{
  "CardCode": "C10432",
  "NumAtCard": "WEB-100482",
  "DocDueDate": "2026-10-05",
  "DocumentLines": [
    { "ItemCode": "KB-2210", "Quantity": 120,
      "UnitPrice": 9.60, "WarehouseCode": "01", "TaxCode": "CA-SF" }
  ]
}

SAP answers with two numbers: DocEntry, the internal key, and DocNum, the order number your staff see. The integration stores both next to the store order number, so a delivery or invoice created later in SAP can be traced back to the store order. The fields per flow are on orders and fulfillment.

How SAP Business One exposes data

Service Layer, DI API and DI Server

SAP Business One has three APIs on the same business objects. The Service Layer is an OData service over HTTPS on port 50000 by default: /b1s/v1 for OData version 3, /b1s/v2 for version 4, JSON in both. The DI API is built on Microsoft COM and runs only on Windows. The DI Server offers the same objects over SOAP.

We build new integrations on the Service Layer. SAP lists what it cannot do that the DI API can: direct SQL through a RecordSet, import and export of XML, and transactions that span more than one call. For reads outside the standard entities there is SQLQueries from 10.0 FP 2011: a stored query that the integration runs through the Service Layer. SAP's guide Working with SAP Business One Service Layer has the full description.

A session instead of a token

The integration logs in with POST /b1s/v2/Login, sending the company database, a user name and a password. It gets back a B1SESSION cookie with a SessionTimeout of 30 minutes, plus a ROUTEID cookie that keeps the session on the same node behind SAP's load balancer. Every later call sends both. After 30 minutes without a call the session is gone, and the next call returns 401 with "Invalid session or session already timeout". SAP calls a login a heavy job, so the integration reuses one session and logs in again only after a 401. The SAP user it logs in with is a normal user, and that user's authorizations decide what the integration can read and write.

Limits that are settings

SAP documents no request rate limit for the Service Layer. Throughput depends on your server and on these settings:

The page size decides how many calls a full read takes. Worked through for a catalog of 40,000 items: at the default of 20 that is 40,000 / 20 = 2,000 calls, each following an @odata.nextLink. With Prefer: odata.maxpagesize=1000 it is 40 calls. Special prices add to it: 300 customers with 150 special prices each are 45,000 rows, which is 45 pages of 1,000. The integration asks only for the fields the store uses with $select, and after the first full run reads only what changed since the last one. The method is in integration throughput.

Webhooks from FP 2602

From SAP Business One 10.0 FP 2602 the Service Layer sends a notification when an event happens, for example sap.b1.Orders.Created.v1. Orders have six events: created, updated, deleted, closed, cancelled and reopened. Webhooks are off per company by default and need the Webhook Messenger Service on the server.

SAP's guide gives two retry policies: the configuration table says 3 retries 2 seconds apart, its FAQ says up to 5 retries from 2 to 32 seconds. Either way the retries are over within about a minute. A receiver that is down for longer loses the notification, and SAP warns that retries can deliver the same event twice. Next to the webhooks we therefore run a check on the update date, and on versions before FP 2602 that check is the only route. See webhooks are not a guarantee.

Where an SAP Business One integration gets stuck

Special prices per customer

An item has a price per price list in ItemPrices, and a business partner points to one price list through PriceListNum. On top of that come special prices: a price or discount for one item and one customer in SpecialPrices, with periods (DateFrom, Dateto) and per period a quantity scale. SAP's training material states that a special price for a business partner overrides all other prices.

Worked through for the example in the diagram: an order of 120 units of KB-2210 for C10432 in 2026 gets the period price, 120 × $9.60 = $1,152.00. An order of 250 units hits the scale, 250 × $9.20 = $2,300.00. Most store platforms have no model for four layers with dates, so the integration resolves them into what the platform supports, such as a catalog or price list per customer and a quantity rule, and changes the store price on January 1, 2027, the day the period ends. See customer-specific pricing.

Stock per warehouse is three numbers

Per item and warehouse SAP returns InStock (in the warehouse), Committed (committed to customers) and Ordered (ordered from vendors). None of them is the number the store should show. With 20 in stock in warehouse 01, 4 committed and 10 on order, 20 - 4 = 16 can be sold; the 10 on order count once they arrive. Which warehouses count for the store is set per integration, as described in multi-location inventory.

Keys, addresses and sales tax

Sales tax is where US orders stop. The store calculates tax by ship-to address; SAP Business One expects a TaxCode on each line, a code defined in your company for the sales tax of the location where the sale takes place. The integration maps each ship-to location to its code and holds an order whose location has no code, with the address in the message, instead of posting it with the wrong tax. Address splitting is covered in address field mapping.

By default a PATCH overwrites an order even when an employee changed it a second earlier. From 10.0 FP 2102 the Service Layer returns an ETag on orders, deliveries and invoices. The integration sends it back in If-Match; when the order has changed in the meantime, SAP answers 412 Precondition Failed with error -2039, and the integration reads the new version before it tries again.

Platforms we integrate with SAP Business One

The integration is built on your installation: your version, your database, your price lists and user-defined fields. Each store platform has its own pair page:

• Shopify SAP integration: business partners against Shopify companies, special prices against catalogs, Shopify's GraphQL cost budget against SAP's session.
• Magento SAP integration: price lists and special prices against Magento's customer groups and tier prices, configurable products against SAP items.

The platform side is on Shopify, Magento and WooCommerce. For other ERPs, see Business Central and NetSuite.

We build the integration for a fixed price, then host it, monitor it and fix it when SAP or the store platform changes something, for a monthly fee. Before go-live it runs as a dry run that writes nothing: you see per order which business partner, price and lines would be created in SAP. Every integration comes with a dashboard, logs and a per-run diff. Tell us which version and database you run.