SAP S/4HANA Sales Orders API

openapi: 3.1.0
info:
  title: SAP S/4HANA Sales Order Partners Sales Orders 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: Sales Orders
  description: Operations on sales order header 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
components:
  parameters:
    expand:
      name: $expand
      in: query
      description: Comma-separated list of navigation properties to expand
      schema:
        type: string
    inlinecount:
      name: $inlinecount
      in: query
      description: Include total count of matching entities
      schema:
        type: string
        enum:
        - allpages
        - none
    filter:
      name: $filter
      in: query
      description: OData filter expression
      schema:
        type: string
    ifMatch:
      name: If-Match
      in: header
      required: true
      description: ETag value for optimistic concurrency control
      schema:
        type: string
    top:
      name: $top
      in: query
      description: Maximum number of entities to return
      schema:
        type: integer
        minimum: 0
    select:
      name: $select
      in: query
      description: Comma-separated list of properties to include in the response
      schema:
        type: string
    salesOrderKey:
      name: SalesOrder
      in: path
      required: true
      description: Sales order number (10-character string, e.g., '0000000001')
      schema:
        type: string
        maxLength: 10
    skip:
      name: $skip
      in: query
      description: Number of entities to skip
      schema:
        type: integer
        minimum: 0
    orderby:
      name: $orderby
      in: query
      description: Comma-separated list of properties for sorting (e.g., 'CreationDate desc')
      schema:
        type: string
  schemas:
    ODataError:
      type: object
      description: OData error response envelope
      properties:
        error:
          type: object
          properties:
            code:
              type: string
              description: SAP error code
            message:
              type: object
              properties:
                lang:
                  type: string
                  description: Language of the error message
                value:
                  type: string
                  description: Human-readable error message
            innererror:
              type: object
              description: Additional error details
              properties:
                application:
                  type: object
                  properties:
                    component_id:
                      type: string
                    service_namespace:
                      type: string
                    service_id:
                      type: string
                    service_version:
                      type: string
                transactionid:
                  type: string
                timestamp:
                  type: string
                errordetails:
                  type: array
                  items:
                    type: object
                    properties:
                      code:
                        type: string
                      message:
                        type: string
                      severity:
                        type: string
          example: example_value
    SalesOrderItemCreate:
      type: object
      description: Request payload for creating a new sales order item
      properties:
        Material:
          type: string
          maxLength: 40
          description: Material number
          example: example_value
        RequestedQuantity:
          type: string
          description: Requested quantity
          example: example_value
        RequestedQuantityUnit:
          type: string
          maxLength: 3
          description: Unit of measure
          example: example_value
        Plant:
          type: string
          maxLength: 4
          description: Plant
          example: example_value
        SalesOrderItemCategory:
          type: string
          maxLength: 4
          description: Item category
          example: example_value
        SalesOrderItemText:
          type: string
          maxLength: 40
          description: Item description
          example: example_value
        PurchaseOrderByCustomer:
          type: string
          maxLength: 35
          description: Customer PO number at item level
          example: example_value
        PricingDate:
          type: string
          format: date
          description: Pricing date
          example: '2026-01-15'
        CustomerPaymentTerms:
          type: string
          maxLength: 4
          description: Payment terms
          example: example_value
        MaterialByCustomer:
          type: string
          maxLength: 35
          description: Customer material number
          example: example_value
        Batch:
          type: string
          maxLength: 10
          description: Batch number
          example: example_value
        ProductionPlant:
          type: string
          maxLength: 4
          description: Production plant
          example: example_value
        StorageLocation:
          type: string
          maxLength: 4
          description: Storage location
          example: example_value
        DeliveryPriority:
          type: string
          maxLength: 2
          description: Delivery priority
          example: example_value
        IncotermsClassification:
          type: string
          maxLength: 3
          description: Incoterms classification
          example: example_value
        IncotermsTransferLocation:
          type: string
          maxLength: 28
          description: Incoterms location
          example: example_value
        to_PricingElement:
          type: array
          description: Pricing elements (deep insert)
          items:
            $ref: '#/components/schemas/SalesOrderItemPrcgElmnt'
          example: []
        to_ScheduleLine:
          type: array
          description: Schedule lines (deep insert)
          items:
            $ref: '#/components/schemas/SalesOrderScheduleLine'
          example: []
        to_Partner:
          type: array
          description: Partners (deep insert)
          items:
            $ref: '#/components/schemas/SalesOrderItemPartner'
          example: []
        to_Text:
          type: array
          description: Text records (deep insert)
          items:
            $ref: '#/components/schemas/SalesOrderItemText'
          example: []
    SalesOrderText:
      type: object
      description: Sales order header text entity (A_SalesOrderText) for long texts associated with the sales order header.
      properties:
        SalesOrder:
          type: string
          maxLength: 10
          description: Sales order number
          example: example_value
        Language:
          type: string
          maxLength: 2
          description: Language key (ISO 639-1)
          example: example_value
        LongTextID:
          type: string
          maxLength: 4
          description: Text ID (e.g., 0001 for header note)
          example: '500123'
        LongText:
          type: string
          description: Text content
          example: example_value
    SalesOrderUpdate:
      type: object
      description: Request payload for updating sales order header fields
      properties:
        PurchaseOrderByCustomer:
          type: string
          maxLength: 35
          example: example_value
        RequestedDeliveryDate:
          type: string
          format: date
          example: '2026-01-15'
        CustomerPaymentTerms:
          type: string
          maxLength: 4
          example: example_value
        ShippingCondition:
          type: string
          maxLength: 2
          example: example_value
        CompleteDeliveryIsDefined:
          type: boolean
          example: true
        HeaderBillingBlockReason:
          type: string
          maxLength: 2
          example: example_value
        DeliveryBlockReason:
          type: string
          maxLength: 2
          example: example_value
        IncotermsClassification:
          type: string
          maxLength: 3
          example: example_value
        IncotermsTransferLocation:
          type: string
          maxLength: 28
          example: example_value
        PricingDate:
          type: string
          format: date
          example: '2026-01-15'
        SDDocumentReason:
          type: string
          maxLength: 3
          example: example_value
    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: []
    SalesOrderItemPrcgElmnt:
      type: object
      description: Sales order item pricing element entity (A_SalesOrderItemPrcgElmnt) representing a pricing condition at the item level.
      properties:
        SalesOrder:
          type: string
          maxLength: 10
          description: Sales order number
          example: example_value
        SalesOrderItem:
          type: string
          maxLength: 6
          description: Sales order item number
          example: example_value
        PricingProcedureStep:
          type: string
          maxLength: 3
          description: Step number in the pricing procedure
          example: example_value
        PricingProcedureCounter:
          type: string
          maxLength: 3
          description: Counter for condition within a step
          example: example_value
        ConditionType:
          type: string
          maxLength: 4
          description: Condition type
          example: example_value
        ConditionRateValue:
          type: string
          description: Condition rate
          example: example_value
        ConditionCurrency:
          type: string
          maxLength: 5
          description: Condition currency
          example: example_value
        ConditionQuantity:
          type: string
          description: Condition quantity
          example: example_value
        ConditionQuantityUnit:
          type: string
          maxLength: 3
          description: Condition quantity unit
          example: example_value
        ConditionAmount:
          type: string
          description: Condition value
          example: example_value
        TransactionCurrency:
          type: string
          maxLength: 5
          description: Document currency
          example: example_value
        ConditionCategory:
          type: string
          maxLength: 1
          description: Condition category
          example: example_value
        ConditionIsForStatistics:
          type: boolean
          description: Statistical condition
          example: true
        ConditionOrigin:
          type: string
          maxLength: 1
          description: Origin of the condition
          example: example_value
        IsGroupCondition:
          type: string
          maxLength: 1
          description: Group condition indicator
          example: example_value
        ConditionControl:
          type: string
          maxLength: 1
          description: Condition control
          example: example_value
        ConditionInactiveReason:
          type: string
          maxLength: 1
          description: Reason for inactivity
          example: example_value
        ConditionClass:
          type: string
          maxLength: 1
          description: Condition class
          example: example_value
        ConditionIsManuallyChanged:
          type: boolean
          description: Manually changed indicator
          example: true
    SalesOrderItemText:
      type: object
      description: Sales order item text entity (A_SalesOrderItemText) for long texts associated with a sales order item.
      properties:
        SalesOrder:
          type: string
          maxLength: 10
          description: Sales order number
          example: example_value
        SalesOrderItem:
          type: string
          maxLength: 6
          description: Sales order item number
          example: example_value
        Language:
          type: string
          maxLength: 2
          description: Language key (ISO 639-1)
          example: example_value
        LongTextID:
          type: string
          maxLength: 4
          description: Text ID
          example: '500123'
        LongText:
          type: string
          description: Text content
          example: example_value
    SalesOrderItemPartner:
      type: object
      description: Sales order item partner entity (A_SalesOrderItemPartner) representing a business partner in a specific function role at the item level.
      properties:
        SalesOrder:
          type: string
          maxLength: 10
          description: Sales order number
          example: example_value
        SalesOrderItem:
          type: string
          maxLength: 6
          description: Sales order item number
          example: example_value
        PartnerFunction:
          type: string
          maxLength: 2
          description: Partner function code
          example: example_value
        Customer:
          type: string
          maxLength: 10
          description: Customer number
          example: example_value
        Supplier:
          type: string
          maxLength: 10
          description: Supplier number
          example: example_value
    SalesOrderScheduleLine:
      type: object
      description: Sales order schedule line entity (A_SalesOrderScheduleLine) representing a delivery schedule for a sales order item with confirmed quantities and dates from availability check (ATP).
      properties:
        SalesOrder:
          type: string
          maxLength: 10
          description: Sales order number
          example: example_value
        SalesOrderItem:
          type: string
          maxLength: 6
          description: Sales order item number
          example: example_value
        ScheduleLine:
          type: string
          maxLength: 4
          description: Schedule line number
          example: example_value
        RequestedDeliveryDate:
          type: string
          format: date
          description: Requested delivery date
          example: '2026-01-15'
        ConfirmedDeliveryDate:
          type: string
          format: date
          description: Confirmed delivery date from ATP check
          example: '2026-01-15'
        OrderQuantityUnit:
          type: string
          maxLength: 3
          description: Order quantity unit
          example: example_value
        OrderQuantitySAPUnit:
          type: string
          maxLength: 3
          description: SAP internal unit of measure
          example: example_value
        ScheduleLineOrderQuantity:
          type: string
          description: Ordered quantity on the schedule line
          example: example_value
        ConfdOrderQtyByMatlAvailCheck:
          type: string
          description: Confirmed quantity from material availability check
          example: example_value
        DeliveredQtyInOrderQtyUnit:
          type: string
          description: Delivered quantity in order unit
          example: example_value
        OpenConfdDelivQtyInOrdQtyUnit:
          type: string
          description: Open 

# --- truncated at 32 KB (51 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/sap-s4hana/refs/heads/main/openapi/sap-s4hana-sales-orders-api-openapi.yml