We value your privacy

We use cookies to analyze our website traffic and improve your experience. By accepting, you agree to our use of analytics cookies. See our Privacy Policy for details.

IDoc vs API vs Events: When to Use Which in SAP S/4HANA

IDocs still run much of SAP integration, but SAP's 2026 clean core guidance points new designs to released APIs and business events. What each is good at, an ordered decision matrix, what changes by S/4HANA edition, and how to keep, wrap or replace existing IDocs.

Marek Juračka
Marek Juračka17 Nov 2026 • 13 min read

Last technically reviewed: 17/11/2026. Reviewed by Marek Juračka, CTO.

IDoc vs API vs Events: When to Use Which in SAP S/4HANA


Table of contents



Most SAP S/4HANA programmes have the same argument sooner or later. The interface team wants to keep the IDocs that have moved orders and master data reliably for years, the architects want released APIs, and someone else wants every change published as a business event. IDoc vs API is rarely about which technology is better; it is about which one fits a specific interface, in a specific S/4HANA edition, at a specific point in a modernisation programme.

The question is sharper in 2026. SAP now publishes a clean core classification for integration technologies, a white paper that names IDoc replacement among its main modernisation recommendations, and Migration Assessment recommendations that suggest APIs and events for existing IDoc interfaces. None of this makes IDocs unsupported, but it changes the default for new designs.

This article compares the three, sets out an ordered decision matrix, summarises SAP's position on IDocs in a clean core world, and describes how to modernise existing IDoc interfaces without rewriting everything at once.

In short

  • Use a released API when the caller needs an answer or works on one object, a business event when several systems react to a change, and an IDoc where a stable asynchronous document flow, partner EDI or an ECC core makes it the pragmatic choice.

  • IDocs remain supported in SAP S/4HANA, but SAP's 2026 clean core guidance recommends released APIs and events for new designs, and in Public Edition IDocs are available only over SOAP within predefined communication scenarios.

  • Existing IDoc interfaces are a portfolio to classify (keep, wrap, replace), and a PI/PO migration or S/4HANA conversion is the natural moment to decide.

IDoc, API and events in one paragraph

An IDoc is an SAP document format for asynchronous message exchange: one system sends a complete business document, such as an order or a material master, and the receiver processes it later. A released API (OData or SOAP) is a documented, SAP-supported interface that another system calls to read, create or change data, usually synchronously. A business event is a notification that something happened in SAP S/4HANA, such as a business partner change, published to a broker so that any number of subscribers can react.

They answer different questions. An API answers "do this, or tell me this, now". An IDoc delivers "here is the full document, process it when you can". An event says "this changed, whoever cares can react". Many designs combine an event with an API call, and many estates will run IDocs alongside both for years.

What is each good at?

IDocs carry complete documents asynchronously, APIs serve synchronous or object-level operations, and events decouple a change from the systems that react to it. The table compares them on the dimensions that usually decide a design.

Dimension

IDoc

Released API (OData, SOAP)

Business event

Nature

Asynchronous business document in an SAP-defined format

Contract for reading or changing business objects

Notification that a business object changed

Interaction

One-way message, processed later by the receiver

OData usually request and response; SOAP also supports asynchronous delivery

Publish and subscribe through a broker

Consumers

Receivers configured in SAP; each new receiver means more configuration in SAP or routing in middleware

Any authorised caller

Any number of subscribers without changing the publisher

Payload

Full document, often large and segment-based

Defined by the API; single objects or bulk, depending on the service

SAP standard events are typically small notifications, often just the object key

Reliability

Status records per IDoc; duplicate detection in the backend when sent with the IDoc content type and a stable message ID

Caller handles errors and retries; writes need idempotency

Queues hold events until consumed; consumers must handle duplicates and ordering

Standards

SAP-proprietary format

Open standards (HTTP, OData, SOAP)

Broker protocols such as AMQP, MQTT or HTTP

Where it fits best

Stable asynchronous flows, partner EDI, ECC cores, existing investment

Availability checks, create and update, lookups, enrichment after an event

Change notification to several systems, decoupled processes

IDoc strengths that are easy to underestimate

