SAP Ariba Purchase Orders API

openapi: 3.1.0
info:
  title: SAP Ariba Procurement Invoices Purchase Orders API
  description: Enables integration with SAP Ariba procurement processes including purchase orders, invoices, requisitions, receipts, and supplier management across the SAP Business Network. This API supports the complete procure-to-pay lifecycle from requisition creation through invoice reconciliation and payment processing.
  version: 1.0.0
  contact:
    name: SAP Ariba API Support
    url: https://developer.ariba.com
    email: support@ariba.com
  license:
    name: SAP Developer License
    url: https://www.sap.com/about/legal/developer-license.html
  termsOfService: https://www.ariba.com/legal/terms-of-use
  x-sap-api-type: REST
  x-sap-shortText: Procurement API for purchase orders, invoices, and suppliers
  x-sap-stateInfo:
    state: Active
  x-documentation:
  - url: https://help.sap.com/docs/ariba-apis
    description: SAP Help Portal - Ariba APIs
  - url: https://api.sap.com/package/SAPAribaOpenAPIs/rest
    description: SAP Business Accelerator Hub
  - url: https://help.sap.com/docs/ariba-apis/operational-reporting-api-for-procurement/operational-reporting-api-for-procurement
    description: Operational Reporting API for Procurement
servers:
- url: https://openapi.ariba.com/api/procurement/v1
  description: SAP Ariba Production API Server
- url: https://sandbox.ariba.com/api/procurement/v1
  description: SAP Ariba Sandbox API Server
security:
- oauth2: []
tags:
- name: Purchase Orders
  description: Create, retrieve, update, and manage purchase orders across the SAP Ariba Network. Supports standard and service purchase orders including new, change, cancel, and close operations.
paths:
  /orders:
    get:
      operationId: listPurchaseOrders
      summary: List Purchase Orders
      description: Retrieves a paginated list of purchase order headers matching the specified filter criteria. Supports filtering by buyer, supplier, date range, status, and other order attributes. Results are returned with pagination support using skip and limit parameters.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/SkipParam'
      - $ref: '#/components/parameters/LimitParam'
      - name: filter
        in: query
        description: 'OData-style filter expression to narrow results. Supports operators eq, ne, gt, lt, ge, le with the case-sensitive ''and'' operator. Example: orderDate ge ''2025-01-01'' and status eq ''Ordered'''
        required: false
        schema:
          type: string
      - name: orderBy
        in: query
        description: Field name to sort results by, with optional asc or desc direction
        required: false
        schema:
          type: string
      - name: supplierId
        in: query
        description: Filter by supplier AN-ID on the SAP Ariba Network
        required: false
        schema:
          type: string
      - name: buyerId
        in: query
        description: Filter by buyer AN-ID on the SAP Ariba Network
        required: false
        schema:
          type: string
      - name: status
        in: query
        description: Filter by purchase order status
        required: false
        schema:
          $ref: '#/components/schemas/PurchaseOrderStatus'
      - name: fromDate
        in: query
        description: Filter orders created on or after this date (ISO 8601 format YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
      - name: toDate
        in: query
        description: Filter orders created on or before this date (ISO 8601 format YYYY-MM-DD)
        required: false
        schema:
          type: string
          format: date
      responses:
        '200':
          description: Successfully retrieved list of purchase orders
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrderListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    post:
      operationId: createPurchaseOrder
      summary: Create a Purchase Order
      description: Creates a new purchase order in the SAP Ariba system. The order must include header information, at least one line item, supplier details, and shipping address. Upon successful creation, the purchase order is transmitted through the Ariba Network to the designated supplier.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseOrderCreate'
      responses:
        '201':
          description: Purchase order created successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
          headers:
            Location:
              description: URI of the newly created purchase order
              schema:
                type: string
                format: uri
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '409':
          description: Conflict - duplicate order number or business rule violation
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity - validation error in order data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderId}:
    get:
      operationId: getPurchaseOrder
      summary: Get a Purchase Order
      description: Retrieves the complete details of a specific purchase order including header information, all line items, accounting assignments, shipping addresses, and current status. The orderId corresponds to the unique purchase order identifier (UniqueName) in SAP Ariba.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/OrderIdParam'
      responses:
        '200':
          description: Successfully retrieved purchase order details
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
    patch:
      operationId: updatePurchaseOrder
      summary: Update a Purchase Order
      description: Updates an existing purchase order with change request information. Supports modifications to line items, quantities, prices, delivery dates, and shipping addresses. Creates a new version of the purchase order and increments the version number. Change requests are transmitted to the supplier through the Ariba Network.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/OrderIdParam'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PurchaseOrderUpdate'
      responses:
        '200':
          description: Purchase order updated successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - order is in a state that does not allow modification
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '422':
          description: Unprocessable entity - validation error in update data
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
  /orders/{orderId}/cancel:
    post:
      operationId: cancelPurchaseOrder
      summary: Cancel a Purchase Order
      description: Cancels an existing purchase order and notifies the supplier through the Ariba Network. Only orders in Ordered or Confirmed status can be cancelled. Cancellation creates a new version with cancelled status.
      tags:
      - Purchase Orders
      parameters:
      - $ref: '#/components/parameters/RealmParam'
      - $ref: '#/components/parameters/OrderIdParam'
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                reason:
                  type: string
                  description: Reason for cancellation
                  maxLength: 1000
      responses:
        '200':
          description: Purchase order cancelled successfully
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PurchaseOrder'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          description: Conflict - order cannot be cancelled in its current state
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      x-microcks-operation:
        delay: 0
        dispatcher: FALLBACK
