---

name: sap-s4hana-sales description: > SAP S/4HANA On-Premise Sales API integration guide covering ~119 APIs across OData V2, OData V4, and SOAP protocols. Use when building integrations with SAP S/4HANA Sales — including sales orders, sales quotations, sales contracts, scheduling agreements, billing documents, customer returns, credit/debit memo requests, leads, opportunities, appointments, phone calls, tasks, pricing condition records, customer materials, and solution quotations. Triggers on: "SAP", "S/4HANA", "S4HANA", "OData", "SOAP A2A", "sales order", "sales quotation", "billing document", "customer return", "credit memo", "debit memo", "lead API", "opportunity API", "pricing condition", "scheduling agreement", "sales contract", "deep insert", "SAP API", "SAP integration", "API_SalesOrder", "API_LEAD", "API_OPPORTUNITY", "API_BILLING_DOCUMENT_SRV".

SAP S/4HANA Sales APIs

Source: SAP Help Portal — APIs for Sales Version: SAP S/4HANA 2025 FPS01 (Feb 2026)

Protocol Quick Reference

Protocol	Version	Communication	Use Case
OData	V2	Synchronous	Standard CRUD, real-time integration
OData	V4	Synchronous + Async	Next-gen APIs (RAP), lightweight JSON, deep insert with full response
SOAP	—	Asynchronous	Bulk processing, A2A/B2B integration, reliable messaging

Communication Types

Type	Protocol	Execution	Use Case
A2X	OData	Synchronous	Connect SAP with external systems via HTTP
A2A	SOAP	Asynchronous	Internal system-to-system. Monitor via AIF (/AIF/ERR) or SRT_MONI
B2B	SOAP	Asynchronous	Cross-company/external landscape connectivity

OData V2 vs V4

Feature	OData V2	OData V4
Response format	XML/JSON	Lightweight JSON
Async mode	No	Yes (prefer: respond-async)
Minimal response	No	Yes (prefer: return=minimal)
Deep insert response	Key only	Full entity tree
Subentity filtering	Limited	Supported
Pricing in response	Limited	Complete (incl. subtotals)
ETag	Varies	Consistent (If-Match header)
Architecture	Classic SAP Gateway	RAP (ABAP RESTful Application Programming Model)

Only 3 APIs have V4 versions: Sales Order, Sales Contract, Customer Return. Prefer V4 when available.

API Selection Guide

By Task

Task	API	Protocol	Reference File
Create/manage sales orders	API_SalesOrder (V4)	OData V4	order-contract-management.md
Bulk create sales orders	SalesOrderBulkRequest_In	SOAP A2A	order-contract-management.md
Simulate sales order (pricing/ATP/credit)	API_SALES_ORDER_SIMULATION_SRV	OData	order-contract-management.md
Create/manage sales quotations	API_SALES_QUOTATION_SRV	OData	order-contract-management.md
Create/manage sales contracts	API_SalesContract (V4)	OData V4	order-contract-management.md
Manage scheduling agreements	API_SALES_SCHEDULING_AGREEMENT	OData	order-contract-management.md
Read/cancel billing documents	API_BILLING_DOCUMENT_SRV	OData	billing.md
Create billing documents	SOAP A2A	SOAP	billing.md
Create/manage customer returns	API_CUSTOMER_RETURN_SRV (V2)	OData V2	returns-and-claims.md
Create credit memo requests	API_CREDIT_MEMO_REQUEST_SRV	OData	returns-and-claims.md
Manage leads	API_LEAD	OData	sales-force-support.md
Manage opportunities	API_OPPORTUNITY	OData	sales-force-support.md
Manage pricing conditions	API_SLSPRICINGCONDITIONRECORD_SRV	OData	pricing-and-master-data.md
Manage customer materials	API_CUSTOMER_MATERIAL_SRV	OData	pricing-and-master-data.md
Solution quotations	OData A2X	OData	solution-business-and-index.md