An IDoc carries control, data and status records, so every document has a traceable processing history inside SAP. Over SOAP, the IDoc runtime in the backend can detect and discard duplicate messages when the IDoc content type is used and the message ID stays the same across retries, as SAP documents for Cloud Integration's IDoc receiver. That is reliability an API-based replacement has to rebuild, not inherit.

API strengths

Released APIs are documented on the SAP Business Accelerator Hub, versioned and maintained by SAP across upgrades. SAP's clean core integration white paper suggests SOAP for bulk loads, complex objects and asynchronous delivery, and OData or REST for single-object handling and operations by resource ID. Exposing them through SAP API Management adds security policies, throttling and a catalogue for consumers.

Event strengths

Events remove the publisher's knowledge of its consumers: a new system that cares about a business partner change adds a subscription, not another outbound interface. The cost is that a notification event rarely carries enough data, so consumers usually call an API for the current state. The broker choice and its limits are covered in our SAP Event Mesh guide.

Decision matrix: which one for a given interface?

Ask a short sequence of questions in order, because early answers rule out options for later ones. This is IGT's working method, not an SAP standard; it fits the requirement-first approach of SAP's Integration Solution Advisory Methodology and our SAP integration patterns guide.

Six-question decision path for choosing between IDoc, released API and business event in SAP S/4HANA, from standard content availability to existing IDoc interfaces.

Question (in this order)

If yes

If no

1. Is there a standard SAP integration scenario, released API or business event that covers the requirement?

Use it; the remaining questions only decide how to consume it

Continue, and record the gap

2. Does the caller need an answer before it can continue?

Released API, called synchronously

Asynchronous: IDoc, asynchronous SOAP or event

3. Do several systems need to react to the same change, now or likely later?

Business event, with an API for detail where needed

One receiver: a queued message or IDoc is often simpler

4. Is the payload a large document or a bulk data set?

IDoc or asynchronous SOAP for documents; data integration tooling for bulk replication

Event plus API, or a direct API call

5. Is the counterpart an external partner exchanging EDI documents?

IDoc mapped to EDI in the integration layer remains a reasonable choice

Prefer APIs or events for application-to-application flows

6. Does a working IDoc interface already exist, with no planned change?

Keep it, document it and flag it for later modernisation

Design the new interface on APIs or events

Two non-functional factors can override the table. Latency: IDoc output can be passed on immediately or collected and sent by a scheduled job, depending on configuration, so check how outbound processing is set up before assuming any of the three is "real time". Edition: in S/4HANA Cloud Public Edition, the question is not only whether an IDoc fits but whether one is offered at all for the scenario.

An example: a warehouse system needs every released delivery. If it is the only consumer and the document is large, an outbound IDoc is defensible. If transport management and a customer portal want the same change, an event plus an API lookup scales better: each new consumer becomes a subscription, not another outbound interface in the core.

Is IDoc still supported in SAP S/4HANA?

Yes, but the support differs by edition, and SAP's direction for new designs is released APIs and events. The practical position as SAP documents it in November 2026:

  • SAP S/4HANA (on-premise). IDoc and ALE remain part of the product. SAP's documentation for the 2025 release, updated in October 2026, still documents IDocs in its Library of ALE Business Processes.

  • SAP S/4HANA Cloud Private Edition. SAP documents IDoc and ALE configuration for Private Edition as well (SAP Best Practices: SAP S/4HANA Cloud Private Edition Configuration (Sender System)). SAP frames its clean core integration guidance around the journey to Private Edition and, ultimately, Public Edition, so this is where the move to APIs and events is usually planned.

  • SAP S/4HANA Cloud Public Edition. IDocs are part of predefined communication scenarios and, in SAP's words, "only supported via SOAP" rather than classic RFC or plain HTTP (SAP Help Portal: BAPIs/IDocs in SAP S/4HANA Cloud Public Edition). Check that list, which covers inbound IDocs, and the communication scenario documentation for outbound IDocs before assuming an IDoc you use on-premise is available.

  • SAP ECC. IDocs are often the main asynchronous option. Custom events on ECC are possible through SAP Application Interface Framework, as covered in our clean core integration article.