components:
  schemas:
    AccountingInfo:
      type: object
      description: Accounting assignment information for cost allocation on purchase order line items
      properties:
        costCenter:
          type: string
          description: Cost center identifier for expenditure allocation
          example: example_value
        generalLedger:
          type: string
          description: General ledger account number
          example: example_value
        asset:
          type: string
          description: Fixed asset number
          example: example_value
        internalOrder:
          type: string
          description: Internal order number
          example: example_value
        wbsElement:
          type: string
          description: Work Breakdown Structure element
          example: example_value
        amount:
          $ref: '#/components/schemas/Money'
        percentage:
          type: number
          format: double
          description: Percentage of line item amount allocated to this accounting assignment
          minimum: 0
          maximum: 100
          example: 42.5
        sapDistributionFlag:
          type: string
          description: SAP distribution indicator flag
          example: example_value
        accountCategory:
          type: string
          description: Account assignment category code for the line item expenditure
          example: example_value
    Money:
      type: object
      description: Monetary amount with currency code following ISO 4217
      required:
      - amount
      - currencyCode
      properties:
        amount:
          type: number
          format: double
          description: The monetary value
          examples:
          - 1250.0
        currencyCode:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
          examples:
          - USD
          - EUR
          - GBP
    Address:
      type: object
      description: Postal address structure used for shipping, billing, and company addresses
      properties:
        name:
          type: string
          description: Addressee name or attention line
          example: Example Title
        lines:
          type: string
          description: Street address lines
          example: example_value
        city:
          type: string
          description: City name
          example: example_value
        state:
          type: string
          description: State or province
          example: example_value
        postalCode:
          type: string
          description: Postal or ZIP code
          example: example_value
        country:
          type: string
          description: Country code (ISO 3166-1 alpha-2)
          pattern: ^[A-Z]{2}$
          example: example_value
        phone:
          type: string
          description: Phone number
          example: example_value
        email:
          type: string
          format: email
          description: Email address
          example: user@example.com
    ErrorResponse:
      type: object
      description: Standard error response structure
      required:
      - error
      properties:
        error:
          type: object
          required:
          - code
          - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              examples:
              - INVALID_REQUEST
              - RESOURCE_NOT_FOUND
              - UNAUTHORIZED
            message:
              type: string
              description: Human-readable error message
            details:
              type: array
              description: Additional error details
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: Field name that caused the error (for validation errors)
                  message:
                    type: string
                    description: Detail message for this specific issue
                  errorNumber:
                    type: string
                    description: SAP error number
                  errorModule:
                    type: string
                    description: SAP module where the error originated
          example: example_value
    SupplierReference:
      type: object
      description: Reference to a supplier on the SAP Ariba Network
      required:
      - supplierId
      properties:
        supplierId:
          type: string
          description: Supplier unique identifier (AN-ID on the Ariba Network or internal supplier number)
          examples:
          - AN01000000001
        name:
          type: string
          description: Supplier company name
          example: Example Title
        erpSupplierId:
          type: string
          description: Supplier number in the ERP system
          example: '500123'
    PurchaseOrderListResponse:
      type: object
      description: Paginated list of purchase orders
      properties:
        totalCount:
          type: integer
          description: Total number of matching records
          example: 10
        skip:
          type: integer
          description: Number of records skipped
          example: 10
        limit:
          type: integer
          description: Maximum records per page
          example: 10
        orders:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseOrder'
          example: []
    UnitOfMeasure:
      type: object
      description: Unit of measure specification following UN/ECE Recommendation 20 standard codes
      required:
      - code
      properties:
        code:
          type: string
          description: Unit of measure code (UN/ECE Rec 20 or SAP Ariba internal code)
          examples:
          - EA
          - KG
          - PC
          - HR
        description:
          type: string
          description: Human-readable description of the unit
          examples:
          - Each
          - Kilogram
          - Piece
          - Hour
    PurchaseOrderCreate:
      type: object
      description: Request body for creating a new purchase order
      required:
      - supplier
      - currency
      - lineItems
      properties:
        erpPONumber:
          type: string
          description: ERP system purchase order number
          example: example_value
        supplier:
          $ref: '#/components/schemas/SupplierReference'
        currency:
          type: string
          description: ISO 4217 currency code
          pattern: ^[A-Z]{3}$
          example: example_value
        paymentTerms:
          $ref: '#/components/schemas/PaymentTerms'
        purchaseOrg:
          type: string
          description: Purchasing organization identifier
          example: example_value
        purchaseGroup:
          type: string
          description: Purchasing group identifier
          example: example_value
        companyCode:
          type: string
          description: Company code
          example: example_value
        shipTo:
          $ref: '#/components/schemas/Address'
        billTo:
          $ref: '#/components/schemas/Address'
        lineItems:
          type: array
          items:
            $ref: '#/components/schemas/PurchaseOrderLineItem'
          minItems: 1
          example: []
        requisitionId:
          type: string
          description: Reference to originating requisition
          example: '500123'
        contractId:
          type: string
          description: Reference to master agreement
          example: '500123'
        comments:
          type: string
          description: Header-level comments
          example: example_value
    PaymentTerms:
      type: object
      description: Payment terms governing when and how invoices should be paid
      properties:
        code:
          type: string
          description: Payment terms code
          examples:
          - NET30
          - NET60
          - 2/10NET30
        description:
          type: string
          description: Human-readable payment terms description
          example: A sample description.
        netDays:
          type: integer
          description: Number of days until payment is due
          example: 10
        discountPercent:
          type: number
          format: double
          description: Early payment discount percentage
          example: 42.5
        discountDays:
          type: integer
          description: Number of days within which discount applies
          example: 10
    TaxDetail:
      type: object
      description: Tax calculation details for an invoice or line item
      properties:
        taxCode:
          type: string
          description: Tax code identifier
          example: example_value
        taxCategory:
          type: string
          description: Tax category (e.g., VAT, GST, Sales Tax)
          example: example_value
        taxRate:
          type: number
          format: double
          description: Tax rate as a percentage
          minimum: 0
          example: 42.5
        taxAmount:
          $ref: '#/components/schemas/Money'
        taxableAmount:
          $ref: '#/components/schemas/Money'
        description:
          type: string
          description: Description of the tax
          example: A sample description.
    BuyerReference:
      type: object
      description: Reference to a buyer organization
      properties:
        buyerId:
          type: string
          description: Buyer AN-ID on the SAP Ariba Network
          example: '500123'
        name:
          type: string
          description: Buyer organization name
          example: Example Title
        erpBuyerId:
          type: string
          description: Buyer identifier in the ERP system
          example: '500123'
    PurchaseOrderStatus:
      type: string
      description: Status of a purchase order in the procurement lifecycle
      enum:
      - Draft
      - Submitted
      - Ordered
      - Confirmed
      - PartiallyReceived
      - Received
      - PartiallyInvoiced
      - Invoiced
      - Cancelled
      - Closed
      - Rejected
    CommodityCode:
      type: object
      description: UNSPSC commodity classification code
      required:
      - code
      properties:
        code:
          type: string
          description: UNSPSC commodity code
          examples:
          - '43211500'
        description:
          type: string
          description: Commodity description
          examples:
          - Computers
        domain:
          type: string
          description: Classification domain identifier
          default: UNSPSC
          example: example_value
    PurchaseOrderLineItem:
      type: object
      description: A line item within a purchase order representing a specific good or service being procured
      required:
      - numberOnPO
      - description
      - quantity
      - unitPrice
      - unitOfMeasure
      properties:
        numberOnPO:
          type: string
          description: Line item number within the purchase order. Unique within the order.
          example: example_value
        description:
          type: string
          description: Description of the item or service being purchased
          example: A sample description.
        quantity:
          type: number
          format: double
          description: Quantity to purchase
          minimum: 0
          example: 42.5
        unitPrice:
          $ref: '#/components/schemas/Money'
        unitOfMeasure:
          $ref: '#/components/schemas/UnitOfMeasure'
        netAmount:
          $ref: '#/components/schemas/Money'
        commodityCode:
          $ref: '#/components/schemas/CommodityCode'
        buyerPartNumber:
          type: string
          description: Buyer-assigned part or material number
          example: example_value
        supplierPartNumber:
          type: string
          description: Supplier-assigned part or catalog number
          example: example_value
        manufacturerPartId:
          type: string
          description: Manufacturer part identifier
          example: '500123'
        manufacturerName:
          type: string
          description: Name of the manufacturer
          example: example_value
        itemCategory:
          type: string
          description: Item category code distinguishing material, service, or other item types
          example: example_value
        accountCategory:
          type: string
          description: Account assignment category for the line item expenditure
          example: example_value
        needByDate:
          type: string
          format: date
          description: Requested delivery date for the line item (ISO 8601 YYYY-MM-DD)
          example: '2026-01-15'
        shipTo:
          $ref: '#/components/schemas/Address'
        accountings:
          type: array
          description: Split accounting assignments for distributing costs across multiple cost objects
          items:
            $ref: '#/components/schemas/AccountingInfo'
          example: []
        receivingType:
          type: integer
          description: Receiving type value indicating how receipts should be processed for this line item
          example: 10
        taxCode:
          type: string
          description: Tax code per evaluated receipt settlement agreements
          example: example_value
        taxDetail:
          $ref: '#/components/schemas/TaxDetail'
        itemOnRequisition:
          type: string
          description: Line number of the corresponding item in the originating requisition
          example: example_value
        serviceStartDate:
          type: string
          format: date
          description: Service period start date (for service line items)
          example: '2026-01-15'
        serviceEndDate:
          type: string
          format: date
          description: Service period end date (for service line items)
          example: '2026-01-15'
        comments:
          type: string
          description: Additional comments or notes on the line item
          example: example_value
    PurchaseOrder:
      type: object
      description: A complete purchase order document representing a buyer's commitment to purchase goods or services from a supplier through the SAP Ariba Network
      required:
      - orderId
      - orderDate
      - supplier
      - currency
      - lineItems
      properties:
        orderId:
          type: string
          description: Unique purchase order identifier (UniqueName) including version
          examples:
          - PO-2025-001234
        erpPONumber:
          type: string
          description: ERP system purchase order number. Unique ID for every version of the purchase order in the backend ERP system.
          example: example_value
        versionNumber:
          type: integer
          description: Supplemental version number of the order. Incremented with each change request.
          minimum: 1
          example: 10
        orderDate:
          type: string
          format: date-time
          description: Date and time when the purchase order was created
          example: '2026-01-15T10:30:00Z'
        status:
          $ref: '#/components/schemas/PurchaseOrderStatus'
        orderMethodCategory:
          type: string
          description: Ordering method category indicating how the order was generated (e.g., manual, automatic, blanket release)
          example: example_value
        supplier:
          $ref: '#/components/schemas/SupplierReference'
        buyer:
          $ref: '#/components/schemas/BuyerReference'
        currency:
          type: string
          description: ISO 4217 currency code for the order
          pattern: ^[A-Z]{3}$
          example: example_value
        totalAmount:
          $ref: '#/components/schemas/Money'
        taxAmount:
          $ref: '#/components/schemas/Money'
        shippingAmount:
          $ref: '#/components/schemas/Money'
        paymentTerms:
          $ref: '#/components/schemas/PaymentTerms'
        purchaseOrg:
          type: string
          description: Purchasing organization identifier
          example: example_value
        purchaseGroup:
          type: string
          description: Purchasing group identifier
          example: example_value
        companyCode:
          type: string
          description: Company code for the buying entity
          example: example_value
        shipTo:
          $ref: '#/components/schemas/Address'
        billTo:
          $ref: '#/components/schemas/Address'
        lineItems:
          type: array
          description: Line items contained in the purchase order
          items:
            $ref: '#/components/schemas/PurchaseOrderLineItem'
          minItems: 1
          example: []
        requisitionId:
          type: string
          description: Reference to the originating purchase requisition
          example: '500123'
        contractId:
          type: string
          description: Reference to a master agreement or contract
          example: '500123'
        comments:
          type: string
          description: Header-level comments on the purchase order
          example: example_value
        createdDate:
          type: string
          format: date-time
          description: Timestamp when the order was first created
          example: '2026-01-15T10:30:00Z'
        lastModifiedDate:
          type: string
          format: date-time
          description: Timestamp of the most recent modification
          example: '2026-01-15T10:30:00Z'
        closedDate:
          type: string
          format: date-time
          description: Timestamp when the order was closed
          example: '2026-01-15T10:30:00Z'
    PurchaseOrderUpdate:
      type: object
      description: Request body for updating an existing purchase order. Only provided fields will be modified.
      properties:
        lineItems:
          type: array
          description: Updated line items
          items:
            $ref: '#/components/schemas/PurchaseOrderLineItem'
          example: []
        shipTo:
          $ref: '#/components/schemas/Address'
        paymentTerms:
          $ref: '#/components/schemas/PaymentTerms'
        comments:
          type: string
          description: Change request comments
          example: example_value
  parameters:
    OrderIdParam:
      name: orderId
      in: path
      description: Unique purchase order identifier (UniqueName). This is the purchase order number with its version, or the ERP PO number (ERPPONumber).
      required: true
      schema:
        type: string
    SkipParam:
      name: skip
      in: query
      description: Number of records to skip for pagination (default 0)
      required: false
      schema:
        type: integer
        minimum: 0
        default: 0
    RealmParam:
      name: realm
      in: query
      description: The SAP Ariba realm identifier for the buyer organization. This is the unique site name assigned during provisioning.
      required: true
      schema:
        type: string
    LimitParam:
      name: limit
      in: query
      description: Maximum number of records to return per page (default 10, max 100)
      required: false
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 10
  responses:
    NotFound:
      description: Resource not found
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    InternalServerError:
      description: Internal server error
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Forbidden:
      description: Forbidden - insufficient permissions for the requested operation
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    Unauthorized:
      description: Unauthorized - invalid or missing authentication credentials
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    TooManyRequests:
      description: Rate limit exceeded. Retry after the duration specified in the Retry-After header.
      headers:
        Retry-After:
          description: Number of seconds to wait before retrying
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
    BadRequest:
      description: Bad request - invalid parameters or malformed request
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
  securitySchemes:
    oauth2:
      type: oauth2
      description: OAuth 2.0 Client Credentials flow for SAP Ariba API authentication. Obtain client credentials from the SAP Ariba Developer Portal.
      flows:
        clientCredentials:
          tokenUrl: https://api.ariba.com/v2/oauth/token
          scopes: {}