By Protocol Choice

• Real-time CRUD on single documents → OData (V4 preferred if available)
• Bulk/batch processing → SOAP A2A
• Cross-company B2B → SOAP B2B
• Simulation (no save) → OData Simulation APIs
• Read-only master data → OData A2X (Read)

Authentication

Method	OData V2	OData V4	SOAP
Basic (User ID/Password)	Yes	Yes	Yes (Username Token)
X.509 Certificate	—	Yes	Yes (X509 Token)
OAuth 2.0	—	Yes	—

Common Authorization Objects

Object	Description
S_SERVICE	Check at Start of External Services (required by all APIs)
V_VBAK_AAT	Sales Document: Authorization for Sales Document Types
V_VBAK_VKO	Sales Document: Authorization for Sales Areas
V_VBAK_APM	Sales Document: Approval Management
V_VBRK_FKA	Billing: Authorization for Billing Types
V_VBRK_VKO	Billing: Authorization for Sales Organizations
V_KONH_VKO	Condition: Authorization for Sales Organizations
/AIF/PROC	AIF Interface Processing (SOAP A2A APIs)

Common Implementation Patterns

Service Activation

OData APIs: Activate via transaction for maintaining services on SAP Gateway hub system.

SOAP A2A APIs: ICF service is inactive by default. Activate via SICF: Select service → Menu Service/Host → Activate.

Deep Insert (Required by Most Sales APIs)

POST /sap/opu/odata/SAP/<SERVICE>/<HeaderEntity>
Content-Type: application/json

{
  "HeaderField1": "value",
  "to_Item": [
    {
      "ItemField1": "value",
      "to_Partner": [...]
    }
  ],
  "to_Partner": [...],
  "to_PricingElement": [...],
  "to_Text": [...]
}

$batch Request Pattern

POST /sap/opu/odata/SAP/<SERVICE>/$batch
Content-Type: multipart/mixed; boundary=batch

--batch
Content-Type: multipart/mixed; boundary=changeset

--changeset
Content-Type: application/http
Content-Transfer-Encoding: binary

<individual request>
--changeset--
--batch--

Universal constraint: No multiple documents in a single changeset.

ETag Handling (Optimistic Concurrency)

OData V4 (Sales Order, Sales Contract): If-Match header required for all change operations. ETag = LastChangeDateTime.

OData V2 (Customer Return): GET → retrieve LastChangeDateTime → $batch changeset with MERGE (If-Match) as first op, then payload.

Pricing APIs: ETag in every entity; retrieve via GET, include in If-Match.

Async Mode (OData V4 Only)

Set prefer: respond-async header. Response returns 202 Accepted with location header containing a polling URL.

Error Monitoring

Protocol	Tool	Transaction
OData	SAP Gateway Error Log	—
SOAP A2A	SAP Application Interface Framework (AIF)	/AIF/ERR
SOAP A2A	SOAP Monitoring	SRT_MONI

BAdI Integration Points

Available for Sales Orders, Customer Returns, Scheduling Agreements, Credit/Debit Memos:

• Sales Document Check Before Save BAdI — Cancel without saving on error
• Sales Header Check BAdI — Continue and save
• Sales Item Check BAdI — Continue and save

Reference Files

Read the relevant reference file when working with a specific API domain:

File	When to Read
sales-force-support.md	Working with Lead, Opportunity, Appointment, Phone Call, or Task APIs
order-contract-management.md	Working with Sales Orders, Quotations, Contracts, or Scheduling Agreements
pricing-and-master-data.md	Working with Pricing Condition Records, Customer Materials, or Sales Org master data
billing.md	Working with Billing Documents or Billing Requests
returns-and-claims.md	Working with Customer Returns, Credit/Debit Memos, or Sales Orders Without Charge
solution-business-and-index.md	Working with Solution Quotations, or looking up an API by technical name