In SAP Integration Suite, Cloud Integration has a native IDoc adapter that exchanges IDocs with systems supporting SOAP web services. For teams coming from SAP PI/PO, where RFC-based IDoc communication was common, this means the backend sends and receives IDocs over SOAP. Our PI/PO vs Integration Suite comparison covers the other adapter differences.

IDoc in a clean core world

SAP's 2026 guidance does not ban IDocs; it treats them as a traditional interface to use where no modern alternative exists and to plan away from over time. "IDocs are not clean core" and "IDocs are fine" are both oversimplifications.

What SAP's 2026 sources say

SAP Note 3690029, published in 2026, rates integration technologies on an A–D clean core scale using two criteria: support in SAP S/4HANA Cloud Public Edition, and alignment with modern standards such as event-driven architecture and API-managed integration. Our clean core article explains the levels. The rating for each technology, IDoc included, sits in the note itself, so look it up there and record it in the interface design rather than relying on summaries.

SAP's clean core integration white paper (July 2026) is more direct about IDocs. Among its typical "get clean" recommendations:

  • Replace IDocs with SOAP or OData APIs or business events, listed alongside replacing RFCs and BAPIs with APIs and custom interfaces with SAP pre-delivered content.

  • IDoc to business event where message size and complexity should be minimised.

  • IDoc to API-managed protocols (SOAP, OData, REST), because IDoc is a proprietary protocol that SAP describes as legacy technology in cloud-native architectures.

The same paper is pragmatic about the present. Where no modern alternative exists and a traditional interface has not been deprecated, SAP says temporary use may be acceptable, provided the interface is documented, owned and identified as a modernisation candidate. SAP's own example of an IDoc modernisation also notes that IDocs still make sense in some scenarios, especially EDI with external partners (SAP Community: IDoc to events and APIs).

Integration rating and extension are separate questions

Choosing IDoc as the technology is an integration question for SAP Note 3690029. Adding custom segments and user exits to fill them is an extensibility question for SAP Note 3578329. A standard IDoc and a heavily extended one are not the same risk, even though both appear as "IDoc interfaces" in an inventory.

Modernising existing IDoc interfaces: keep, wrap or replace

Treat existing IDoc interfaces as a portfolio and give each a disposition, rather than rewriting all of them or none. The table is IGT's framework; the target technologies follow SAP's recommendations above.

Six dispositions for existing IDoc interfaces: keep, keep and move logic out, wrap, replace with a released API, replace with an event plus API, and retire.

Disposition

When it fits

What changes

Keep

Standard IDoc, stable, no released alternative, or partner EDI that works

Nothing technical; document the interface, its owner and its clean core rating, and review it at the next major change

Keep, move logic out

Standard IDoc wrapped in receiver-specific ABAP: custom segments, user exits, code-list translation

Mapping, enrichment and routing move to the integration layer; the core sends the standard IDoc

Wrap

Consumers want an API, but the backend scenario is IDoc-based and cannot change yet

The integration layer exposes a governed API or publishes an event and converts to or from the IDoc behind it; a transitional step, not an end state

Replace with released API

A released SOAP or OData API covers the function, or the consumer needs a synchronous answer

IDoc configuration retired; error handling and idempotency designed in the consumer or the integration layer

Replace with event plus API

Change notification to several consumers, such as business partner changes

The core publishes a standard event; consumers fetch current state through a released API

Retire

No traffic, no owner or the receiving system has gone

Partner profiles, distribution model entries and custom code removed

What a replacement has to rebuild

Replacing an IDoc changes more than the format. Four things often get lost in the first design:

  • Monitoring. Support teams often know how to find and reprocess a failed IDoc. The replacement needs an equivalent place where failed messages are visible and can be resubmitted.

  • Duplicate handling. The IDoc backend can discard duplicates under the conditions described above. An API call that is retried after a timeout cannot, unless the receiver checks a business key.

  • Ordering. Events and asynchronous calls can arrive out of order. A consumer that calls an API for current state after each event limits the damage, but writes still need to be safe when applied twice.

  • Volume behaviour. One IDoc carrying many items should not become hundreds of synchronous calls. Where the payload is a document or a batch, asynchronous SOAP or a bulk-capable API is closer to the original pattern.

