openapi: 3.1.0
info:
title: SAP S/4HANA Sales Order API
description: >-
The SAP S/4HANA Sales Order API (API_SALES_ORDER_SRV) enables you to create,
read, update, and delete sales orders in SAP S/4HANA. This OData V2-based
service provides access to complete sales order documents including header
data, line items, pricing elements, schedule lines, partners, and text
records. It supports deep insert operations for creating a sales order header
with its dependent entities in a single request. The API covers the full
sales order lifecycle from creation through to completion and rejection.
version: 1.0.0
termsOfService: https://www.sap.com/about/trust-center/agreements/cloud/cloud-services.html
contact:
name: SAP API Support
url: https://support.sap.com
license:
name: SAP Developer License
url: https://www.sap.com/about/trust-center/agreements/cloud/cloud-services.html
x-sap-api-type: OData V2
x-sap-shortText: Manage sales orders in SAP S/4HANA
servers:
- url: https://sandbox.api.sap.com/s4hanacloud/sap/opu/odata/sap/API_SALES_ORDER_SRV
description: SAP S/4HANA Cloud sandbox environment
- url: https://{host}:{port}/sap/opu/odata/sap/API_SALES_ORDER_SRV
description: SAP S/4HANA on-premise or private cloud
variables:
host:
default: my-s4hana-host.example.com
description: SAP S/4HANA server hostname
port:
default: '443'
description: SAP S/4HANA server port
security:
- basicAuth: []
- oauth2: []
tags:
- name: Partners
description: Operations on header and item partner functions
- name: Pricing Elements
description: Operations on header and item pricing elements
- name: Sales Order Items
description: Operations on sales order line items
- name: Sales Orders
description: Operations on sales order header records
- name: Schedule Lines
description: Operations on item schedule lines for delivery scheduling
- name: Text
description: Operations on header and item text records
paths:
/A_SalesOrder:
get:
operationId: listSalesOrders
summary: Sap S/4hana Retrieve a List of Sales Orders
description: >-
Returns a collection of sales order header records. Supports OData system
query options including $filter, $select, $expand, $orderby, $top, $skip,
and $inlinecount for pagination. Use $expand to include related entities
such as items, partners, and pricing elements in the response.
tags:
- Sales Orders
parameters:
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
- $ref: '#/components/parameters/orderby'
- $ref: '#/components/parameters/inlinecount'
responses:
'200':
description: Sales orders retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrder'
__count:
type: string
description: Total count of matching entities when $inlinecount=allpages is specified
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createSalesOrder
summary: Sap S/4hana Create a New Sales Order
description: >-
Creates a new sales order in SAP S/4HANA. Supports deep insert, allowing
you to create a header along with items, partners, pricing elements,
schedule lines, billing plans, and text records in a single request. The
SalesOrderType, SalesOrganization, DistributionChannel, and
OrganizationDivision are required for creation.
tags:
- Sales Orders
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SalesOrderCreate'
responses:
'201':
description: Sales order created successfully
content:
application/json:
schema:
type: object
properties:
d:
$ref: '#/components/schemas/SalesOrder'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrder('{SalesOrder}'):
get:
operationId: getSalesOrder
summary: Sap S/4hana Retrieve a Single Sales Order by Key
description: >-
Returns a single sales order header record identified by its sales order
number. Use $expand to include related entities such as to_Item,
to_Partner, and to_PricingElement.
tags:
- Sales Orders
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: Sales order retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
$ref: '#/components/schemas/SalesOrder'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateSalesOrder
summary: Sap S/4hana Update a Sales Order Header
description: >-
Performs a partial update (MERGE/PATCH) on an existing sales order header.
Only the fields provided in the request body are updated. Requires an
If-Match header with the entity ETag for optimistic concurrency control.
tags:
- Sales Orders
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/ifMatch'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SalesOrderUpdate'
responses:
'204':
description: Sales order updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'412':
$ref: '#/components/responses/PreconditionFailed'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteSalesOrder
summary: Sap S/4hana Delete a Sales Order
description: >-
Deletes an existing sales order. Requires an If-Match header with the
entity ETag for optimistic concurrency control. A sales order can only be
deleted if its processing status permits deletion.
tags:
- Sales Orders
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/ifMatch'
responses:
'204':
description: Sales order deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'412':
$ref: '#/components/responses/PreconditionFailed'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrder('{SalesOrder}')/to_Item:
get:
operationId: listSalesOrderItems
summary: Sap S/4hana Retrieve Items for a Sales Order
description: >-
Returns the line items belonging to a specific sales order. Use $expand
to include related entities such as to_PricingElement, to_ScheduleLine,
and to_Partner.
tags:
- Sales Order Items
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/top'
- $ref: '#/components/parameters/skip'
- $ref: '#/components/parameters/filter'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: Sales order items retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrderItem'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
post:
operationId: createSalesOrderItem
summary: Sap S/4hana Create a New Sales Order Item
description: >-
Creates a new line item within an existing sales order. The Material
field is typically required. Supports deep insert for creating pricing
elements, schedule lines, partners, and text along with the item.
tags:
- Sales Order Items
parameters:
- $ref: '#/components/parameters/salesOrderKey'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SalesOrderItemCreate'
responses:
'201':
description: Sales order item created successfully
content:
application/json:
schema:
type: object
properties:
d:
$ref: '#/components/schemas/SalesOrderItem'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrderItem(SalesOrder='{SalesOrder}',SalesOrderItem='{SalesOrderItem}'):
get:
operationId: getSalesOrderItem
summary: Sap S/4hana Retrieve a Single Sales Order Item
description: >-
Returns a single sales order item identified by the composite key of
SalesOrder and SalesOrderItem numbers.
tags:
- Sales Order Items
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/salesOrderItemKey'
- $ref: '#/components/parameters/select'
- $ref: '#/components/parameters/expand'
responses:
'200':
description: Sales order item retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
$ref: '#/components/schemas/SalesOrderItem'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
patch:
operationId: updateSalesOrderItem
summary: Sap S/4hana Update a Sales Order Item
description: >-
Performs a partial update on an existing sales order item. Only the fields
provided in the request body are updated. Requires an If-Match header
with the entity ETag for optimistic concurrency control.
tags:
- Sales Order Items
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/salesOrderItemKey'
- $ref: '#/components/parameters/ifMatch'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SalesOrderItemUpdate'
responses:
'204':
description: Sales order item updated successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'412':
$ref: '#/components/responses/PreconditionFailed'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
delete:
operationId: deleteSalesOrderItem
summary: Sap S/4hana Delete a Sales Order Item
description: >-
Deletes an existing sales order item. Requires an If-Match header with
the entity ETag.
tags:
- Sales Order Items
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/salesOrderItemKey'
- $ref: '#/components/parameters/ifMatch'
responses:
'204':
description: Sales order item deleted successfully
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
'412':
$ref: '#/components/responses/PreconditionFailed'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrder('{SalesOrder}')/to_Partner:
get:
operationId: listSalesOrderPartners
summary: Sap S/4hana Retrieve Partners for a Sales Order
description: >-
Returns the header-level partner functions for a sales order, such as
sold-to party, ship-to party, bill-to party, and payer.
tags:
- Partners
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/select'
responses:
'200':
description: Sales order partners retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrderHeaderPartner'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrder('{SalesOrder}')/to_PricingElement:
get:
operationId: listSalesOrderPricingElements
summary: Sap S/4hana Retrieve Header Pricing Elements for a Sales Order
description: >-
Returns the header-level pricing condition records for a sales order,
including prices, discounts, surcharges, taxes, and freight charges.
tags:
- Pricing Elements
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/select'
responses:
'200':
description: Pricing elements retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrderHeaderPrcgElmnt'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrderItem(SalesOrder='{SalesOrder}',SalesOrderItem='{SalesOrderItem}')/to_ScheduleLine:
get:
operationId: listSalesOrderItemScheduleLines
summary: Sap S/4hana Retrieve Schedule Lines for a Sales Order Item
description: >-
Returns the schedule lines for a specific sales order item, containing
confirmed quantities and delivery dates.
tags:
- Schedule Lines
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/salesOrderItemKey'
- $ref: '#/components/parameters/select'
responses:
'200':
description: Schedule lines retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrderScheduleLine'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrderItem(SalesOrder='{SalesOrder}',SalesOrderItem='{SalesOrderItem}')/to_PricingElement:
get:
operationId: listSalesOrderItemPricingElements
summary: Sap S/4hana Retrieve Pricing Elements for a Sales Order Item
description: >-
Returns the item-level pricing condition records for a sales order item,
including item prices, discounts, surcharges, and tax amounts.
tags:
- Pricing Elements
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/salesOrderItemKey'
- $ref: '#/components/parameters/select'
responses:
'200':
description: Pricing elements retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrderItemPrcgElmnt'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
/A_SalesOrder('{SalesOrder}')/to_Text:
get:
operationId: listSalesOrderTexts
summary: Sap S/4hana Retrieve Text Records for a Sales Order
description: >-
Returns the header-level text records for a sales order, such as notes,
internal comments, and header texts.
tags:
- Text
parameters:
- $ref: '#/components/parameters/salesOrderKey'
- $ref: '#/components/parameters/select'
responses:
'200':
description: Text records retrieved successfully
content:
application/json:
schema:
type: object
properties:
d:
type: object
properties:
results:
type: array
items:
$ref: '#/components/schemas/SalesOrderText'
'401':
$ref: '#/components/responses/Unauthorized'
'404':
$ref: '#/components/responses/NotFound'
x-microcks-operation:
delay: 0
dispatcher: FALLBACK
components:
securitySchemes:
basicAuth:
type: http
scheme: basic
description: Basic authentication using SAP user credentials
oauth2:
type: oauth2
description: OAuth 2.0 authentication for SAP S/4HANA Cloud
flows:
clientCredentials:
tokenUrl: https://{tenant}.authentication.{region}.hana.ondemand.com/oauth/token
scopes:
API_SALES_ORDER_SRV_0001: Access to Sales Order API
parameters:
salesOrderKey:
name: SalesOrder
in: path
required: true
description: Sales order number (10-character string, e.g., '0000000001')
schema:
type: string
maxLength: 10
salesOrderItemKey:
name: SalesOrderItem
in: path
required: true
description: Sales order item number (6-character string, e.g., '000010')
schema:
type: string
maxLength: 6
top:
name: $top
in: query
description: Maximum number of entities to return
schema:
type: integer
minimum: 0
skip:
name: $skip
in: query
description: Number of entities to skip
schema:
type: integer
minimum: 0
filter:
name: $filter
in: query
description: OData filter expression
schema:
type: string
select:
name: $select
in: query
description: Comma-separated list of properties to include in the response
schema:
type: string
expand:
name: $expand
in: query
description: Comma-separated list of navigation properties to expand
schema:
type: string
orderby:
name: $orderby
in: query
description: Comma-separated list of properties for sorting (e.g., 'CreationDate desc')
schema:
type: string
inlinecount:
name: $inlinecount
in: query
description: Include total count of matching entities
schema:
type: string
enum:
- allpages
- none
ifMatch:
name: If-Match
in: header
required: true
description: ETag value for optimistic concurrency control
schema:
type: string
schemas:
SalesOrder:
type: object
description: >-
Sales order header entity (A_SalesOrder) representing a complete sales
document in SAP S/4HANA. Contains organizational data, customer
references, pricing totals, and processing status information.
properties:
SalesOrder:
type: string
maxLength: 10
description: Sales order number
examples: ['0000000001']
SalesOrderType:
type: string
maxLength: 4
description: Sales document type (e.g., OR for standard order, RE for returns)
examples: ['OR']
SalesOrganization:
type: string
maxLength: 4
description: Sales organization responsible for the sales order
examples: ['1710']
DistributionChannel:
type: string
maxLength: 2
description: Distribution channel through which the product reaches the customer
examples: ['10']
OrganizationDivision:
type: string
maxLength: 2
description: Division for the sales organization
examples: ['00']
SalesGroup:
type: string
maxLength: 3
description: Sales group within the sales organization
example: example_value
SalesOffice:
type: string
maxLength: 4
description: Sales office responsible for the order
example: example_value
SalesDistrict:
type: string
maxLength: 6
description: Geographic sales district
example: example_value
SoldToParty:
type: string
maxLength: 10
description: Customer number of the sold-to party
examples: ['10100001']
CreationDate:
type: string
format: date
description: Date when the sales order was created
example: '2026-01-15'
CreatedByUser:
type: string
maxLength: 12
description: User who created the sales order
example: example_value
LastChangeDate:
type: string
format: date
description: Date of the last change to the sales order
example: '2026-01-15'
LastChangeDateTime:
type: string
format: date-time
description: Timestamp of the last change including time zone
example: '2026-01-15T10:30:00Z'
PurchaseOrderByCustomer:
type: string
maxLength: 35
description: Customer purchase order number
example: example_value
CustomerPurchaseOrderType:
type: string
maxLength: 4
description: Customer purchase order type
example: example_value
CustomerPurchaseOrderDate:
type: string
format: date
description: Customer purchase order date
example: '2026-01-15'
SalesOrderDate:
type: string
format: date
description: Document date of the sales order
example: '2026-01-15'
TotalNetAmount:
type: string
description: Total net value of the sales order in document currency
examples: ['15000.00']
TransactionCurrency:
type: string
maxLength: 5
description: Currency key for the sales order (ISO 4217)
examples: ['USD']
SDDocumentReason:
type: string
maxLength: 3
description: Order reason (e.g., reason for return or credit memo)
example: example_value
PricingDate:
type: string
format: date
description: Date used for pricing determination
example: '2026-01-15'
RequestedDeliveryDate:
type: string
format: date
description: Requested delivery date for the entire order
example: '2026-01-15'
ShippingCondition:
type: string
maxLength: 2
description: Shipping condition code
example: example_value
CompleteDeliveryIsDefined:
type: boolean
description: Indicator for complete delivery requirement
example: true
ShippingType:
type: string
maxLength: 2
description: Shipping type code
example: example_value
HeaderBillingBlockReason:
type: string
maxLength: 2
description: Billing block reason at header level
example: example_value
DeliveryBlockReason:
type: string
maxLength: 2
description: Delivery block reason
example: example_value
IncotermsClassification:
type: string
maxLength: 3
description: Incoterms classification (e.g., FOB, CIF, EXW)
examples: ['EXW']
IncotermsTransferLocation:
type: string
maxLength: 28
description: Incoterms location (named place)
example: example_value
IncotermsLocation1:
type: string
maxLength: 70
description: Incoterms location 1
example: example_value
IncotermsLocation2:
type: string
maxLength: 70
description: Incoterms location 2
example: example_value
IncotermsVersion:
type: string
maxLength: 4
description: Incoterms version year
example: example_value
CustomerPaymentTerms:
type: string
maxLength: 4
description: Payment terms key
examples: ['0001']
PaymentMethod:
type: string
maxLength: 1
description: Payment method code
example: example_value
AssignmentReference:
type: string
maxLength: 18
description: Assignment reference number
example: example_value
ReferenceSDDocument:
type: string
maxLength: 10
description: Reference document number (e.g., quotation or contract number)
example: example_value
ReferenceSDDocumentCategory:
type: string
maxLength: 4
description: Reference document category
example: example_value
AccountingExchangeRate:
type: string
description: Exchange rate for accounting
example: example_value
OverallSDProcessStatus:
type: string
maxLength: 1
description: Overall processing status of the sales document (A=Not yet processed, B=Partially processed, C=Completely processed)
examples: ['A']
TotalCreditCheckStatus:
type: string
maxLength: 1
description: Overall status of credit checks
example: example_value
OverallTotalDeliveryStatus:
type: string
maxLength: 1
description: Overall delivery status
example: example_value
OverallSDDocumentRejectionSts:
type: string
maxLength: 1
description: Overall rejection status of the sales document
example: example_value
BillingDocumentDate:
type: string
format: date
description: Billing date for the entire order
example: '2026-01-15'
ContractAccount:
type: string
maxLength: 12
description: Contract account number
example: example_value
AdditionalCustomerGroup1:
type: string
maxLength: 3
description: Customer group 1
example: example_value
AdditionalCustomerGroup2:
type: string
maxLength: 3
description: Customer group 2
example: example_value
AdditionalCustomerGroup3:
type: string
maxLength: 3
description: Customer group 3
example: example_value
AdditionalCustomerGroup4:
type: string
maxLength: 3
description: Customer group 4
example: example_value
AdditionalCustomerGroup5:
type: string
maxLength: 3
description: Customer group 5
example: example_value
SlsDocIsRlvtForProofOfDeliv:
type: boolean
description: Indicator that the document is relevant for proof of delivery
example: true
CustomerTaxClassification1:
type: string
maxLength: 1
description: Tax classification 1 for customer
example: example_value
CustomerTaxClassification2:
type: string
maxLength: 1
description: Tax classification 2 for customer
example: example_value
CustomerTaxClassification3:
type: string
maxLength: 1
description: Tax classification 3 for customer
example: example_value
CustomerTaxClassification4:
type: string
maxLength: 1
description: Tax classification 4 for customer
example: example_value
CustomerAccountGroup:
type: string
maxLength: 4
description: Customer account group
example: example_value
to_Item:
type: array
description: Navigation to sales order items
items:
$ref: '#/components/schemas/SalesOrderItem'
example: []
to_Partner:
type: array
description: Navigation to header partner functions
items:
$ref: '#/components/schemas/SalesOrderHeaderPartner'
example: []
to_PricingElement:
type: array
description: Navigation to header pricing elements
items:
$ref: '#/components/schemas/SalesOrderHeaderPrcgElmnt'
example: []
to_Text:
type: array
description: Navigation to header text records
items:
$ref: '#/components/schemas/SalesOrderText'
example: []
SalesOrderCreate:
type: object
description: Request payload for creating a new sales order with optional deep insert
required:
- SalesOrderType
- SalesOrganization
- DistributionChannel
- OrganizationDivision
properties:
SalesOrderType:
type: string
maxLength: 4
description: Sales document type
example: example_value
SalesOrganization:
type: string
# --- truncated at 32 KB (65 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sap-s4hana/refs/heads/main/openapi/sap-s4hana-sales-order-openapi.yml