Using the PI/PO migration as the decision point

A PI/PO migration forces every IDoc interface through design and testing anyway, which makes it the natural moment to decide each disposition. Migration Assessment has included clean core modernisation recommendations for IDoc scenarios since Q2 2025, suggesting released APIs and events that could cover the same functional requirement. SAP itself notes that choosing the right one is a combined architectural and functional decision; a suggestion in the report is a starting point, not a design.

Rewriting every IDoc during the migration, however, adds functional testing, business sign-off and risk to a programme with a deadline. A common sequence is to migrate stable IDoc interfaces through the IDoc adapter and modernise those that are changing anyway or serve several consumers. Our SAP PI/PO migration guide covers the strategy, and PI/PO to Cloud Integration migration covers the step-by-step transfer.

Heterogeneous landscapes

The decision does not depend on SAP Integration Suite. In IGT's SAP ECC and MES project for a manufacturer with five factories, webMethods Integration Server consumed SAP IDocs, transformed them into a canonical XML model and routed them to each plant's MES by configuration, which kept plant-specific logic out of the ERP. The keep, wrap or replace logic applies whichever platform runs the integration layer; see SAP MES integration for the manufacturing view.

Conclusion

IDoc vs API vs events is not a contest with one winner. Released APIs fit synchronous and object-level work, business events fit change notification to several consumers, and IDocs still fit stable asynchronous document flows, partner EDI and ECC cores. SAP's 2026 guidance sets the default for new designs firmly on APIs and events, while accepting documented, owned IDoc interfaces where no modern alternative exists yet.

The practical work is classification: know which IDoc interfaces you run, what they depend on and which are about to change. Modernise those first, document the rest, and revisit them as SAP publishes new APIs and events.

If you are planning an S/4HANA programme or a PI/PO migration and need to decide what happens to your IDoc interfaces, talk to our SAP integration team or see our SAP integration services.

Related questions

Is IDoc still supported in S/4HANA?

Yes. IDoc and ALE remain part of SAP S/4HANA on-premise and are documented for Private Edition. In SAP S/4HANA Cloud Public Edition, IDocs are available within predefined communication scenarios and only over SOAP, so check SAP's list for each scenario.

Should I replace IDocs with APIs?

Not all at once. SAP's clean core guidance recommends released APIs or business events for new designs and lists IDoc replacement as a modernisation goal, but it accepts documented use where no alternative exists. Replace interfaces that are changing, serve several consumers or need synchronous answers, and keep stable ones until a natural trigger such as a PI/PO migration.

When are business events better than APIs?

When several systems need to react to the same change and the publisher should not know about them. An API is better when the caller needs an answer before it can continue. Many designs combine both: the event announces the change and consumers call a released API for the current state.

Can IDocs be used with SAP Integration Suite?

Yes. Cloud Integration has an IDoc sender and receiver adapter that exchanges IDocs with systems over SOAP web services. Teams moving from SAP PI/PO should plan for that change if their existing IDoc communication runs over RFC.

Sources

SAP Best Practices: SAP S/4HANA Cloud Private Edition Configuration (Sender System)

SAP: Clean core integration (white paper, July 2026)

SAP Community: Introducing the Clean Core Integration White Paper

SAP Community: Introducing SAP Note 3690029, Integration Technologies and Frameworks in the Context of Clean Core

SAP Community: Modernizing for a Clean Core: IDoc to Events and APIs in SAP PI/PO to Integration Suite Migration

SAP Help Portal: BAPIs/IDocs in SAP S/4HANA Cloud Public Edition

SAP Help Portal: IDoc (Library of ALE Business Processes, SAP S/4HANA)

SAP Help Portal: IDoc Adapter (SAP Integration Suite)

SAP Help Portal: IDoc Receiver Handles Duplicates


Let’s make it click!

Whether you're scaling a startup or streamlining a corporate ecosystem, we help teams launch faster and integrate smarter.

Eva Polcíková

Eva Polcíková

Project Manager

Book a call
Funded by the European Union – NextGenerationEU
Recovery and Resilience Plan of the Slovak Republic

2026 IGT Systems. All rights reserved. Designed by pomasle.studio

TermsPrivacyCookies